@stacksjs/ts-css 0.1.0

package/dist/parse/list.d.ts

@@ -0,0 +1,54 @@
+declare function createItem<T>(data: T): ListItem<T>;
+/**
+ * Convenience constructor matching `csstree.List()` (callable without `new`).
+ */
+export declare function makeList<T>(): CssList<T>;
+/**
+ * Doubly linked list used as the children container for every CSS AST node.
+ *
+ * Mirrors css-tree's `List` so `csstree.List` import sites can switch to
+ * `import { CssList as List } from '@stacksjs/ts-css/parse'` without changing
+ * call sites. The list owns its `ListItem<T>` cells; items can be moved
+ * between lists by detach/insert pairs.
+ */
+export declare interface ListItem<T> {
+  prev: ListItem<T> | null
+  next: ListItem<T> | null
+  data: T
+}
+export declare class CssList<T> {
+  head: ListItem<T> | null;
+  tail: ListItem<T> | null;
+  static createItem<U>(data: U): ListItem<U>;
+  createItem(data: T): ListItem<T>;
+  get isEmpty(): boolean;
+  get first(): T | null;
+  get last(): T | null;
+  *[Symbol.iterator](): Iterator<T>;
+  fromArray(items: ReadonlyArray<T>): this;
+  toArray(): T[];
+  toJSON(): T[];
+  forEach(fn: (data: T, item: ListItem<T>, list: CssList<T>) => void, thisArg?: any): void;
+  forEachRight(fn: (data: T, item: ListItem<T>, list: CssList<T>) => void, thisArg?: any): void;
+  reduce<U>(fn: (acc: U, data: T, index: number, list: CssList<T>) => U, initial: U): U;
+  some(fn: (item: T, index: number, list: CssList<T>) => boolean): boolean;
+  map<U>(fn: (item: T, index: number, list: CssList<T>) => U): CssList<U>;
+  filter(fn: (item: T, index: number, list: CssList<T>) => boolean): CssList<T>;
+  clear(): void;
+  copy(): CssList<T>;
+  prepend(item: ListItem<T>): this;
+  prependData(data: T): this;
+  append(item: ListItem<T>): this;
+  appendData(data: T): this;
+  insert(item: ListItem<T>, before?: ListItem<T> | null | undefined): this;
+  insertData(data: T, before?: ListItem<T> | null): this;
+  remove(item: ListItem<T>): ListItem<T>;
+  push(data: T): void;
+  pop(): ListItem<T> | null;
+  unshift(data: T): void;
+  shift(): ListItem<T> | null;
+  prependList(list: CssList<T>): this;
+  appendList(list: CssList<T>): this;
+  insertList(list: CssList<T>, before?: ListItem<T> | null): this;
+  replace(oldItem: ListItem<T>, newItemOrList: ListItem<T> | CssList<T>): void;
+}

package/dist/parse/parser/index.d.ts

@@ -0,0 +1,6 @@
+import { TokenType } from '../tokenizer';
+import type { CssNode, ParseOptions } from '../types';
+// ----- top-level dispatch -----
+export declare function parse(source: string, options?: ParseOptions): CssNode;
+// expose some helpers for the public surface
+export { TokenType };

package/dist/parse/tokenizer.d.ts

@@ -0,0 +1,67 @@
+/** Decode a CSS-escaped name slice (e.g. `\\26 B` → `&B`). */
+/**
+ * Decode a CSS string literal slice to its actual character value.
+ * `start` / `end` exclude the surrounding quote characters.
+ *
+ * Handles:
+ *   - hex escapes (`\26 ` → `&`)
+ *   - `\"` / `\'` / `\\`
+ *   - escaped newlines (CSS: backslash followed by newline is removed)
+ *   - any other `\<char>` → `<char>`
+ */
+export declare function decodeString(source: string, start: number, end: number): string;
+export declare function decodeName(source: string, start: number, end: number): string;
+export declare interface Token {
+  type: TokenType
+  start: number
+  end: number
+}
+export declare class Tokenizer {
+  source: string;
+  offset: number;
+  types: Uint8Array;
+  starts: Uint32Array;
+  ends: Uint32Array;
+  count: number;
+  constructor(source: string);
+  get lineStarts(): number[];
+  get tokens(): Token[];
+  locate(offset: number): { line: number, column: number };
+}
+/**
+ * CSS Syntax Module Level 3 tokenizer.
+ *
+ *   https://www.w3.org/TR/css-syntax-3/#tokenization
+ *
+ * Produces a flat sequence of token offsets that the parser walks. Tokens
+ * are recorded as parallel arrays (type + offset) rather than allocations
+ * — every other CSS lib does the same for performance.
+ */
+export declare const enum TokenType {
+  EOF = 0,
+  Ident = 1,
+  Function = 2,
+  AtKeyword = 3,
+  Hash = 4,
+  String = 5,
+  BadString = 6,
+  Url = 7,
+  BadUrl = 8,
+  Delim = 9,
+  Number = 10,
+  Percentage = 11,
+  Dimension = 12,
+  WhiteSpace = 13,
+  CDO = 14,
+  CDC = 15,
+  Colon = 16,
+  Semicolon = 17,
+  Comma = 18,
+  LeftSquareBracket = 19,
+  RightSquareBracket = 20,
+  LeftParenthesis = 21,
+  RightParenthesis = 22,
+  LeftCurlyBracket = 23,
+  RightCurlyBracket = 24,
+  Comment = 25,
+}

package/dist/parse/types.d.ts

@@ -0,0 +1,264 @@
+import type { CssList } from './list';
+export declare interface BaseNode {
+  type: CssNodeType
+  loc?: CssLocation | null
+}
+export declare interface CssLocation {
+  source: string
+  start: { offset: number, line: number, column: number }
+  end: { offset: number, line: number, column: number }
+}
+// ----- Containers -----
+export declare interface StyleSheet extends BaseNode {
+  type: 'StyleSheet'
+  children: CssList<CssNode>
+}
+export declare interface Rule extends BaseNode {
+  type: 'Rule'
+  prelude: SelectorList | Raw
+  block: Block
+}
+export declare interface Atrule extends BaseNode {
+  type: 'Atrule'
+  name: string
+  prelude: AtrulePrelude | Raw | null
+  block: Block | null
+}
+export declare interface AtrulePrelude extends BaseNode {
+  type: 'AtrulePrelude'
+  children: CssList<CssNode>
+}
+export declare interface Block extends BaseNode {
+  type: 'Block'
+  children: CssList<CssNode>
+}
+// ----- Declarations -----
+export declare interface Declaration extends BaseNode {
+  type: 'Declaration'
+  important: boolean | string
+  property: string
+  value: Value | Raw
+}
+export declare interface DeclarationList extends BaseNode {
+  type: 'DeclarationList'
+  children: CssList<CssNode>
+}
+export declare interface Value extends BaseNode {
+  type: 'Value'
+  children: CssList<CssNode>
+}
+// ----- Selectors -----
+export declare interface SelectorList extends BaseNode {
+  type: 'SelectorList'
+  children: CssList<CssNode>
+}
+export declare interface Selector extends BaseNode {
+  type: 'Selector'
+  children: CssList<CssNode>
+}
+export declare interface TypeSelector extends BaseNode {
+  type: 'TypeSelector'
+  name: string
+}
+export declare interface IdSelector extends BaseNode {
+  type: 'IdSelector'
+  name: string
+}
+export declare interface ClassSelector extends BaseNode {
+  type: 'ClassSelector'
+  name: string
+}
+export declare interface AttributeSelector extends BaseNode {
+  type: 'AttributeSelector'
+  name: Identifier
+  matcher: string | null
+  value: StringNode | Identifier | null
+  flags: string | null
+}
+export declare interface PseudoClassSelector extends BaseNode {
+  type: 'PseudoClassSelector'
+  name: string
+  children: CssList<CssNode> | null
+}
+export declare interface PseudoElementSelector extends BaseNode {
+  type: 'PseudoElementSelector'
+  name: string
+  children: CssList<CssNode> | null
+}
+export declare interface Combinator extends BaseNode {
+  type: 'Combinator'
+  name: string
+}
+export declare interface NestingSelector extends BaseNode {
+  type: 'NestingSelector'
+}
+// ----- Atomic values -----
+export declare interface Identifier extends BaseNode {
+  type: 'Identifier'
+  name: string
+}
+export declare interface NumberNode extends BaseNode {
+  type: 'Number'
+  value: string
+}
+export declare interface PercentageNode extends BaseNode {
+  type: 'Percentage'
+  value: string
+}
+export declare interface DimensionNode extends BaseNode {
+  type: 'Dimension'
+  value: string
+  unit: string
+}
+export declare interface StringNode extends BaseNode {
+  type: 'String'
+  value: string
+}
+export declare interface UrlNode extends BaseNode {
+  type: 'Url'
+  value: string
+}
+export declare interface HashNode extends BaseNode {
+  type: 'Hash'
+  name: string
+}
+export declare interface OperatorNode extends BaseNode {
+  type: 'Operator'
+  value: string
+}
+export declare interface FunctionNode extends BaseNode {
+  type: 'Function'
+  name: string
+  children: CssList<CssNode>
+}
+export declare interface ParenthesesNode extends BaseNode {
+  type: 'Parentheses'
+  children: CssList<CssNode>
+}
+export declare interface BracketsNode extends BaseNode {
+  type: 'Brackets'
+  children: CssList<CssNode>
+}
+export declare interface RawNode extends BaseNode {
+  type: 'Raw'
+  value: string
+}
+export declare interface CommentNode extends BaseNode {
+  type: 'Comment'
+  value: string
+}
+export declare interface WhiteSpaceNode extends BaseNode {
+  type: 'WhiteSpace'
+  value: string
+}
+export declare interface CDONode extends BaseNode { type: 'CDO' }
+export declare interface CDCNode extends BaseNode { type: 'CDC' }
+export declare interface NthNode extends BaseNode {
+  type: 'Nth'
+  nth: AnPlusBNode | Identifier
+  selector: SelectorList | null
+}
+export declare interface AnPlusBNode extends BaseNode {
+  type: 'AnPlusB'
+  a: string | null
+  b: string | null
+}
+export declare interface RatioNode extends BaseNode {
+  type: 'Ratio'
+  left: NumberNode
+  right: NumberNode
+}
+export declare interface UnicodeRangeNode extends BaseNode {
+  type: 'UnicodeRange'
+  value: string
+}
+export declare interface MediaQueryListNode extends BaseNode {
+  type: 'MediaQueryList'
+  children: CssList<CssNode>
+}
+export declare interface MediaQueryNode extends BaseNode {
+  type: 'MediaQuery'
+  children: CssList<CssNode>
+}
+export declare interface MediaFeatureNode extends BaseNode {
+  type: 'MediaFeature'
+  name: string
+  value: NumberNode | DimensionNode | RatioNode | Identifier | null
+}
+export declare interface ParseOptions {
+  filename?: string
+  positions?: boolean
+  context?: ParseContext
+  parseValue?: boolean
+  parseAtrulePrelude?: boolean
+  parseCustomProperty?: boolean
+  parseRulePrelude?: boolean
+  onParseError?: (error: SyntaxError, fallbackNode: CssNode) => void
+}
+export type CssNodeType = | 'AnPlusB'
+    | 'Atrule'
+    | 'AtrulePrelude'
+    | 'AttributeSelector'
+    | 'Block'
+    | 'Brackets'
+    | 'CDC'
+    | 'CDO'
+    | 'ClassSelector'
+    | 'Combinator'
+    | 'Comment'
+    | 'Declaration'
+    | 'DeclarationList'
+    | 'Dimension'
+    | 'Function'
+    | 'Hash'
+    | 'IdSelector'
+    | 'Identifier'
+    | 'MediaFeature'
+    | 'MediaQuery'
+    | 'MediaQueryList'
+    | 'NestingSelector'
+    | 'Nth'
+    | 'Number'
+    | 'Operator'
+    | 'Parentheses'
+    | 'Percentage'
+    | 'PseudoClassSelector'
+    | 'PseudoElementSelector'
+    | 'Ratio'
+    | 'Raw'
+    | 'Rule'
+    | 'Selector'
+    | 'SelectorList'
+    | 'StyleSheet'
+    | 'TypeSelector'
+    | 'UnicodeRange'
+    | 'Url'
+    | 'Value'
+    | 'WhiteSpace'
+    | 'String';
+// ----- Aliases -----
+export type Raw = RawNode;
+export type CssNode = | StyleSheet | Rule | Atrule | AtrulePrelude | Block
+    | Declaration | DeclarationList | Value
+    | SelectorList | Selector | TypeSelector | IdSelector | ClassSelector
+    | AttributeSelector | PseudoClassSelector | PseudoElementSelector
+    | Combinator | NestingSelector
+    | Identifier | NumberNode | PercentageNode | DimensionNode
+    | StringNode | UrlNode | HashNode | OperatorNode
+    | FunctionNode | ParenthesesNode | BracketsNode
+    | RawNode | CommentNode | WhiteSpaceNode | CDONode | CDCNode
+    | NthNode | AnPlusBNode | RatioNode | UnicodeRangeNode
+    | MediaQueryListNode | MediaQueryNode | MediaFeatureNode;
+export type ParseContext = | 'stylesheet'
+    | 'atrule'
+    | 'atrulePrelude'
+    | 'mediaQuery'
+    | 'mediaQueryList'
+    | 'rule'
+    | 'selectorList'
+    | 'selector'
+    | 'block'
+    | 'declarationList'
+    | 'declaration'
+    | 'value'
+    | 'raw';

package/dist/parse/walker.d.ts

@@ -0,0 +1,55 @@
+import { CssList, type ListItem } from './list';
+import type { Atrule, CssNode, Declaration, Rule } from './types';
+export declare const walk: WalkFn;
+export declare const walkSkip: symbol;
+export declare const walkStop: symbol;
+export declare interface WalkContext {
+  root: CssNode
+  stylesheet: CssNode | null
+  atrule: Atrule | null
+  atrulePrelude: CssNode | null
+  rule: Rule | null
+  selector: CssNode | null
+  block: CssNode | null
+  declaration: Declaration | null
+  function: CssNode | null
+}
+/**
+ * Object-form visitor. The `T extends WalkVisit` generic is inferred from
+ * the literal value of `visit`, so writing
+ *
+ *     walk(ast, { visit: 'Rule', enter(node) { … } })
+ *
+ * narrows `node` to `Rule`. Without `visit`, callbacks receive the full
+ * `CssNode` union as `enter`/`leave` arguments.
+ */
+export declare interface WalkVisitorObject<T extends WalkVisit | undefined = undefined> {
+  visit?: T
+  reverse?: boolean
+  enter?: VisitorCallback<T extends WalkVisit ? CssNodeOfType<T> : CssNode>
+  leave?: VisitorCallback<T extends WalkVisit ? CssNodeOfType<T> : CssNode>
+}
+/**
+ * Walk every node of `root`, calling `visitor` (or visitor.enter / .leave).
+ * Returns:
+ *   - undefined when traversal completes,
+ *   - the SKIP / STOP sentinel propagated from a visitor.
+ *
+ * `walk.skip` / `walk.stop` are exposed as static-symbol sentinels.
+ */
+export declare interface WalkFn {
+  (root: CssNode, visitor: WalkVisitorFunction): symbol | undefined
+  <T extends WalkVisit>(root: CssNode, visitor: WalkVisitorObject<T>): symbol | undefined
+  skip: symbol
+  stop: symbol
+}
+export type WalkVisit = CssNode['type'];
+// Narrow CssNode by its `type` discriminant — used to type the
+// `visit: 'Rule'` filter so consumer callbacks receive a `Rule`, not the
+// full union.
+export type CssNodeOfType<T extends WalkVisit> = Extract<CssNode, { type: T }>;
+// eslint-disable-next-line pickier/no-unused-vars
+declare type VisitorCallback<N> = (this: WalkContext, node: N, item: ListItem<CssNode> | null, list: CssList<CssNode> | null) => void | symbol;
+/** Plain-function visitor — runs against every node. */
+export type WalkVisitorFunction = VisitorCallback<CssNode>;
+export type WalkVisitor = WalkVisitorFunction | WalkVisitorObject<WalkVisit | undefined>;

package/dist/select/index.d.ts

@@ -0,0 +1,18 @@
+import { parseAndCompile } from './pseudo-selectors/selectors';
+import type { Adapter, CompiledQuery, Options } from './types';
+import type { Selector } from '../what';
+export type {
+  Adapter,
+  CompiledQuery,
+  Options,
+  Predicate,
+} from './types';
+export declare function compile<Node, ElementNode extends Node>(selector: string | Selector[][], options: Options<Node, ElementNode>): CompiledQuery<ElementNode>;
+/** Drop the cached compile of `selector` for `adapter`, or all entries
+ *  if `selector` is omitted. */
+export declare function clearSelectorCache(adapter: object, selector?: string): void;
+export declare function selectAll<Node, ElementNode extends Node>(selector: string | Selector[][] | CompiledQuery<ElementNode>, root: Node | Node[], options: Options<Node, ElementNode>): ElementNode[];
+export declare function selectOne<Node, ElementNode extends Node>(selector: string | Selector[][] | CompiledQuery<ElementNode>, root: Node | Node[], options: Options<Node, ElementNode>): ElementNode | null;
+export declare function is<Node, ElementNode extends Node>(node: ElementNode, selector: string | Selector[][] | CompiledQuery<ElementNode>, options: Options<Node, ElementNode>): boolean;
+// expose internals for advanced use
+export { parseAndCompile };