ReviewOS

also looking at this

stacks/ts-css

Merge @stacksjs/ts-css into this repo as packages/toolkit

#27
Merged glennmichael123 wants to merge merge/ts-css-toolkit into main
128 files +9797 -201
packages/toolkit/docs/api/parse.mdadded+166-0
Changes to packages/toolkit/docs/api/parse.md
@@ -0,0 +1,166 @@
1# Parser API
2
3Replaces `css-tree`. Tokenizer, recursive-descent parser, walker,
4generator, deep clone, and a doubly-linked `List`.
5
6```ts
7import { clone, generate, List, parse, walk } from '@stacksjs/ts-css'
8// or, when you only need the parser:
9import { /* … */ } from '@stacksjs/ts-css/parse'
10```
11
12## `parse(source, options?)`
13
14Parse a CSS source string into an AST.
15
16```ts
17parse(source: string, options?: ParseOptions): CssNode
18```
19
20### Options
21
22| Option | Default | Description |
23| ----------------------- | -------------- | ------------------------------------------------------------------------ |
24| `context` | `'stylesheet'` | What grammar to parse against (see below). |
25| `parseValue` | `true` | When `false`, declaration values are stored as `Raw` nodes. |
26| `parseAtrulePrelude` | `true` | When `false`, at-rule preludes are stored as `Raw`. |
27| `parseRulePrelude` | `true` | When `false`, rule preludes (selector lists) are stored as `Raw`. |
28| `parseCustomProperty` | `false` | When `true`, custom property values are parsed (otherwise `Raw`). |
29| `positions` | `false` | Track source `loc` info on every node. |
30| `filename` | — | Source filename, used in `loc.source`. |
31| `onParseError` | — | Called when the parser substitutes a `Raw` node for an error. |
32
33### Parse contexts
34
35| `context` | Returns | Use for |
36| ------------------- | ------------------------------------ | ---------------------------------------------------- |
37| `'stylesheet'` | `StyleSheet` | Top-level CSS files (default) |
38| `'atrule'` | `Atrule \| StyleSheet` | A single `@rule …;` or `@rule { … }` |
39| `'atrulePrelude'` | `AtrulePrelude` | The `(min-width: 800px)` part of a media query |
40| `'rule'` | `Rule` | A single `selector { … }` block |
41| `'block'` | `Block` | Just the `{ decl; decl; }` body |
42| `'declarationList'` | `DeclarationList` | A `style="…"` attribute body |
43| `'declaration'` | `Declaration` | A single `prop: value;` line |
44| `'value'` | `Value` | Just the value side of a declaration |
45| `'selector'` | `Selector` | A single selector segment (`a > b`) |
46| `'selectorList'` | `SelectorList` | A comma-separated list (`a, b > c`) |
47
48## `walk(ast, visitor)`
49
50Recursively traverse the AST.
51
52```ts
53walk(ast: CssNode, visitor: WalkVisitor): symbol | undefined
54```
55
56`visitor` is either:
57- A function: `(node, item, list) => void | symbol`
58- An object: `{ visit?, enter?, leave?, reverse? }`
59
60Inside callbacks, `this` carries traversal context: `this.atrule`,
61`this.rule`, `this.selector`, `this.declaration`, etc.
62
63```ts
64walk(ast, {
65 visit: 'Declaration',
66 enter(decl) {
67 if (decl.property === 'color')
68 decl.value = parse('blue', { context: 'value' })
69 },
70})
71```
72
73### Sentinels
74
75| Constant | What it does |
76| ------------- | --------------------------------------------------------- |
77| `walk.skip` | Return from `enter` to skip the node's children. |
78| `walk.stop` | Return to halt the entire traversal. |
79
80## `generate(node)`
81
82Serialize an AST node back to a CSS string. Output is compact (no
83unnecessary whitespace) — comparable to `csstree.generate(node)` with
84no formatting options.
85
86```ts
87generate(node: CssNode): string
88```
89
90## `clone(node)`
91
92Deep-clone an AST node, preserving the `List` structure of children.
93
94```ts
95clone<T extends CssNode>(node: T): T
96```
97
98## `List<T>`
99
100Doubly linked list — every container node uses one for its `children`.
101
102```ts
103import { List } from '@stacksjs/ts-css'
104
105const list = new List<number>()
106list.appendData(1)
107list.appendData(2)
108list.toArray() // [1, 2]
109```
110
111### Mutation methods
112
113| Method | Description |
114| --------------------------- | ------------------------------------------------- |
115| `appendData(data)` | Append a new item built from `data`. |
116| `prependData(data)` | Prepend a new item. |
117| `insertData(data, before?)` | Insert before `before` (a `ListItem`), or at tail. |
118| `insert(item, before?)` | Insert an existing `ListItem`. |
119| `remove(item)` | Detach an item from the list. |
120| `replace(old, newItem)` | Replace `old` with `newItem` (or another `List`). |
121| `clear()` | Detach all items. |
122
123### Iteration
124
125| Method | Callback signature |
126| ------------------------------- | ----------------------------------------------- |
127| `forEach(fn)` | `(data, item, list)` — matches `css-tree`. |
128| `forEachRight(fn)` | Same, in reverse. |
129| `reduce(fn, init)` | `(acc, data, index, list)` |
130| `some(fn)` | `(data, index, list) => boolean` |
131| `map(fn)` | Returns a new `List`. |
132| `filter(fn)` | Returns a new `List`. |
133
134The `forEach` / `forEachRight` callbacks honor a cursor protocol so
135callbacks can safely insert/remove items mid-walk without breaking the
136iterator.
137
138## AST node reference
139
140The full discriminated union is `CssNode`. The most common variants:
141
142```ts
143interface StyleSheet { type: 'StyleSheet', children: List<CssNode> }
144interface Rule { type: 'Rule', prelude: SelectorList | Raw, block: Block }
145interface Atrule { type: 'Atrule', name: string, prelude: AtrulePrelude | Raw | null, block: Block | null }
146interface Block { type: 'Block', children: List<CssNode> }
147interface Declaration { type: 'Declaration', property: string, value: Value | Raw, important: boolean | string }
148interface Value { type: 'Value', children: List<CssNode> }
149interface Selector { type: 'Selector', children: List<CssNode> }
150// + identifiers, numbers, dimensions, hashes, urls, functions, …
151```
152
153See `src/parse/types.ts` for the complete type definitions.
154
155## Tokenizer (advanced)
156
157If you need raw token output, import `Tokenizer` directly:
158
159```ts
160import { Tokenizer, TokenType } from '@stacksjs/ts-css/parse'
161
162const t = new Tokenizer('.foo { color: red }')
163for (const tok of t.tokens) {
164 console.log(TokenType[tok.type], tok.start, tok.end)
165}
166```