@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

§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'

§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'

§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'

§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"]'

§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'

§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'

§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'

§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

§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

§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

§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

§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)

◇ Classes

§class

CssSelector

Builder class for constructing CSS selectors with a fluent API.

Properties

Methods

§active(): CssSelector

Appends the :active pseudo-class to the selector.

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

Appends an attribute selector to the current selector.

§childOf(parentSelector: CssSelector): CssSelector

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

§class(className: string): CssSelector

Appends a class selector to the current selector.

§first(): CssSelector

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

§focus(): CssSelector

Appends the :focus pseudo-class to the selector.

§followingSiblings(siblingSelector: CssSelector): CssSelector

Creates a general sibling selector (~ combinator).

§hover(): CssSelector

Appends the :hover pseudo-class to the selector.

§id(id: string): CssSelector

Appends an ID selector to the current selector.

§last(): CssSelector

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

§nextSibling(siblingSelector: CssSelector): CssSelector

Creates an adjacent sibling selector (+ combinator).

§nth(n: number): CssSelector

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

§parentOf(childSelector: CssSelector): CssSelector

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

§pseudo(pseudo: string): CssSelector

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

§toString(): string

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