@hyperfrontend/ui-utils/selector

selector

CSS-selector builder, validators, and DOM-query shortcuts that produce safer selectors than ad-hoc string concatenation.

CssSelector is a fluent builder for composing selectors out of tag, id, class, and attribute parts; the validator family (validateCssName, validateStringArgument, validateIdSelector, validateClassSelector, validateAttributeSelector, isValidCssSelector) rejects inputs that would produce malformed or surprising selectors before they reach the DOM. The query helpers (select, selectBy, selectByElement, selectAllElements, selectById, selectByClass, selectByAttribute) wrap querySelector / querySelectorAll so callers don't have to repeat the boilerplate or remember the typed return shapes.

API Reference§

ƒ Functions

§function

isValidCssSelector(selector: string): boolean

Validates whether a string is a valid CSS selector by attempting to query with it.

Parameters

Name	Type	Description
§selector	`string`	The CSS selector string to validate

Returns

boolean

True if the selector is valid, false otherwise

Example

Validating CSS selectors

isValidCssSelector('.my-class')
// => true

isValidCssSelector('#header nav > ul')
// => true

isValidCssSelector('[invalid')
// => false

View source →

§function

select(): CssSelector

Creates a new empty CSS selector builder.

Returns

CssSelector

A new CssSelector instance

Example

Creating empty selector

const selector = select().class('active').id('panel')
selector.toString() // => '.active#panel'

View source →

§function

selectAllElements(): CssSelector

Creates a CSS selector builder for the universal selector (*).

Returns

CssSelector

A new CssSelector instance that matches all elements

Example

Selecting all elements

const selector = selectAllElements().class('visible')
selector.toString() // => '*.visible'

View source →

§function

selectBy(selector: string): CssSelector

Creates a CSS selector builder initialized with the given selector string.

Parameters

Name	Type	Description
§selector	`string`	The initial CSS selector string

Returns

CssSelector

A new CssSelector instance

Example

Creating selector from string

const selector = selectBy('article').class('featured')
selector.toString() // => 'article.featured'

View source →

§function

selectByAttribute(attribute: string, value?: string): CssSelector

Creates a CSS selector builder for elements with a specific attribute.

Parameters

Name	Type	Description
§attribute	`string`	The attribute name to select
§value?	`string`	Optional attribute value to match

Returns

CssSelector

A new CssSelector instance

Example

Selecting by attribute

selectByAttribute('disabled').toString() // => '[disabled]'
selectByAttribute('data-role', 'button').toString() // => '[data-role="button"]'

View source →

§function

selectByClass(className: string): CssSelector

Creates a CSS selector builder for elements with a specific class name.

Parameters

Name	Type	Description
§className	`string`	The class name to select

Returns

CssSelector

A new CssSelector instance

Example

Selecting by class

const selector = selectByClass('highlighted')
selector.toString() // => '.highlighted'

View source →

§function

selectByElement(tagName: unknown): CssSelector

Creates a CSS selector builder for a specific HTML element tag name.

Parameters

Name	Type	Description
§tagName	`unknown`	The HTML tag name to select

Returns

CssSelector

A new CssSelector instance

Example

Selecting by element tag

const selector = selectByElement('button').class('primary')
selector.toString() // => 'button.primary'

View source →

§function

selectById(id: string): CssSelector

Creates a CSS selector builder for an element with a specific ID.

Parameters

Name	Type	Description
§id	`string`	The ID to select

Returns

CssSelector

A new CssSelector instance

Example

Selecting by ID

const selector = selectById('main-content')
selector.toString() // => '#main-content'

View source →

§function

validateAttributeSelector(attribute: string): void

Validates that an attribute name is valid for CSS attribute selectors. Attribute names cannot contain spaces, quotes, angle brackets, or equals signs.

Parameters

Name	Type	Description
§attribute	`string`	The attribute name to validate

Example

Validating attribute selector

validateAttributeSelector('data-testid') // passes
validateAttributeSelector('attr=value') // throws Error

View source →

§function

validateClassSelector(className: string): void

Validates that a class name follows CSS naming conventions.

Parameters

Name	Type	Description
§className	`string`	The class name to validate

Example

Validating class selector

validateClassSelector('btn-primary') // passes
validateClassSelector('1invalid') // throws Error

View source →

§function

validateCssName(arg: string, argName: string): void

Validates that a CSS name follows proper naming conventions. CSS names must start with a letter and contain only alphanumeric characters, underscores, or hyphens.

Parameters

Name	Type	Description
§arg	`string`	The CSS name to validate
§argName	`string`	The name of the argument (used in error messages)

Example

Validating CSS name format

validateCssName('my-class', 'className') // passes
validateCssName('123invalid', 'className') // throws Error

View source →

§function

validateIdSelector(id: string): void

Validates that an ID selector follows CSS naming conventions.

Parameters

Name	Type	Description
§id	`string`	The ID to validate

Example

Validating ID selector

validateIdSelector('main-header') // passes
validateIdSelector('') // throws Error

View source →

§function

validateStringArgument(arg: string, argName: string): void

Validates that a string argument is not undefined, null, or empty.

Parameters

Name	Type	Description
§arg	`string`	The string to validate
§argName	`string`	The name of the argument (used in error messages)

Example

Validating string arguments

validateStringArgument('valid', 'name') // passes
validateStringArgument('', 'name') // throws Error
validateStringArgument('   ', 'name') // throws Error (whitespace only)

View source →

◇ Classes

§class

CssSelector

Builder class for constructing CSS selectors with a fluent API.

Constructor

§new CssSelector(selector: string)

Starts a selector from a base, usually a tag name or the universal *.
The base is taken as written, neither validated nor escaped, so it may already be a complete selector that the builder methods then extend.

Parameters

Name	Type	Description
§selector	`string`	The initial selector text

Methods

§readonly active(): CssSelector

Appends the :active pseudo-class to the selector.

Returns

CssSelector

The CssSelector instance for method chaining

§readonly attribute(attribute: string, value?: string): CssSelector

Appends an attribute selector to the current selector.
Backslashes and double quotes in the value are escaped, so any value produces a selector the DOM accepts. An empty string matches an empty attribute rather than mere presence.

Parameters

Name	Type	Description
§attribute	`string`	The attribute name to select
§value?	`string`	Optional attribute value to match

Returns

CssSelector

The CssSelector instance for method chaining

§readonly childOf(parentSelector: CssSelector): CssSelector

Creates a child selector (> combinator) with this selector as the child.

Parameters

Name	Type	Description
§parentSelector	`CssSelector`	The selector that will be the direct parent of this selector

Returns

CssSelector

The CssSelector instance for method chaining

§readonly class(className: string): CssSelector

Appends a class selector to the current selector.

Parameters

Name	Type	Description
§className	`string`	The class name to append

Returns

CssSelector

The CssSelector instance for method chaining

§readonly first(): CssSelector

Appends the :first-child pseudo-class to the selector.

Returns

CssSelector

The CssSelector instance for method chaining

§readonly focus(): CssSelector

Appends the :focus pseudo-class to the selector.

Returns

CssSelector

The CssSelector instance for method chaining

§readonly followingSiblings(siblingSelector: CssSelector): CssSelector

Creates a general sibling selector (~ combinator).

Parameters

Name	Type	Description
§siblingSelector	`CssSelector`	The selector for following sibling elements

Returns

CssSelector

The CssSelector instance for method chaining

§readonly hover(): CssSelector

Appends the :hover pseudo-class to the selector.

Returns

CssSelector

The CssSelector instance for method chaining

§readonly id(id: string): CssSelector

Appends an ID selector to the current selector.

Parameters

Name	Type	Description
§id	`string`	The ID to append

Returns

CssSelector

The CssSelector instance for method chaining

§readonly last(): CssSelector

Appends the :last-child pseudo-class to the selector.

Returns

CssSelector

The CssSelector instance for method chaining

§readonly nextSibling(siblingSelector: CssSelector): CssSelector

Creates an adjacent sibling selector (+ combinator).

Parameters

Name	Type	Description
§siblingSelector	`CssSelector`	The selector for the next sibling element

Returns

CssSelector

The CssSelector instance for method chaining

§readonly nth(n: number): CssSelector

Appends the :nth-child() pseudo-class to the selector.

Parameters

Name	Type	Description
§n	`number`	The child index (1-based)

Returns

CssSelector

The CssSelector instance for method chaining

§readonly parentOf(childSelector: CssSelector): CssSelector

Creates a descendant selector (space combinator) with this selector as the parent.

Parameters

Name	Type	Description
§childSelector	`CssSelector`	The selector that will be a descendant of this selector

Returns

CssSelector

The CssSelector instance for method chaining

§readonly pseudo(pseudo: string): CssSelector

Appends a generic pseudo-class or pseudo-element to the selector.

Parameters

Name	Type	Description
§pseudo	`string`	The pseudo-class or pseudo-element (with or without leading colon)

Returns

CssSelector

The CssSelector instance for method chaining

§readonly toString(): string

Converts the selector builder to its string representation. This method returns the complete CSS selector that has been built.

Returns

string

The complete CSS selector string that can be used in querySelector or CSS stylesheets

Example

Building CSS selector with fluent API

const selector = new CssSelector('div')
  .class('container')
  .id('main')
selector.toString() // => 'div.container#main'

View source →