@projectwallace/css-parser 0.8.0 → 0.8.1

package/dist/constants.d.ts

@@ -1 +1,40 @@
-export { STYLESHEET, STYLE_RULE, AT_RULE, DECLARATION, SELECTOR, COMMENT, BLOCK, IDENTIFIER, NUMBER, DIMENSION, STRING, HASH, FUNCTION, OPERATOR, PARENTHESIS, URL, SELECTOR_LIST, TYPE_SELECTOR, CLASS_SELECTOR, ID_SELECTOR, ATTRIBUTE_SELECTOR, PSEUDO_CLASS_SELECTOR, PSEUDO_ELEMENT_SELECTOR, COMBINATOR, UNIVERSAL_SELECTOR, NESTING_SELECTOR, NTH_SELECTOR, NTH_OF_SELECTOR, LANG_SELECTOR, MEDIA_QUERY, MEDIA_FEATURE, MEDIA_TYPE, CONTAINER_QUERY, SUPPORTS_QUERY, LAYER_NAME, PRELUDE_OPERATOR, FLAG_IMPORTANT, ATTR_OPERATOR_NONE, ATTR_OPERATOR_EQUAL, ATTR_OPERATOR_TILDE_EQUAL, ATTR_OPERATOR_PIPE_EQUAL, ATTR_OPERATOR_CARET_EQUAL, ATTR_OPERATOR_DOLLAR_EQUAL, ATTR_OPERATOR_STAR_EQUAL, ATTR_FLAG_NONE, ATTR_FLAG_CASE_INSENSITIVE, ATTR_FLAG_CASE_SENSITIVE, } from './arena';
+import { STYLESHEET, STYLE_RULE, AT_RULE, DECLARATION, SELECTOR, COMMENT, BLOCK, IDENTIFIER, NUMBER, DIMENSION, STRING, HASH, FUNCTION, OPERATOR, PARENTHESIS, URL, SELECTOR_LIST, TYPE_SELECTOR, CLASS_SELECTOR, ID_SELECTOR, ATTRIBUTE_SELECTOR, PSEUDO_CLASS_SELECTOR, PSEUDO_ELEMENT_SELECTOR, COMBINATOR, UNIVERSAL_SELECTOR, NESTING_SELECTOR, NTH_SELECTOR, NTH_OF_SELECTOR, LANG_SELECTOR, MEDIA_QUERY, MEDIA_FEATURE, MEDIA_TYPE, CONTAINER_QUERY, SUPPORTS_QUERY, LAYER_NAME, PRELUDE_OPERATOR, FLAG_IMPORTANT, ATTR_OPERATOR_NONE, ATTR_OPERATOR_EQUAL, ATTR_OPERATOR_TILDE_EQUAL, ATTR_OPERATOR_PIPE_EQUAL, ATTR_OPERATOR_CARET_EQUAL, ATTR_OPERATOR_DOLLAR_EQUAL, ATTR_OPERATOR_STAR_EQUAL, ATTR_FLAG_NONE, ATTR_FLAG_CASE_INSENSITIVE, ATTR_FLAG_CASE_SENSITIVE } from './arena';
+export { STYLESHEET, STYLE_RULE, AT_RULE, DECLARATION, SELECTOR, COMMENT, BLOCK, IDENTIFIER, NUMBER, DIMENSION, STRING, HASH, FUNCTION, OPERATOR, PARENTHESIS, URL, SELECTOR_LIST, TYPE_SELECTOR, CLASS_SELECTOR, ID_SELECTOR, ATTRIBUTE_SELECTOR, PSEUDO_CLASS_SELECTOR, PSEUDO_ELEMENT_SELECTOR, COMBINATOR, UNIVERSAL_SELECTOR, NESTING_SELECTOR, NTH_SELECTOR, NTH_OF_SELECTOR, LANG_SELECTOR, MEDIA_QUERY, MEDIA_FEATURE, MEDIA_TYPE, CONTAINER_QUERY, SUPPORTS_QUERY, LAYER_NAME, PRELUDE_OPERATOR, FLAG_IMPORTANT, ATTR_OPERATOR_NONE, ATTR_OPERATOR_EQUAL, ATTR_OPERATOR_TILDE_EQUAL, ATTR_OPERATOR_PIPE_EQUAL, ATTR_OPERATOR_CARET_EQUAL, ATTR_OPERATOR_DOLLAR_EQUAL, ATTR_OPERATOR_STAR_EQUAL, ATTR_FLAG_NONE, ATTR_FLAG_CASE_INSENSITIVE, ATTR_FLAG_CASE_SENSITIVE, };
+export declare const NODE_TYPES: {
+    readonly STYLESHEET: 1;
+    readonly STYLE_RULE: 2;
+    readonly AT_RULE: 3;
+    readonly DECLARATION: 4;
+    readonly SELECTOR: 5;
+    readonly COMMENT: 6;
+    readonly BLOCK: 7;
+    readonly IDENTIFIER: 10;
+    readonly NUMBER: 11;
+    readonly DIMENSION: 12;
+    readonly STRING: 13;
+    readonly HASH: 14;
+    readonly FUNCTION: 15;
+    readonly OPERATOR: 16;
+    readonly PARENTHESIS: 17;
+    readonly URL: 18;
+    readonly SELECTOR_LIST: 20;
+    readonly TYPE_SELECTOR: 21;
+    readonly CLASS_SELECTOR: 22;
+    readonly ID_SELECTOR: 23;
+    readonly ATTRIBUTE_SELECTOR: 24;
+    readonly PSEUDO_CLASS_SELECTOR: 25;
+    readonly PSEUDO_ELEMENT_SELECTOR: 26;
+    readonly COMBINATOR: 27;
+    readonly UNIVERSAL_SELECTOR: 28;
+    readonly NESTING_SELECTOR: 29;
+    readonly NTH_SELECTOR: 30;
+    readonly NTH_OF_SELECTOR: 31;
+    readonly LANG_SELECTOR: 56;
+    readonly MEDIA_QUERY: 32;
+    readonly MEDIA_FEATURE: 33;
+    readonly MEDIA_TYPE: 34;
+    readonly CONTAINER_QUERY: 35;
+    readonly SUPPORTS_QUERY: 36;
+    readonly LAYER_NAME: 37;
+    readonly PRELUDE_OPERATOR: 38;
+};

package/dist/constants.js

@@ -0,0 +1,47 @@
+import { PRELUDE_OPERATOR, LAYER_NAME, SUPPORTS_QUERY, CONTAINER_QUERY, MEDIA_TYPE, MEDIA_FEATURE, MEDIA_QUERY, LANG_SELECTOR, NTH_OF_SELECTOR, NTH_SELECTOR, NESTING_SELECTOR, UNIVERSAL_SELECTOR, COMBINATOR, PSEUDO_ELEMENT_SELECTOR, PSEUDO_CLASS_SELECTOR, ATTRIBUTE_SELECTOR, ID_SELECTOR, CLASS_SELECTOR, TYPE_SELECTOR, SELECTOR_LIST, URL, PARENTHESIS, OPERATOR, FUNCTION, HASH, STRING, DIMENSION, NUMBER, IDENTIFIER, BLOCK, COMMENT, SELECTOR, DECLARATION, AT_RULE, STYLE_RULE, STYLESHEET } from './arena.js';
+export { ATTR_FLAG_CASE_INSENSITIVE, ATTR_FLAG_CASE_SENSITIVE, ATTR_FLAG_NONE, ATTR_OPERATOR_CARET_EQUAL, ATTR_OPERATOR_DOLLAR_EQUAL, ATTR_OPERATOR_EQUAL, ATTR_OPERATOR_NONE, ATTR_OPERATOR_PIPE_EQUAL, ATTR_OPERATOR_STAR_EQUAL, ATTR_OPERATOR_TILDE_EQUAL, FLAG_IMPORTANT } from './arena.js';
+
+const NODE_TYPES = {
+  // Core nodes
+  STYLESHEET,
+  STYLE_RULE,
+  AT_RULE,
+  DECLARATION,
+  SELECTOR,
+  COMMENT,
+  BLOCK,
+  // Value nodes
+  IDENTIFIER,
+  NUMBER,
+  DIMENSION,
+  STRING,
+  HASH,
+  FUNCTION,
+  OPERATOR,
+  PARENTHESIS,
+  URL,
+  // Selector nodes
+  SELECTOR_LIST,
+  TYPE_SELECTOR,
+  CLASS_SELECTOR,
+  ID_SELECTOR,
+  ATTRIBUTE_SELECTOR,
+  PSEUDO_CLASS_SELECTOR,
+  PSEUDO_ELEMENT_SELECTOR,
+  COMBINATOR,
+  UNIVERSAL_SELECTOR,
+  NESTING_SELECTOR,
+  NTH_SELECTOR,
+  NTH_OF_SELECTOR,
+  LANG_SELECTOR,
+  // At-rule prelude nodes
+  MEDIA_QUERY,
+  MEDIA_FEATURE,
+  MEDIA_TYPE,
+  CONTAINER_QUERY,
+  SUPPORTS_QUERY,
+  LAYER_NAME,
+  PRELUDE_OPERATOR
+};
+
+export { ATTRIBUTE_SELECTOR, AT_RULE, BLOCK, CLASS_SELECTOR, COMBINATOR, COMMENT, CONTAINER_QUERY, DECLARATION, DIMENSION, FUNCTION, HASH, IDENTIFIER, ID_SELECTOR, LANG_SELECTOR, LAYER_NAME, MEDIA_FEATURE, MEDIA_QUERY, MEDIA_TYPE, NESTING_SELECTOR, NODE_TYPES, NTH_OF_SELECTOR, NTH_SELECTOR, NUMBER, OPERATOR, PARENTHESIS, PRELUDE_OPERATOR, PSEUDO_CLASS_SELECTOR, PSEUDO_ELEMENT_SELECTOR, SELECTOR, SELECTOR_LIST, STRING, STYLESHEET, STYLE_RULE, SUPPORTS_QUERY, TYPE_SELECTOR, UNIVERSAL_SELECTOR, URL };

package/dist/css-node.d.ts

@@ -80,48 +80,124 @@ export declare class CSSNode {
     private source;
     private index;
     constructor(arena: CSSDataArena, source: string, index: number);
-    get_index(): number;
+    /** Get node type as number (for performance) */
     get type(): CSSNodeType;
+    /** Get node type as human-readable string */
     get type_name(): TypeName;
+    /** Get the full text of this node from source */
     get text(): string;
+    /** Get the "content" text (property name for declarations, at-rule name for at-rules, layer name for import layers) */
     get name(): string;
+    /**
+     * Alias for name (for declarations: "color" in "color: blue")
+     * More semantic than `name` for declaration nodes
+     */
     get property(): string;
+    /**
+     * Get the value text (for declarations: "blue" in "color: blue")
+     * For dimension/number nodes: returns the numeric value as a number
+     * For string nodes: returns the string content without quotes
+     * For URL nodes with quoted string: returns the string with quotes (consistent with STRING node)
+     * For URL nodes with unquoted URL: returns the URL content without quotes
+     */
     get value(): string | number | null;
+    /** Get the numeric value for NUMBER and DIMENSION nodes, or null for other node types */
     get value_as_number(): number | null;
+    /**
+     * Get the prelude text (for at-rules: "(min-width: 768px)" in "@media (min-width: 768px)")
+     * This is an alias for `value` to make at-rule usage more semantic
+     */
     get prelude(): string | null;
+    /**
+     * Get the attribute operator (for attribute selectors: =, ~=, |=, ^=, $=, *=)
+     * Returns one of the ATTR_OPERATOR_* constants
+     */
     get attr_operator(): number;
+    /**
+     * Get the attribute flags (for attribute selectors: i, s)
+     * Returns one of the ATTR_FLAG_* constants
+     */
     get attr_flags(): number;
+    /** Get the unit for dimension nodes (e.g., "px" from "100px", "%" from "50%") */
     get unit(): string | null;
+    /** Check if this declaration has !important */
     get is_important(): boolean | null;
+    /** Check if this has a vendor prefix (computed on-demand) */
     get is_vendor_prefixed(): boolean;
+    /** Check if this node has an error */
     get has_error(): boolean;
+    /** Check if this at-rule has a prelude */
     get has_prelude(): boolean;
+    /** Check if this rule has a block { } */
     get has_block(): boolean;
+    /** Check if this style rule has declarations */
     get has_declarations(): boolean;
+    /** Get the block node (for style rules and at-rules with blocks) */
     get block(): CSSNode | null;
+    /** Check if this block is empty (no declarations or rules, only comments allowed) */
     get is_empty(): boolean;
+    /** Get array of parsed value nodes (for declarations only) */
     get values(): CSSNode[];
-    get value_count(): number;
+    /** Get start line number */
     get line(): number;
+    /** Get start column number */
     get column(): number;
+    /** Get start offset in source */
     get start(): number;
+    /** Get length in source */
     get length(): number;
+    /**
+     * Get end offset in source
+     * End is not stored, must be calculated
+     */
     get end(): number;
+    /** Get first child node */
     get first_child(): CSSNode | null;
+    /** Get next sibling node */
     get next_sibling(): CSSNode | null;
+    /** Check if this node has a next sibling */
     get has_next(): boolean;
+    /**
+     * Check if this node has children
+     * For pseudo-class/pseudo-element functions, returns true if FLAG_HAS_PARENS is set
+     * This allows formatters to distinguish :lang() from :hover
+     */
     get has_children(): boolean;
+    /** Get all children as an array */
     get children(): CSSNode[];
+    /** Make CSSNode iterable over its children */
     [Symbol.iterator](): Iterator<CSSNode>;
+    /** Get the 'a' coefficient from An+B expression (e.g., "2n" from "2n+1", "odd" from "odd") */
     get nth_a(): string | null;
+    /** Get the 'b' coefficient from An+B expression (e.g., "+1" from "2n+1") */
     get nth_b(): string | null;
+    /** Get the An+B formula node from :nth-child(2n+1 of .foo) */
     get nth(): CSSNode | null;
+    /** Get the selector list from :nth-child(2n+1 of .foo) */
     get selector(): CSSNode | null;
+    /**
+     * Get selector list from pseudo-class functions
+     * Works for :is(.a), :not(.b), :has(.c), :where(.d), :nth-child(2n of .e)
+     */
     get selector_list(): CSSNode | null;
+    /**
+     * Iterator over first compound selector parts (zero allocation)
+     * Yields parts before the first combinator
+     */
     compound_parts(): IterableIterator<CSSNode>;
+    /**
+     * Get first compound selector as array
+     * Returns array of parts before first combinator
+     */
     get first_compound(): CSSNode[];
+    /**
+     * Split selector into compound selectors
+     * Returns array of compound arrays split by combinators
+     */
     get all_compounds(): CSSNode[][];
+    /** Check if selector is compound (no combinators) */
     get is_compound(): boolean;
+    /** Get text of first compound selector (no node allocation) */
     get first_compound_text(): string;
     /**
      * Clone this node as a mutable plain JavaScript object

package/dist/css-node.js

@@ -49,41 +49,41 @@ class CSSNode {
     this.source = source;
     this.index = index;
   }
-  // Get the node index (for internal use)
-  get_index() {
-    return this.index;
-  }
-  // Get node type as number (for performance)
+  /** Get node type as number (for performance) */
   get type() {
     return this.arena.get_type(this.index);
   }
-  // Get node type as human-readable string
+  /** Get node type as human-readable string */
   get type_name() {
     return TYPE_NAMES[this.type] || "unknown";
   }
-  // Get the full text of this node from source
+  /** Get the full text of this node from source */
   get text() {
     let start = this.arena.get_start_offset(this.index);
     let length = this.arena.get_length(this.index);
     return this.source.substring(start, start + length);
   }
-  // Get the "content" text (property name for declarations, at-rule name for at-rules, layer name for import layers)
+  /** Get the "content" text (property name for declarations, at-rule name for at-rules, layer name for import layers) */
   get name() {
     let start = this.arena.get_content_start(this.index);
     let length = this.arena.get_content_length(this.index);
     if (length === 0) return "";
     return this.source.substring(start, start + length);
   }
-  // Alias for name (for declarations: "color" in "color: blue")
-  // More semantic than `name` for declaration nodes
+  /**
+   * Alias for name (for declarations: "color" in "color: blue")
+   * More semantic than `name` for declaration nodes
+   */
   get property() {
     return this.name;
   }
-  // Get the value text (for declarations: "blue" in "color: blue")
-  // For dimension/number nodes: returns the numeric value as a number
-  // For string nodes: returns the string content without quotes
-  // For URL nodes with quoted string: returns the string with quotes (consistent with STRING node)
-  // For URL nodes with unquoted URL: returns the URL content without quotes
+  /**
+   * Get the value text (for declarations: "blue" in "color: blue")
+   * For dimension/number nodes: returns the numeric value as a number
+   * For string nodes: returns the string content without quotes
+   * For URL nodes with quoted string: returns the string with quotes (consistent with STRING node)
+   * For URL nodes with unquoted URL: returns the URL content without quotes
+   */
   get value() {
     let { type, text } = this;
     if (type === DIMENSION) {
@@ -113,6 +113,7 @@ class CSSNode {
     if (length === 0) return null;
     return this.source.substring(start, start + length);
   }
+  /** Get the numeric value for NUMBER and DIMENSION nodes, or null for other node types */
   get value_as_number() {
     let text = this.text;
     if (this.type === NUMBER) {
@@ -123,33 +124,39 @@ class CSSNode {
     }
     return null;
   }
-  // Get the prelude text (for at-rules: "(min-width: 768px)" in "@media (min-width: 768px)")
-  // This is an alias for `value` to make at-rule usage more semantic
+  /**
+   * Get the prelude text (for at-rules: "(min-width: 768px)" in "@media (min-width: 768px)")
+   * This is an alias for `value` to make at-rule usage more semantic
+   */
   get prelude() {
     let val = this.value;
     return typeof val === "string" ? val : null;
   }
-  // Get the attribute operator (for attribute selectors: =, ~=, |=, ^=, $=, *=)
-  // Returns one of the ATTR_OPERATOR_* constants
+  /**
+   * Get the attribute operator (for attribute selectors: =, ~=, |=, ^=, $=, *=)
+   * Returns one of the ATTR_OPERATOR_* constants
+   */
   get attr_operator() {
     return this.arena.get_attr_operator(this.index);
   }
-  // Get the attribute flags (for attribute selectors: i, s)
-  // Returns one of the ATTR_FLAG_* constants
+  /**
+   * Get the attribute flags (for attribute selectors: i, s)
+   * Returns one of the ATTR_FLAG_* constants
+   */
   get attr_flags() {
     return this.arena.get_attr_flags(this.index);
   }
-  // Get the unit for dimension nodes (e.g., "px" from "100px", "%" from "50%")
+  /** Get the unit for dimension nodes (e.g., "px" from "100px", "%" from "50%") */
   get unit() {
     if (this.type !== DIMENSION) return null;
     return parse_dimension(this.text).unit;
   }
-  // Check if this declaration has !important
+  /** Check if this declaration has !important */
   get is_important() {
     if (this.type !== DECLARATION) return null;
     return this.arena.has_flag(this.index, FLAG_IMPORTANT);
   }
-  // Check if this has a vendor prefix (computed on-demand)
+  /** Check if this has a vendor prefix (computed on-demand) */
   get is_vendor_prefixed() {
     switch (this.type) {
       case DECLARATION:
@@ -167,23 +174,23 @@ class CSSNode {
         return false;
     }
   }
-  // Check if this node has an error
+  /** Check if this node has an error */
   get has_error() {
     return this.arena.has_flag(this.index, FLAG_HAS_ERROR);
   }
-  // Check if this at-rule has a prelude
+  /** Check if this at-rule has a prelude */
   get has_prelude() {
     return this.arena.get_value_length(this.index) > 0;
   }
-  // Check if this rule has a block { }
+  /** Check if this rule has a block { } */
   get has_block() {
     return this.arena.has_flag(this.index, FLAG_HAS_BLOCK);
   }
-  // Check if this style rule has declarations
+  /** Check if this style rule has declarations */
   get has_declarations() {
     return this.arena.has_flag(this.index, FLAG_HAS_DECLARATIONS);
   }
-  // Get the block node (for style rules and at-rules with blocks)
+  /** Get the block node (for style rules and at-rules with blocks) */
   get block() {
     if (this.type === STYLE_RULE) {
       let first = this.first_child;
@@ -206,7 +213,7 @@ class CSSNode {
     }
     return null;
   }
-  // Check if this block is empty (no declarations or rules, only comments allowed)
+  /** Check if this block is empty (no declarations or rules, only comments allowed) */
   get is_empty() {
     if (this.type !== BLOCK) return false;
     let child = this.first_child;
@@ -219,7 +226,7 @@ class CSSNode {
     return true;
   }
   // --- Value Node Access (for declarations) ---
-  // Get array of parsed value nodes (for declarations only)
+  /** Get array of parsed value nodes (for declarations only) */
   get values() {
     let result = [];
     let child = this.first_child;
@@ -229,57 +236,52 @@ class CSSNode {
     }
     return result;
   }
-  // Get count of value nodes
-  get value_count() {
-    let count = 0;
-    let child = this.first_child;
-    while (child) {
-      count++;
-      child = child.next_sibling;
-    }
-    return count;
-  }
-  // Get start line number
+  /** Get start line number */
   get line() {
     return this.arena.get_start_line(this.index);
   }
-  // Get start column number
+  /** Get start column number */
   get column() {
     return this.arena.get_start_column(this.index);
   }
-  // Get start offset in source
+  /** Get start offset in source */
   get start() {
     return this.arena.get_start_offset(this.index);
   }
-  // Get length in source
+  /** Get length in source */
   get length() {
     return this.arena.get_length(this.index);
   }
-  // Get end offset in source
-  // End is not stored, must be calculated
+  /**
+   * Get end offset in source
+   * End is not stored, must be calculated
+   */
   get end() {
     return this.start + this.length;
   }
   // --- Tree Traversal ---
-  // Get first child node
+  /** Get first child node */
   get first_child() {
     let child_index = this.arena.get_first_child(this.index);
     if (child_index === 0) return null;
     return new CSSNode(this.arena, this.source, child_index);
   }
-  // Get next sibling node
+  /** Get next sibling node */
   get next_sibling() {
     let sibling_index = this.arena.get_next_sibling(this.index);
     if (sibling_index === 0) return null;
     return new CSSNode(this.arena, this.source, sibling_index);
   }
+  /** Check if this node has a next sibling */
   get has_next() {
     let sibling_index = this.arena.get_next_sibling(this.index);
     return sibling_index !== 0;
   }
-  // Check if this node has children
-  // For pseudo-class/pseudo-element functions, returns true if FLAG_HAS_PARENS is set
-  // This allows formatters to distinguish :lang() from :hover
+  /**
+   * Check if this node has children
+   * For pseudo-class/pseudo-element functions, returns true if FLAG_HAS_PARENS is set
+   * This allows formatters to distinguish :lang() from :hover
+   */
   get has_children() {
     if (this.type === PSEUDO_CLASS_SELECTOR || this.type === PSEUDO_ELEMENT_SELECTOR) {
       if (this.arena.has_flag(this.index, FLAG_HAS_PARENS)) {
@@ -288,7 +290,7 @@ class CSSNode {
     }
     return this.arena.has_children(this.index);
   }
-  // Get all children as an array
+  /** Get all children as an array */
   get children() {
     let result = [];
     let child = this.first_child;
@@ -298,7 +300,7 @@ class CSSNode {
     }
     return result;
   }
-  // Make CSSNode iterable over its children
+  /** Make CSSNode iterable over its children */
   *[Symbol.iterator]() {
     let child = this.first_child;
     while (child) {
@@ -307,7 +309,7 @@ class CSSNode {
     }
   }
   // --- An+B Expression Helpers (for NODE_SELECTOR_NTH) ---
-  // Get the 'a' coefficient from An+B expression (e.g., "2n" from "2n+1", "odd" from "odd")
+  /** Get the 'a' coefficient from An+B expression (e.g., "2n" from "2n+1", "odd" from "odd") */
   get nth_a() {
     if (this.type !== NTH_SELECTOR) return null;
     let len = this.arena.get_content_length(this.index);
@@ -315,7 +317,7 @@ class CSSNode {
     let start = this.arena.get_content_start(this.index);
     return this.source.substring(start, start + len);
   }
-  // Get the 'b' coefficient from An+B expression (e.g., "+1" from "2n+1")
+  /** Get the 'b' coefficient from An+B expression (e.g., "+1" from "2n+1") */
   get nth_b() {
     if (this.type !== NTH_SELECTOR) return null;
     let len = this.arena.get_value_length(this.index);
@@ -339,20 +341,22 @@ class CSSNode {
     return value;
   }
   // --- Pseudo-Class Nth-Of Helpers (for NODE_SELECTOR_NTH_OF) ---
-  // Get the An+B formula node from :nth-child(2n+1 of .foo)
+  /** Get the An+B formula node from :nth-child(2n+1 of .foo) */
   get nth() {
     if (this.type !== NTH_OF_SELECTOR) return null;
     return this.first_child;
   }
-  // Get the selector list from :nth-child(2n+1 of .foo)
+  /** Get the selector list from :nth-child(2n+1 of .foo) */
   get selector() {
     if (this.type !== NTH_OF_SELECTOR) return null;
     let first = this.first_child;
     return first ? first.next_sibling : null;
   }
   // --- Pseudo-Class Selector List Helper ---
-  // Get selector list from pseudo-class functions
-  // Works for :is(.a), :not(.b), :has(.c), :where(.d), :nth-child(2n of .e)
+  /**
+   * Get selector list from pseudo-class functions
+   * Works for :is(.a), :not(.b), :has(.c), :where(.d), :nth-child(2n of .e)
+   */
   get selector_list() {
     if (this.type !== PSEUDO_CLASS_SELECTOR) return null;
     let child = this.first_child;
@@ -366,8 +370,10 @@ class CSSNode {
     return null;
   }
   // --- Compound Selector Helpers (for NODE_SELECTOR) ---
-  // Iterator over first compound selector parts (zero allocation)
-  // Yields parts before the first combinator
+  /**
+   * Iterator over first compound selector parts (zero allocation)
+   * Yields parts before the first combinator
+   */
   *compound_parts() {
     if (this.type !== SELECTOR) return;
     let child = this.first_child;
@@ -377,8 +383,10 @@ class CSSNode {
       child = child.next_sibling;
     }
   }
-  // Get first compound selector as array
-  // Returns array of parts before first combinator
+  /**
+   * Get first compound selector as array
+   * Returns array of parts before first combinator
+   */
   get first_compound() {
     if (this.type !== SELECTOR) return [];
     let result = [];
@@ -390,8 +398,10 @@ class CSSNode {
     }
     return result;
   }
-  // Split selector into compound selectors
-  // Returns array of compound arrays split by combinators
+  /**
+   * Split selector into compound selectors
+   * Returns array of compound arrays split by combinators
+   */
   get all_compounds() {
     if (this.type !== SELECTOR) return [];
     let compounds = [];
@@ -413,7 +423,7 @@ class CSSNode {
     }
     return compounds;
   }
-  // Check if selector is compound (no combinators)
+  /** Check if selector is compound (no combinators) */
   get is_compound() {
     if (this.type !== SELECTOR) return false;
     let child = this.first_child;
@@ -423,7 +433,7 @@ class CSSNode {
     }
     return true;
   }
-  // Get text of first compound selector (no node allocation)
+  /** Get text of first compound selector (no node allocation) */
   get first_compound_text() {
     if (this.type !== SELECTOR) return "";
     let start = -1;

package/dist/index.d.ts

@@ -3,10 +3,11 @@ export { parse_selector } from './parse-selector';
 export { parse_atrule_prelude } from './parse-atrule-prelude';
 export { parse_value } from './parse-value';
 export { tokenize } from './tokenize';
-export { walk, traverse } from './walk';
+export { walk, traverse, SKIP, BREAK } from './walk';
 export { type ParserOptions } from './parse';
 export { CSSNode, type CSSNodeType, TYPE_NAMES, type CloneOptions, type PlainCSSNode } from './css-node';
 export type { LexerPosition } from './lexer';
 export { ATTR_OPERATOR_NONE, ATTR_OPERATOR_EQUAL, ATTR_OPERATOR_TILDE_EQUAL, ATTR_OPERATOR_PIPE_EQUAL, ATTR_OPERATOR_CARET_EQUAL, ATTR_OPERATOR_DOLLAR_EQUAL, ATTR_OPERATOR_STAR_EQUAL, ATTR_FLAG_NONE, ATTR_FLAG_CASE_INSENSITIVE, ATTR_FLAG_CASE_SENSITIVE, } from './arena';
 export * from './constants';
 export * from './token-types';
+export { NODE_TYPES } from './constants';

package/dist/index.js

@@ -3,7 +3,8 @@ export { parse_selector } from './parse-selector.js';
 export { parse_atrule_prelude } from './parse-atrule-prelude.js';
 export { parse_value } from './parse-value.js';
 export { tokenize } from './tokenize.js';
-export { traverse, walk } from './walk.js';
+export { BREAK, SKIP, traverse, walk } from './walk.js';
 export { CSSNode, TYPE_NAMES } from './css-node.js';
 export { ATTRIBUTE_SELECTOR, ATTR_FLAG_CASE_INSENSITIVE, ATTR_FLAG_CASE_SENSITIVE, ATTR_FLAG_NONE, ATTR_OPERATOR_CARET_EQUAL, ATTR_OPERATOR_DOLLAR_EQUAL, ATTR_OPERATOR_EQUAL, ATTR_OPERATOR_NONE, ATTR_OPERATOR_PIPE_EQUAL, ATTR_OPERATOR_STAR_EQUAL, ATTR_OPERATOR_TILDE_EQUAL, AT_RULE, BLOCK, CLASS_SELECTOR, COMBINATOR, COMMENT, CONTAINER_QUERY, DECLARATION, DIMENSION, FLAG_IMPORTANT, FUNCTION, HASH, IDENTIFIER, ID_SELECTOR, LANG_SELECTOR, LAYER_NAME, MEDIA_FEATURE, MEDIA_QUERY, MEDIA_TYPE, NESTING_SELECTOR, NTH_OF_SELECTOR, NTH_SELECTOR, NUMBER, OPERATOR, PARENTHESIS, PRELUDE_OPERATOR, PSEUDO_CLASS_SELECTOR, PSEUDO_ELEMENT_SELECTOR, SELECTOR, SELECTOR_LIST, STRING, STYLESHEET, STYLE_RULE, SUPPORTS_QUERY, TYPE_SELECTOR, UNIVERSAL_SELECTOR, URL } from './arena.js';
+export { NODE_TYPES } from './constants.js';
 export { TOKEN_AT_KEYWORD, TOKEN_BAD_STRING, TOKEN_BAD_URL, TOKEN_CDC, TOKEN_CDO, TOKEN_COLON, TOKEN_COMMA, TOKEN_COMMENT, TOKEN_DELIM, TOKEN_DIMENSION, TOKEN_EOF, TOKEN_FUNCTION, TOKEN_HASH, TOKEN_IDENT, TOKEN_LEFT_BRACE, TOKEN_LEFT_BRACKET, TOKEN_LEFT_PAREN, TOKEN_NUMBER, TOKEN_PERCENTAGE, TOKEN_RIGHT_BRACE, TOKEN_RIGHT_BRACKET, TOKEN_RIGHT_PAREN, TOKEN_SEMICOLON, TOKEN_STRING, TOKEN_URL, TOKEN_WHITESPACE } from './token-types.js';

package/dist/parse-selector.js

@@ -2,7 +2,7 @@ import { Lexer } from './lexer.js';
 import { CSSDataArena, SELECTOR_LIST, SELECTOR, COMBINATOR, NESTING_SELECTOR, ID_SELECTOR, TYPE_SELECTOR, UNIVERSAL_SELECTOR, CLASS_SELECTOR, ATTRIBUTE_SELECTOR, ATTR_OPERATOR_NONE, ATTR_FLAG_NONE, ATTR_OPERATOR_EQUAL, ATTR_OPERATOR_TILDE_EQUAL, ATTR_OPERATOR_PIPE_EQUAL, ATTR_OPERATOR_CARET_EQUAL, ATTR_OPERATOR_DOLLAR_EQUAL, ATTR_OPERATOR_STAR_EQUAL, ATTR_FLAG_CASE_INSENSITIVE, ATTR_FLAG_CASE_SENSITIVE, PSEUDO_ELEMENT_SELECTOR, PSEUDO_CLASS_SELECTOR, FLAG_HAS_PARENS, LANG_SELECTOR, NTH_OF_SELECTOR } from './arena.js';
 import { TOKEN_COMMA, TOKEN_DELIM, TOKEN_EOF, TOKEN_WHITESPACE, TOKEN_FUNCTION, TOKEN_COLON, TOKEN_LEFT_BRACKET, TOKEN_HASH, TOKEN_IDENT, TOKEN_RIGHT_BRACKET, TOKEN_LEFT_PAREN, TOKEN_RIGHT_PAREN, TOKEN_STRING } from './token-types.js';
 import { skip_whitespace_and_comments_forward, skip_whitespace_and_comments_backward, skip_whitespace_forward } from './parse-utils.js';
-import { CHAR_GREATER_THAN, CHAR_PLUS, CHAR_TILDE, CHAR_PERIOD, CHAR_ASTERISK, CHAR_AMPERSAND, CHAR_PIPE, CHAR_SPACE, CHAR_NEWLINE, CHAR_CARRIAGE_RETURN, CHAR_FORM_FEED, is_combinator, is_whitespace, CHAR_EQUALS, CHAR_CARET, CHAR_DOLLAR, CHAR_SINGLE_QUOTE, CHAR_DOUBLE_QUOTE, CHAR_COLON, str_equals } from './string-utils.js';
+import { CHAR_GREATER_THAN, CHAR_PLUS, CHAR_TILDE, CHAR_PERIOD, CHAR_ASTERISK, CHAR_AMPERSAND, CHAR_PIPE, CHAR_SPACE, CHAR_TAB, CHAR_NEWLINE, CHAR_CARRIAGE_RETURN, CHAR_FORM_FEED, is_combinator, is_whitespace, CHAR_EQUALS, CHAR_CARET, CHAR_DOLLAR, CHAR_SINGLE_QUOTE, CHAR_DOUBLE_QUOTE, CHAR_COLON, str_equals } from './string-utils.js';
 import { ANplusBParser } from './parse-anplusb.js';
 import { CSSNode } from './css-node.js';
 
@@ -108,7 +108,10 @@ class SelectorParser {
       }
       const saved = this.lexer.save_position();
       this.skip_whitespace();
-      if (this.lexer.pos >= this.selector_end) break;
+      if (this.lexer.pos >= this.selector_end) {
+        this.lexer.restore_position(saved);
+        break;
+      }
       this.lexer.next_token_fast(false);
       let token_type = this.lexer.token_type;
       if (token_type === TOKEN_COMMA || this.lexer.pos >= this.selector_end) {
@@ -239,14 +242,17 @@ class SelectorParser {
     let has_whitespace = false;
     while (this.lexer.pos < this.selector_end) {
       let ch = this.source.charCodeAt(this.lexer.pos);
-      if (ch === CHAR_SPACE || ch === CHAR_NEWLINE || ch === CHAR_CARRIAGE_RETURN || ch === CHAR_FORM_FEED) {
+      if (ch === CHAR_SPACE || ch === CHAR_TAB || ch === CHAR_NEWLINE || ch === CHAR_CARRIAGE_RETURN || ch === CHAR_FORM_FEED) {
         has_whitespace = true;
         this.lexer.pos++;
       } else {
         break;
       }
     }
-    if (this.lexer.pos >= this.selector_end) return null;
+    if (this.lexer.pos >= this.selector_end) {
+      this.lexer.pos = whitespace_start;
+      return null;
+    }
     this.lexer.next_token_fast(false);
     if (this.lexer.token_type === TOKEN_DELIM) {
       let ch = this.source.charCodeAt(this.lexer.token_start);
@@ -258,7 +264,7 @@ class SelectorParser {
       this.lexer.pos = whitespace_start;
       while (this.lexer.pos < this.selector_end) {
         let ch = this.source.charCodeAt(this.lexer.pos);
-        if (ch === CHAR_SPACE || ch === CHAR_NEWLINE || ch === CHAR_CARRIAGE_RETURN || ch === CHAR_FORM_FEED) {
+        if (ch === CHAR_SPACE || ch === CHAR_TAB || ch === CHAR_NEWLINE || ch === CHAR_CARRIAGE_RETURN || ch === CHAR_FORM_FEED) {
           this.lexer.pos++;
         } else {
           break;

package/dist/walk.d.ts

@@ -1,20 +1,74 @@
 import type { CSSNode } from './css-node';
-type WalkCallback = (node: CSSNode, depth: number) => void;
+export declare const SKIP: unique symbol;
+export declare const BREAK: unique symbol;
+type WalkCallback = (node: CSSNode, depth: number) => void | typeof SKIP | typeof BREAK;
 /**
  * Walk the AST in depth-first order, calling the callback for each node
+ *
  * @param node - The root node to start walking from
- * @param callback - Function to call for each node visited. Receives the node and its depth (0 for root)
+ * @param callback - Function to call for each node visited. Receives the node and its depth (0 for root).
+ *                   Return SKIP to skip children of current node, or BREAK to stop traversal entirely.
+ * @param depth - Starting depth (default: 0)
+ *
+ * @example
+ * import { parse, walk, SKIP, BREAK } from '@projectwallace/css-parser'
+ *
+ * const ast = parse('.a { .b { .c { color: red; } } }')
+ *
+ * // Skip nested rules
+ * walk(ast, (node) => {
+ *   if (node.type === STYLE_RULE) {
+ *     console.log(node.text)
+ *     return SKIP // Don't visit nested rules
+ *   }
+ * })
+ * // Output: .a { ... }, but not .b or .c
+ *
+ * // Stop on first declaration
+ * walk(ast, (node) => {
+ *   if (node.type === DECLARATION) {
+ *     console.log(node.name)
+ *     return BREAK // Stop traversal
+ *   }
+ * })
  */
-export declare function walk(node: CSSNode, callback: WalkCallback, depth?: number): void;
-type WalkEnterLeaveCallback = (node: CSSNode) => void;
+export declare function walk(node: CSSNode, callback: WalkCallback, depth?: number): boolean;
+type WalkEnterLeaveCallback = (node: CSSNode) => void | typeof SKIP | typeof BREAK;
 interface WalkEnterLeaveOptions {
     enter?: WalkEnterLeaveCallback;
     leave?: WalkEnterLeaveCallback;
 }
 /**
  * Walk the AST in depth-first order, calling enter before visiting children and leave after
+ *
  * @param node - The root node to start walking from
  * @param options - Object with optional enter and leave callback functions
+ * @param options.enter - Called before visiting children. Return SKIP to skip children (leave still called),
+ *                        or BREAK to stop traversal entirely (leave NOT called).
+ * @param options.leave - Called after visiting children. Return BREAK to stop traversal.
+ *
+ * @example
+ * import { parse, traverse, SKIP, BREAK } from '@projectwallace/css-parser'
+ *
+ * const ast = parse('@media screen { .a { color: red; } }')
+ *
+ * // Track context with skip
+ * let depth = 0
+ * traverse(ast, {
+ *   enter(node) {
+ *     depth++
+ *     if (node.type === AT_RULE) {
+ *       console.log('Entering media query at depth', depth)
+ *       return SKIP // Skip contents but still call leave
+ *     }
+ *   },
+ *   leave(node) {
+ *     if (node.type === AT_RULE) {
+ *       console.log('Leaving media query at depth', depth)
+ *     }
+ *     depth--
+ *   }
+ * })
  */
-export declare function traverse(node: CSSNode, { enter, leave }?: WalkEnterLeaveOptions): void;
+export declare function traverse(node: CSSNode, { enter, leave }?: WalkEnterLeaveOptions): boolean;
 export {};

package/dist/walk.js

@@ -1,21 +1,45 @@
+const SKIP = Symbol("SKIP");
+const BREAK = Symbol("BREAK");
 function walk(node, callback, depth = 0) {
-  callback(node, depth);
+  const result = callback(node, depth);
+  if (result === BREAK) {
+    return false;
+  }
+  if (result === SKIP) {
+    return true;
+  }
   let child = node.first_child;
   while (child) {
-    walk(child, callback, depth + 1);
+    const should_continue = walk(child, callback, depth + 1);
+    if (!should_continue) {
+      return false;
+    }
     child = child.next_sibling;
   }
+  return true;
 }
 const NOOP = function() {
 };
 function traverse(node, { enter = NOOP, leave = NOOP } = {}) {
-  enter(node);
-  let child = node.first_child;
-  while (child) {
-    traverse(child, { enter, leave });
-    child = child.next_sibling;
+  const enter_result = enter(node);
+  if (enter_result === BREAK) {
+    return false;
+  }
+  if (enter_result !== SKIP) {
+    let child = node.first_child;
+    while (child) {
+      const should_continue = traverse(child, { enter, leave });
+      if (!should_continue) {
+        return false;
+      }
+      child = child.next_sibling;
+    }
+  }
+  const leave_result = leave(node);
+  if (leave_result === BREAK) {
+    return false;
   }
-  leave(node);
+  return true;
 }
 
-export { traverse, walk };
+export { BREAK, SKIP, traverse, walk };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@projectwallace/css-parser",
-	"version": "0.8.0",
+	"version": "0.8.1",
 	"description": "High-performance CSS lexer and parser, optimized for CSS inspection and analysis",
 	"author": "Bart Veneman <bat@projectwallace.com>",
 	"license": "MIT",