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/select.mdadded+123-0
Changes to packages/toolkit/docs/api/select.md
@@ -0,0 +1,123 @@
1# Selector matcher API
2
3Replaces `css-select`. Run any CSS selector against any tree-like data
4structure via an `Adapter`.
5
6```ts
7import { compile, is, selectAll, selectOne } from '@stacksjs/ts-css'
8// or:
9import { /* … */ } from '@stacksjs/ts-css/select'
10```
11
12## `selectAll(selector, root, options)`
13
14Return every element under `root` that matches `selector`.
15
16```ts
17selectAll<Node, ElementNode extends Node>(
18 selector: string | Selector[][] | CompiledQuery<ElementNode>,
19 root: Node | Node[],
20 options: Options<Node, ElementNode>,
21): ElementNode[]
22```
23
24## `selectOne(selector, root, options)`
25
26Return the first match (in document order), or `null`.
27
28```ts
29selectOne(...): ElementNode | null
30```
31
32## `is(node, selector, options)`
33
34Test whether `node` itself matches `selector`.
35
36```ts
37is(node, selector, options): boolean
38```
39
40## `compile(selector, options)`
41
42Compile a selector once and reuse the predicate against many trees.
43
44```ts
45const test = compile('p > span.foo', options)
46adapter.findAll(test, [root])
47```
48
49## `Adapter<Node, ElementNode>`
50
51The adapter is the tree-access contract. Every method has the same
52signature as `css-select`'s — if you already have one, it works as-is.
53
54| Method | Returns | Purpose |
55| ------------------------------------------------- | -------------------------------- | ----------------------------------------------- |
56| `isTag(node)` | `node is ElementNode` | Type guard for element-vs-text/comment. |
57| `getName(elem)` | `string` | Element tag name. |
58| `getAttributeValue(elem, name)` | `string \| undefined` | Attribute value (case-sensitive on `name`). |
59| `hasAttrib(elem, name)` | `boolean` | Whether `elem[name]` is set. |
60| `getChildren(node)` | `Node[]` | Direct children of `node`. |
61| `getParent(elem)` | `ElementNode \| null` | Parent element (or null for the root). |
62| `getSiblings(elem)` | `Node[]` | All siblings, including `elem`. |
63| `getText(node)` | `string` | Text content (used by some pseudos). |
64| `findAll(test, elems)` | `ElementNode[]` | DFS traversal. |
65| `findOne(test, elems)` | `ElementNode \| null` | DFS, first match. |
66| `existsOne(test, elems)` | `boolean` | DFS, just a check. |
67| `removeSubsets(nodes)` | `Node[]` | Remove descendants when their ancestor is also in `nodes`. |
68
69Optional state-aware hooks (always called for `:hover` / `:active` /
70`:visited`):
71
72| Method | Default | When you'd implement it |
73| --------------------- | ---------------- | --------------------------------------------- |
74| `isActive(elem)` | always `false` | DOM-aware match for `:active` |
75| `isHovered(elem)` | always `false` | DOM-aware match for `:hover` |
76| `isVisited(elem)` | always `false` | DOM-aware match for `:visited` |
77| `equals(a, b)` | `===` | Custom node equality (rare). |
78
79If your tree has no notion of focus/hover, leave these undefined — the
80matcher treats stateful pseudos as never-matching.
81
82## `Options`
83
84| Option | Default | Description |
85| ---------------------------- | ------- | -------------------------------------------------------------------- |
86| `adapter` | — | **Required.** The `Adapter` for your tree. |
87| `xmlMode` | `false` | Disable HTML quirks (case-insensitive tags / attrs). |
88| `lowerCaseAttributeNames` | `true` | Lowercase attribute names before matching. |
89| `lowerCaseTags` | `true` | Lowercase tag names. |
90| `cacheResults` | `true` | Cache compiled selectors keyed by selector string. |
91| `context` | — | Reference node(s) for `:scope`. |
92| `pseudos` | — | Map of custom pseudo-class implementations. |
93| `relativeSelector` | — | Match `:has` lazily. |
94| `quirksMode` | `false` | Match HTML quirks-mode attribute case rules. |
95
96## Supported selectors
97
98| Category | Examples |
99| --------------------- | --------------------------------------------------- |
100| Type / universal | `div`, `*`, `svg\|circle` (namespaces in xmlMode) |
101| Class / id | `.foo`, `#bar` |
102| Attribute | `[a]`, `[a=x]`, `[a~=x]`, `[a\|=x]`, `[a^=x]`, `[a$=x]`, `[a*=x]` (with `i` / `s` case flags) |
103| Combinators | `a b`, `a > b`, `a + b`, `a ~ b`, `a \|\| b` |
104| Structural pseudos | `:first-child`, `:last-child`, `:only-child`, `:first-of-type`, `:last-of-type`, `:only-of-type`, `:nth-child(...)`, `:nth-last-child(...)`, `:nth-of-type(...)`, `:nth-last-of-type(...)` |
105| Logical pseudos | `:is(...)`, `:not(...)`, `:where(...)`, `:has(...)`, `:matches(...)` |
106| Other pseudos | `:empty`, `:root`, `:scope` |
107| Stateful pseudos | `:hover`, `:active`, `:visited`, `:focus`, etc. — gated on adapter `is*` hooks. |
108
109## Custom pseudo-classes
110
111Add your own via `options.pseudos`:
112
113```ts
114selectAll(':my-thing', root, {
115 adapter,
116 pseudos: {
117 'my-thing': elem => adapter.getName(elem).startsWith('x-'),
118 },
119})
120```
121
122The value is either a predicate `(elem, arg?) => boolean` or a string
123selector that the matcher will compile.