@projectwallace/css-parser 0.18.9 → 0.18.11

package/README.md

@@ -25,7 +25,7 @@ npm install @projectwallace/css-parser
 ## Usage
 
 ```typescript
-import { parse, NODE_STYLE_RULE, NODE_DECLARATION } from '@projectwallace/css-parser'
+import { parse, STYLE_RULE, DECLARATION } from '@projectwallace/css-parser'
 
 const ast = parse(`
   body {
@@ -42,13 +42,13 @@ const ast = parse(`
 
 // Iterate over top-level rules
 for (const rule of ast) {
-	if (rule.type === NODE_STYLE_RULE) {
+	if (rule.type === STYLE_RULE) {
 		const selector = rule.first_child
 		console.log(`Selector: ${selector.text}`)
 
 		// Iterate over declarations
 		for (const node of rule) {
-			if (node.type === NODE_DECLARATION) {
+			if (node.type === DECLARATION) {
 				console.log(`  ${node.property}: ${node.value}`)
 			}
 		}
@@ -63,25 +63,193 @@ for (const rule of ast) {
 - **Location tracking with no penalty** — full line, column, and offset data without slowing the parser down
 - **No syntax validation** — skipping spec checks and MDN data means nothing gets in the way of speed
 
-### Bundle sizes
+## API
 
-All sizes are minified and bundled with dependencies. Import only what you need — bundlers will tree-shake the rest.
+Everything is exported from the package root. Each part is also available from its own entry point, so you can import only what you need and skip evaluating the rest of the package. Node properties and return types ship as TypeScript types, so this section sticks to short examples.
 
-| Import                                            | Description                  | Minified | Gzip    |
-| ------------------------------------------------- | ---------------------------- | -------- | ------- |
-| `@projectwallace/css-parser`                      | Full parser (all subparsers) | 68.9 kB  | 15.5 kB |
-| `@projectwallace/css-parser/parse`                | CSS stylesheet parser        | 62.2 kB  | 13.3 kB |
-| `@projectwallace/css-parser/parse-atrule-prelude` | At-rule prelude parser       | 35.4 kB  | 8.4 kB  |
-| `@projectwallace/css-parser/parse-selector`       | Selector parser              | 37.7 kB  | 8.9 kB  |
-| `@projectwallace/css-parser/parse-anplusb`        | An+B syntax parser           | 26.1 kB  | 6.6 kB  |
-| `@projectwallace/css-parser/parse-declaration`    | Declaration parser           | 28.3 kB  | 7.3 kB  |
-| `@projectwallace/css-parser/parse-value`          | Value parser                 | 25.2 kB  | 6.6 kB  |
-| `@projectwallace/css-parser/parse-dimension`      | Dimension parser             | 0.4 kB   | 0.3 kB  |
-| `@projectwallace/css-parser/tokenizer`            | Tokenizer                    | 9.8 kB   | 2.4 kB  |
+### Entry points
 
-## Documentation
+| Import                                            | Exports                                                                                                   |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@projectwallace/css-parser`                      | Everything below, except the `Lexer` and `Parser` classes                                                 |
+| `@projectwallace/css-parser/parse`                | `parse`, `Parser`, `ParserOptions`                                                                        |
+| `@projectwallace/css-parser/parse-selector`       | `parse_selector`, `parse_selector_list`                                                                   |
+| `@projectwallace/css-parser/parse-atrule-prelude` | `parse_atrule_prelude`                                                                                    |
+| `@projectwallace/css-parser/parse-declaration`    | `parse_declaration`                                                                                       |
+| `@projectwallace/css-parser/parse-value`          | `parse_value`                                                                                             |
+| `@projectwallace/css-parser/parse-anplusb`        | `parse_anplusb`                                                                                           |
+| `@projectwallace/css-parser/parse-dimension`      | `parse_dimension`                                                                                         |
+| `@projectwallace/css-parser/tokenizer`            | `tokenize`, `Lexer`                                                                                       |
+| `@projectwallace/css-parser/walker`               | `walk`, `traverse`, `SKIP`, `BREAK`                                                                       |
+| `@projectwallace/css-parser/nodes`                | Node type constants (`STYLE_RULE`, `DECLARATION`, …), `NODE_TYPES`                                        |
+| `@projectwallace/css-parser/node-types`           | Type guards (`is_declaration`, `is_rule`, …) and node types (`CSSNode`, `Rule`, `Declaration`, …)         |
+| `@projectwallace/css-parser/string-utils`         | `is_custom`, `is_vendor_prefixed`, `strip_vendor_prefix`, `str_equals`, `str_starts_with`, `str_index_of` |
+| `@projectwallace/css-parser/token-types`          | Token type constants (`TOKEN_*`)                                                                          |
 
-See [API.md](./API.md) for complete documentation of all parser functions and nodes.
+### `parse(source, options?)`
+
+Parses a full stylesheet and returns the root `StyleSheet` node. Nodes are iterable and expose `first_child`, `next_sibling`, `children`, `text`, `line`, `column`, `start`, `end` and `length`.
+
+```typescript
+import { parse } from '@projectwallace/css-parser'
+
+const ast = parse('body { color: red; }')
+const rule = ast.first_child
+rule.block.first_child.property // "color"
+rule.block.first_child.value.text // "red"
+```
+
+Options:
+
+- `parse_values` (default `true`) — parse declaration values into nodes
+- `parse_selectors` (default `true`) — parse selectors into nodes
+- `parse_atrule_preludes` (default `true`) — parse at-rule preludes into nodes
+- `on_comment` — called for every comment; comments are never part of the tree
+
+```typescript
+const comments = []
+parse('/* hi */ a { color: red }', {
+	parse_values: false,
+	on_comment: (info) => comments.push(info), // { start, end, length, line, column }
+})
+```
+
+### `parse_selector(source)` and `parse_selector_list(source)`
+
+`parse_selector` returns the first selector, `parse_selector_list` the whole `SelectorList`.
+
+```typescript
+import { parse_selector, parse_selector_list } from '@projectwallace/css-parser'
+
+parse_selector('a.b > c').children.map((part) => part.text) // ["a", ".b", ">", "c"]
+parse_selector_list('h1, h2').children.map((s) => s.text) // ["h1", "h2"]
+```
+
+### `parse_declaration(source)`
+
+```typescript
+import { parse_declaration } from '@projectwallace/css-parser'
+
+const decl = parse_declaration('color: red !important')
+decl.property // "color"
+decl.is_important // true
+decl.value.text // "red"
+```
+
+### `parse_value(source)`
+
+Parses a declaration value into a `Value` node with one child per component.
+
+```typescript
+import { parse_value } from '@projectwallace/css-parser'
+
+for (const node of parse_value('10px 20px')) {
+	console.log(node.type_name, node.value, node.unit) // "Dimension" 10 "px", then "Dimension" 20 "px"
+}
+```
+
+### `parse_atrule_prelude(name, prelude)`
+
+Returns an array of nodes for the prelude of the at-rule called `name` (without the `@`).
+
+```typescript
+import { parse_atrule_prelude } from '@projectwallace/css-parser'
+
+const [query] = parse_atrule_prelude('media', '(min-width: 768px)')
+query.type_name // "MediaQuery"
+```
+
+### `parse_dimension(text)`
+
+Splits a number from its unit. It works for anything shaped like a number followed by a unit: lengths (`100px`), percentages (`2%`), durations (`200ms`) and so on. It does not validate; text without a leading number gives `value: 0`.
+
+```typescript
+import { parse_dimension } from '@projectwallace/css-parser'
+
+parse_dimension('100px') // { value: 100, unit: "px" }
+parse_dimension('2%') // { value: 2, unit: "%" }
+parse_dimension('1.5e3s') // { value: 1500, unit: "s" }
+parse_dimension('5') // { value: 5, unit: "" }
+```
+
+### `walk(node, callback)` and `traverse(node, { enter, leave })`
+
+Both walk the tree depth-first. Return `SKIP` to skip the children of a node and `BREAK` to stop entirely. `walk` also passes a `depth` that counts rule and at-rule nesting. `traverse` calls `enter` before and `leave` after the children (`leave` still runs after `SKIP`, but not after `BREAK`).
+
+```typescript
+import {
+	parse,
+	walk,
+	traverse,
+	SKIP,
+	BREAK,
+	DECLARATION,
+	AT_RULE,
+} from '@projectwallace/css-parser'
+
+const ast = parse('@media screen { a { color: red; margin: 0 } }')
+
+walk(ast, (node) => {
+	if (node.type === DECLARATION) {
+		console.log(node.property) // "color"
+		return BREAK
+	}
+})
+
+traverse(ast, {
+	enter(node) {
+		if (node.type === AT_RULE) return SKIP // leave() still runs for this node
+	},
+	leave(node) {},
+})
+```
+
+### `tokenize(source, on_comment?)`
+
+A generator of tokens; comments are skipped and reported through `on_comment`.
+
+```typescript
+import { tokenize } from '@projectwallace/css-parser'
+
+for (const token of tokenize('a { color: red }')) {
+	console.log(token.type, token.start, token.end)
+}
+```
+
+### Node types, type guards and `clone()`
+
+Node type constants (`STYLE_RULE`, `DECLARATION`, `DIMENSION`, …) and `NODE_TYPES` are exported from the root and from `@projectwallace/css-parser/nodes`. Type guards such as `is_declaration()` and `is_dimension()` that narrow a node to its specific type are exported from the root and from `@projectwallace/css-parser/node-types`. `node.clone({ deep?, locations? })` returns a mutable plain-object copy of a node.
+
+```typescript
+import { parse, is_declaration } from '@projectwallace/css-parser'
+
+const decl = parse('a { color: red }').first_child.block.first_child
+is_declaration(decl) // true
+decl.type_name // "Declaration"
+decl.clone({ deep: false }).property // "color"
+```
+
+### String helpers
+
+Allocation-free helpers, handy when working with node names. Also available from `@projectwallace/css-parser/string-utils`; token type constants (`TOKEN_*`) are available from `@projectwallace/css-parser/token-types`. The lowercase argument is the first one for `str_equals` and the second one for `str_starts_with` and `str_index_of`. This inconsistency will be fixed in a future breaking change.
+
+```typescript
+import {
+	is_custom,
+	is_vendor_prefixed,
+	strip_vendor_prefix,
+	str_equals,
+	str_starts_with,
+	str_index_of,
+} from '@projectwallace/css-parser'
+
+is_custom('--primary') // true
+is_vendor_prefixed('-webkit-transform') // true
+strip_vendor_prefix('-webkit-transform') // "transform"
+str_equals('media', 'MEDIA') // true
+str_starts_with('WEBKIT-transform', 'webkit') // true
+str_index_of('background-COLOR', 'color') // 11
+```
 
 ## Non-goals
 

package/dist/{arena-e9O_g2AN.js → arena-Bsf96CQK.js}

@@ -1,5 +1,5 @@
 //#region src/arena.ts
-let BYTES_PER_NODE = 32;
+const BYTES_PER_NODE = 32;
 const STYLESHEET = 1;
 const STYLE_RULE = 2;
 const AT_RULE = 3;
@@ -66,9 +66,9 @@ var CSSDataArena = class CSSDataArena {
 		this.overflow_lengths = /* @__PURE__ */ new Map();
 	}
 	static capacity_for_source(source_length) {
-		let size_in_kb = source_length / 1024;
-		let estimated_nodes = Math.ceil(size_in_kb * CSSDataArena.NODES_PER_KB);
-		let capacity = Math.ceil(estimated_nodes * CSSDataArena.CAPACITY_BUFFER);
+		const size_in_kb = source_length / 1024;
+		const estimated_nodes = Math.ceil(size_in_kb * CSSDataArena.NODES_PER_KB);
+		const capacity = Math.ceil(estimated_nodes * CSSDataArena.CAPACITY_BUFFER);
 		return Math.max(16, capacity);
 	}
 	get_count() {
@@ -93,11 +93,16 @@ var CSSDataArena = class CSSDataArena {
 		return this.view.getUint32(this.node_offset(node_index) + 12, true);
 	}
 	get_length(node_index) {
+		const length = this.view.getUint16(this.node_offset(node_index) + 2, true);
+		if (length === 65535) return this.get_overflow_length(node_index);
+		return length;
+	}
+	get_overflow_length(node_index) {
 		if (this.has_flag(node_index, 4)) {
 			const overflow_length = this.overflow_lengths.get(node_index);
 			if (overflow_length !== void 0) return overflow_length;
 		}
-		return this.view.getUint16(this.node_offset(node_index) + 2, true);
+		return 65535;
 	}
 	get_content_start(node_index) {
 		return this.get_start_offset(node_index) + this.view.getUint16(this.node_offset(node_index) + 16, true);
@@ -130,11 +135,13 @@ var CSSDataArena = class CSSDataArena {
 		this.view.setUint8(this.node_offset(node_index) + 1, flags);
 	}
 	set_length(node_index, length) {
-		if (length > 65535) {
-			this.view.setUint16(this.node_offset(node_index) + 2, 65535, true);
-			this.set_flag(node_index, 4);
-			this.overflow_lengths.set(node_index, length);
-		} else this.view.setUint16(this.node_offset(node_index) + 2, length, true);
+		if (length > 65535) this.set_length_overflow(node_index, length);
+		else this.view.setUint16(this.node_offset(node_index) + 2, length, true);
+	}
+	set_length_overflow(node_index, length) {
+		this.view.setUint16(this.node_offset(node_index) + 2, 65535, true);
+		this.set_flag(node_index, 4);
+		this.overflow_lengths.set(node_index, length);
 	}
 	set_content_start_delta(node_index, delta) {
 		this.view.setUint16(this.node_offset(node_index) + 16, delta, true);
@@ -156,8 +163,8 @@ var CSSDataArena = class CSSDataArena {
 	}
 	grow() {
 		this.growth_count++;
-		let new_capacity = Math.ceil(this.capacity * CSSDataArena.GROWTH_FACTOR);
-		let new_buffer = /* @__PURE__ */ new ArrayBuffer(new_capacity * BYTES_PER_NODE);
+		const new_capacity = Math.ceil(this.capacity * CSSDataArena.GROWTH_FACTOR);
+		const new_buffer = /* @__PURE__ */ new ArrayBuffer(new_capacity * BYTES_PER_NODE);
 		new Uint8Array(new_buffer).set(new Uint8Array(this.buffer));
 		this.buffer = new_buffer;
 		this.view = new DataView(new_buffer);
@@ -172,7 +179,8 @@ var CSSDataArena = class CSSDataArena {
 		this.view.setUint32(offset + 12, start_offset, true);
 		this.view.setUint32(offset + 24, start_line, true);
 		this.view.setUint32(offset + 28, start_column, true);
-		this.set_length(node_index, length);
+		if (length > 65535) this.set_length_overflow(node_index, length);
+		else this.view.setUint16(offset + 2, length, true);
 		return node_index;
 	}
 	append_children(parent_index, children) {
@@ -184,8 +192,8 @@ var CSSDataArena = class CSSDataArena {
 	/** Shrink the buffer to the live node count, releasing wasted capacity. Call once after parsing; no-op if already tight. */
 	trim() {
 		if (this.count === this.capacity) return;
-		let byte_count = this.count * BYTES_PER_NODE;
-		let new_buffer = new ArrayBuffer(byte_count);
+		const byte_count = this.count * BYTES_PER_NODE;
+		const new_buffer = new ArrayBuffer(byte_count);
 		new Uint8Array(new_buffer).set(new Uint8Array(this.buffer, 0, byte_count));
 		this.buffer = new_buffer;
 		this.view = new DataView(new_buffer);
@@ -207,12 +215,12 @@ var CSSDataArena = class CSSDataArena {
 		return this.get_next_sibling(node_index) !== 0;
 	}
 	set_flag(node_index, flag) {
-		let current_flags = this.get_flags(node_index);
-		this.set_flags(node_index, current_flags | flag);
+		const offset = node_index * BYTES_PER_NODE + 1;
+		this.view.setUint8(offset, this.view.getUint8(offset) | flag);
 	}
 	clear_flag(node_index, flag) {
-		let current_flags = this.get_flags(node_index);
-		this.set_flags(node_index, current_flags & ~flag);
+		const offset = node_index * BYTES_PER_NODE + 1;
+		this.view.setUint8(offset, this.view.getUint8(offset) & ~flag);
 	}
 	has_flag(node_index, flag) {
 		return (this.get_flags(node_index) & flag) !== 0;

package/dist/{arena-BGvFdbj5.d.ts → arena-DvT75bvK.d.ts}

@@ -67,6 +67,7 @@ declare class CSSDataArena {
   get_flags(node_index: number): number;
   get_start_offset(node_index: number): number;
   get_length(node_index: number): number;
+  private get_overflow_length;
   get_content_start(node_index: number): number;
   get_content_length(node_index: number): number;
   get_first_child(node_index: number): number;
@@ -78,6 +79,7 @@ declare class CSSDataArena {
   set_type(node_index: number, type: number): void;
   set_flags(node_index: number, flags: number): void;
   set_length(node_index: number, length: number): void;
+  private set_length_overflow;
   set_content_start_delta(node_index: number, delta: number): void;
   set_content_length(node_index: number, length: number): void;
   set_first_child(node_index: number, childIndex: number): void;

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-import { A as PARENTHESIS, B as STYLESHEET, C as MEDIA_QUERY, D as NTH_SELECTOR, E as NTH_OF_SELECTOR, F as RATIO, G as UNICODE_RANGE, H as SUPPORTS_DECLARATION, I as RAW, J as VALUE, K as UNIVERSAL_SELECTOR, L as SELECTOR, N as PSEUDO_CLASS_SELECTOR, O as NUMBER, P as PSEUDO_ELEMENT_SELECTOR, R as SELECTOR_LIST, S as MEDIA_FEATURE, T as NESTING_SELECTOR, U as SUPPORTS_QUERY, V as STYLE_RULE, W as TYPE_SELECTOR, _ as ID_SELECTOR, a as CLASS_SELECTOR, b as LANG_SELECTOR, c as CONTAINER_QUERY, d as DIMENSION, f as FEATURE_RANGE, g as IDENTIFIER, h as HASH, i as BLOCK, j as PRELUDE_OPERATOR, k as OPERATOR, m as FUNCTION, n as AT_RULE, o as COMBINATOR, p as FLAG_IMPORTANT, q as URL, r as AT_RULE_PRELUDE, s as COMMENT, t as ATTRIBUTE_SELECTOR, u as DECLARATION, v as IF_BRANCH, w as MEDIA_TYPE, x as LAYER_NAME, y as IF_CONDITION, z as STRING } from "./arena-BGvFdbj5.js";
+import { A as PARENTHESIS, B as STYLESHEET, C as MEDIA_QUERY, D as NTH_SELECTOR, E as NTH_OF_SELECTOR, F as RATIO, G as UNICODE_RANGE, H as SUPPORTS_DECLARATION, I as RAW, J as VALUE, K as UNIVERSAL_SELECTOR, L as SELECTOR, N as PSEUDO_CLASS_SELECTOR, O as NUMBER, P as PSEUDO_ELEMENT_SELECTOR, R as SELECTOR_LIST, S as MEDIA_FEATURE, T as NESTING_SELECTOR, U as SUPPORTS_QUERY, V as STYLE_RULE, W as TYPE_SELECTOR, _ as ID_SELECTOR, a as CLASS_SELECTOR, b as LANG_SELECTOR, c as CONTAINER_QUERY, d as DIMENSION, f as FEATURE_RANGE, g as IDENTIFIER, h as HASH, i as BLOCK, j as PRELUDE_OPERATOR, k as OPERATOR, m as FUNCTION, n as AT_RULE, o as COMBINATOR, p as FLAG_IMPORTANT, q as URL, r as AT_RULE_PRELUDE, s as COMMENT, t as ATTRIBUTE_SELECTOR, u as DECLARATION, v as IF_BRANCH, w as MEDIA_TYPE, x as LAYER_NAME, y as IF_CONDITION, z as STRING } from "./arena-DvT75bvK.js";
 //#region src/constants.d.ts
 export declare const NODE_TYPES: {
   readonly STYLESHEET: 1;

package/dist/constants.js

@@ -1,4 +1,4 @@
-import { A as PARENTHESIS, B as STYLE_RULE, C as MEDIA_QUERY, D as NTH_SELECTOR, E as NTH_OF_SELECTOR, F as RAW, G as UNIVERSAL_SELECTOR, H as SUPPORTS_QUERY, I as SELECTOR, K as URL, L as SELECTOR_LIST, M as PSEUDO_CLASS_SELECTOR, N as PSEUDO_ELEMENT_SELECTOR, O as NUMBER, P as RATIO, R as STRING, S as MEDIA_FEATURE, T as NESTING_SELECTOR, U as TYPE_SELECTOR, V as SUPPORTS_DECLARATION, W as UNICODE_RANGE, _ as ID_SELECTOR, a as CLASS_SELECTOR, b as LANG_SELECTOR, c as CONTAINER_QUERY, d as DIMENSION, f as FEATURE_RANGE, g as IDENTIFIER, h as HASH, i as BLOCK, j as PRELUDE_OPERATOR, k as OPERATOR, m as FUNCTION, n as AT_RULE, o as COMBINATOR, p as FLAG_IMPORTANT, q as VALUE, r as AT_RULE_PRELUDE, s as COMMENT, t as ATTRIBUTE_SELECTOR, u as DECLARATION, v as IF_BRANCH, w as MEDIA_TYPE, x as LAYER_NAME, y as IF_CONDITION, z as STYLESHEET } from "./arena-e9O_g2AN.js";
+import { A as PARENTHESIS, B as STYLE_RULE, C as MEDIA_QUERY, D as NTH_SELECTOR, E as NTH_OF_SELECTOR, F as RAW, G as UNIVERSAL_SELECTOR, H as SUPPORTS_QUERY, I as SELECTOR, K as URL, L as SELECTOR_LIST, M as PSEUDO_CLASS_SELECTOR, N as PSEUDO_ELEMENT_SELECTOR, O as NUMBER, P as RATIO, R as STRING, S as MEDIA_FEATURE, T as NESTING_SELECTOR, U as TYPE_SELECTOR, V as SUPPORTS_DECLARATION, W as UNICODE_RANGE, _ as ID_SELECTOR, a as CLASS_SELECTOR, b as LANG_SELECTOR, c as CONTAINER_QUERY, d as DIMENSION, f as FEATURE_RANGE, g as IDENTIFIER, h as HASH, i as BLOCK, j as PRELUDE_OPERATOR, k as OPERATOR, m as FUNCTION, n as AT_RULE, o as COMBINATOR, p as FLAG_IMPORTANT, q as VALUE, r as AT_RULE_PRELUDE, s as COMMENT, t as ATTRIBUTE_SELECTOR, u as DECLARATION, v as IF_BRANCH, w as MEDIA_TYPE, x as LAYER_NAME, y as IF_CONDITION, z as STYLESHEET } from "./arena-Bsf96CQK.js";
 //#region src/constants.ts
 const NODE_TYPES = {
 	STYLESHEET: 1,