also looking at this
Merge @stacksjs/ts-css into this repo as packages/toolkit
#27
128 files
+9797
-201
| @@ -0,0 +1,104 @@ | ||
| 1 | # Selector parser API | |
| 2 | ||
| 3 | Replaces `css-what`. Pure-string-to-selector-AST parsing — separate from | |
| 4 | the matcher, so you can analyse selectors (specificity, rewrites, lint | |
| 5 | rules) without running them. | |
| 6 | ||
| 7 | ```ts | |
| 8 | import { isTraversal, parseSelector, stringifySelector } from '@stacksjs/ts-css' | |
| 9 | // or: | |
| 10 | import { parse, stringify, isTraversal } from '@stacksjs/ts-css/what' | |
| 11 | ``` | |
| 12 | ||
| 13 | ## `parse(selector, options?)` | |
| 14 | ||
| 15 | Parse a CSS selector string into a list-of-lists of selector segments. | |
| 16 | ||
| 17 | ```ts | |
| 18 | parse(selector: string, options?: ParseOptions): Selector[][] | |
| 19 | ``` | |
| 20 | ||
| 21 | The outer array is **comma-separated selectors**; the inner arrays are | |
| 22 | **simple selectors and combinators** in source order. | |
| 23 | ||
| 24 | ```ts | |
| 25 | import { parse } from '@stacksjs/ts-css/what' | |
| 26 | ||
| 27 | parse('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 | ||
| 44 | Inverse of `parse` — turn a selector AST back into a string. | |
| 45 | ||
| 46 | ```ts | |
| 47 | stringify(ast: Selector[][]): string | |
| 48 | ``` | |
| 49 | ||
| 50 | ```ts | |
| 51 | import { parse, stringify } from '@stacksjs/ts-css/what' | |
| 52 | ||
| 53 | const ast = parse('div > p:not(.x)') | |
| 54 | stringify(ast) // 'div > p:not(.x)' | |
| 55 | ``` | |
| 56 | ||
| 57 | ## `isTraversal(token)` | |
| 58 | ||
| 59 | Returns `true` if `token` is a combinator (descendant / child / sibling / | |
| 60 | adjacent / parent / column-combinator) and not a simple selector. | |
| 61 | ||
| 62 | ```ts | |
| 63 | isTraversal(token: Selector): boolean | |
| 64 | ``` | |
| 65 | ||
| 66 | ## Segment types | |
| 67 | ||
| 68 | The `Selector` union contains: | |
| 69 | ||
| 70 | ```ts | |
| 71 | type 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 | ||
| 101 | For 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 | |
| 104 | a string (e.g. `:nth-child(2n+1)`), `data` is the raw inner string. | |