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/what.mdadded+104-0
Changes to packages/toolkit/docs/api/what.md
@@ -0,0 +1,104 @@
1# Selector parser API
2
3Replaces `css-what`. Pure-string-to-selector-AST parsing — separate from
4the matcher, so you can analyse selectors (specificity, rewrites, lint
5rules) without running them.
6
7```ts
8import { isTraversal, parseSelector, stringifySelector } from '@stacksjs/ts-css'
9// or:
10import { parse, stringify, isTraversal } from '@stacksjs/ts-css/what'
11```
12
13## `parse(selector, options?)`
14
15Parse a CSS selector string into a list-of-lists of selector segments.
16
17```ts
18parse(selector: string, options?: ParseOptions): Selector[][]
19```
20
21The outer array is **comma-separated selectors**; the inner arrays are
22**simple selectors and combinators** in source order.
23
24```ts
25import { parse } from '@stacksjs/ts-css/what'
26
27parse('div > p, .foo')
28// [
29// [{type:'tag',name:'div'}, {type:'child'}, {type:'tag',name:'p'}],
30// [{type:'attribute',name:'class',action:'element',value:'foo'}],
31// ]
32```
33
34### Options
35
36| Option | Default | Description |
37| ---------------------------- | ------- | -------------------------------------------------------- |
38| `xmlMode` | `false` | Disable HTML quirks (case-insensitive tags / attrs). |
39| `lowerCaseAttributeNames` | `true` | Lowercase attribute names (HTML default). |
40| `lowerCaseTags` | `true` | Lowercase tag names. |
41
42## `stringify(ast)`
43
44Inverse of `parse` — turn a selector AST back into a string.
45
46```ts
47stringify(ast: Selector[][]): string
48```
49
50```ts
51import { parse, stringify } from '@stacksjs/ts-css/what'
52
53const ast = parse('div > p:not(.x)')
54stringify(ast) // 'div > p:not(.x)'
55```
56
57## `isTraversal(token)`
58
59Returns `true` if `token` is a combinator (descendant / child / sibling /
60adjacent / parent / column-combinator) and not a simple selector.
61
62```ts
63isTraversal(token: Selector): boolean
64```
65
66## Segment types
67
68The `Selector` union contains:
69
70```ts
71type Selector =
72 | { type: 'tag', name: string, namespace: string | null }
73 | { type: 'universal', namespace: string | null }
74 | { type: 'attribute', name: string, action: AttributeAction, value: string, namespace: string | null, ignoreCase: boolean | 'quirks' | null }
75 | { type: 'pseudo', name: string, data: string | Selector[][] | null }
76 | { type: 'pseudo-element', name: string, data: string | null }
77 | { type: 'descendant' }
78 | { type: 'child' }
79 | { type: 'parent' }
80 | { type: 'sibling' }
81 | { type: 'adjacent' }
82 | { type: 'column-combinator' }
83```
84
85`AttributeAction` is one of:
86`'any'`, `'element'`, `'end'`, `'equals'`, `'exists'`, `'hyphen'`, `'not'`, `'start'`.
87
88| `[a]` form | `action` |
89| -------------------- | ------------ |
90| `[a]` | `'exists'` |
91| `[a="x"]` | `'equals'` |
92| `[a~="x"]` | `'element'` |
93| `[a\|="x"]` | `'hyphen'` |
94| `[a^="x"]` | `'start'` |
95| `[a$="x"]` | `'end'` |
96| `[a*="x"]` | `'any'` |
97| `[a!="x"]` | `'not'` |
98
99## Pseudo-class shape
100
101For pseudo-classes that take a selector list (`:is`, `:not`, `:where`,
102`:has`, `:matches`, `:-moz-any`, `:-webkit-any`), the `data` field is
103**already parsed** as a `Selector[][]`. For other pseudo-classes that take
104a string (e.g. `:nth-child(2n+1)`), `data` is the raw inner string.