also looking at this
Merge @stacksjs/ts-css into this repo as packages/toolkit
#27
128 files
+9797
-201
| @@ -0,0 +1,123 @@ | ||
| 1 | # Selector matcher API | |
| 2 | ||
| 3 | Replaces `css-select`. Run any CSS selector against any tree-like data | |
| 4 | structure via an `Adapter`. | |
| 5 | ||
| 6 | ```ts | |
| 7 | import { compile, is, selectAll, selectOne } from '@stacksjs/ts-css' | |
| 8 | // or: | |
| 9 | import { /* … */ } from '@stacksjs/ts-css/select' | |
| 10 | ``` | |
| 11 | ||
| 12 | ## `selectAll(selector, root, options)` | |
| 13 | ||
| 14 | Return every element under `root` that matches `selector`. | |
| 15 | ||
| 16 | ```ts | |
| 17 | selectAll<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 | ||
| 26 | Return the first match (in document order), or `null`. | |
| 27 | ||
| 28 | ```ts | |
| 29 | selectOne(...): ElementNode | null | |
| 30 | ``` | |
| 31 | ||
| 32 | ## `is(node, selector, options)` | |
| 33 | ||
| 34 | Test whether `node` itself matches `selector`. | |
| 35 | ||
| 36 | ```ts | |
| 37 | is(node, selector, options): boolean | |
| 38 | ``` | |
| 39 | ||
| 40 | ## `compile(selector, options)` | |
| 41 | ||
| 42 | Compile a selector once and reuse the predicate against many trees. | |
| 43 | ||
| 44 | ```ts | |
| 45 | const test = compile('p > span.foo', options) | |
| 46 | adapter.findAll(test, [root]) | |
| 47 | ``` | |
| 48 | ||
| 49 | ## `Adapter<Node, ElementNode>` | |
| 50 | ||
| 51 | The adapter is the tree-access contract. Every method has the same | |
| 52 | signature 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 | ||
| 69 | Optional 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 | ||
| 79 | If your tree has no notion of focus/hover, leave these undefined — the | |
| 80 | matcher 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 | ||
| 111 | Add your own via `options.pseudos`: | |
| 112 | ||
| 113 | ```ts | |
| 114 | selectAll(':my-thing', root, { | |
| 115 | adapter, | |
| 116 | pseudos: { | |
| 117 | 'my-thing': elem => adapter.getName(elem).startsWith('x-'), | |
| 118 | }, | |
| 119 | }) | |
| 120 | ``` | |
| 121 | ||
| 122 | The value is either a predicate `(elem, arg?) => boolean` or a string | |
| 123 | selector that the matcher will compile. | |