also looking at this
Merge @stacksjs/ts-css into this repo as packages/toolkit
#27
128 files
+9797
-201
| @@ -0,0 +1,107 @@ | ||
| 1 | # Optimizer API | |
| 2 | ||
| 3 | Replaces `csso`. Compact a CSS string, remove duplicate declarations, | |
| 4 | shorten colors, and compute selector specificity. | |
| 5 | ||
| 6 | ```ts | |
| 7 | import { minify, minifyBlock, specificity, syntax } from '@stacksjs/ts-css' | |
| 8 | // or: | |
| 9 | import { /* … */ } from '@stacksjs/ts-css/optimize' | |
| 10 | ``` | |
| 11 | ||
| 12 | ## `minify(source, options?)` | |
| 13 | ||
| 14 | Parse, compress, and re-stringify a full stylesheet. | |
| 15 | ||
| 16 | ```ts | |
| 17 | minify(source: string, options?: MinifyOptions): { css: string, ast: CssNode } | |
| 18 | ``` | |
| 19 | ||
| 20 | ```ts | |
| 21 | minify('.a { margin: 0px 0.5em 10.000px; color: #aabbcc }').css | |
| 22 | // → ".a{margin:0 .5em 10px;color:#abc}" | |
| 23 | ``` | |
| 24 | ||
| 25 | ## `minifyBlock(source, options?)` | |
| 26 | ||
| 27 | Same, but parse `source` as a declaration list (the body of a `style="…"` | |
| 28 | attribute). | |
| 29 | ||
| 30 | ```ts | |
| 31 | minifyBlock('color: red; color: blue').css | |
| 32 | // → "color:blue" | |
| 33 | ``` | |
| 34 | ||
| 35 | ## `MinifyOptions` | |
| 36 | ||
| 37 | | Option | Default | Description | | |
| 38 | | ------------------- | ---------------- | ---------------------------------------------------------- | | |
| 39 | | `comments` | `'exclamation'` | `false` to strip all, `true` / `'exclamation'` to keep `/*!*/` comments, `'first-exclamation'` to keep just the first. | | |
| 40 | | `restructure` | `true` | (Reserved — currently a no-op; declaration-level minification only.) | | |
| 41 | | `forceMediaMerge` | `false` | (Reserved.) | | |
| 42 | | `usage` | `null` | Usage hints (`{tags, ids, classes, force}`) — accepted for API parity. | | |
| 43 | ||
| 44 | ## What gets compressed | |
| 45 | ||
| 46 | Inside any `Value`, ts-css compresses: | |
| 47 | ||
| 48 | | Input | Output | | |
| 49 | | ------------------ | ---------- | | |
| 50 | | `0.5em` | `.5em` | | |
| 51 | | `10.000px` | `10px` | | |
| 52 | | `0px` / `0em` / … | `0` | | |
| 53 | | `#aabbcc` | `#abc` | | |
| 54 | | `#aabbccdd` | `#abcd` | | |
| 55 | | `rgb(255,0,0)` | `#f00` | | |
| 56 | | `url("/x.png")` | `url(/x.png)` (when safe) | | |
| 57 | ||
| 58 | In each `Block`, duplicate declarations are folded with **last wins** | |
| 59 | semantics (respecting `!important`): | |
| 60 | ||
| 61 | ```css | |
| 62 | .a { color: red; color: blue } → .a { color: blue } | |
| 63 | .a { color: red !important; | |
| 64 | color: blue } → .a { color: red !important } | |
| 65 | ``` | |
| 66 | ||
| 67 | Comments matching `options.comments` rule are stripped. | |
| 68 | ||
| 69 | ## `specificity(node)` | |
| 70 | ||
| 71 | Compute the specificity of a `Selector` AST. | |
| 72 | ||
| 73 | ```ts | |
| 74 | import { parse, syntax } from '@stacksjs/ts-css' | |
| 75 | ||
| 76 | const sel = parse('#a.b div', { context: 'selector' }) | |
| 77 | syntax.specificity(sel) // [1, 1, 1] | |
| 78 | ``` | |
| 79 | ||
| 80 | Returns a `[a, b, c]` tuple per | |
| 81 | [selectors level 4](https://www.w3.org/TR/selectors-4/#specificity-rules): | |
| 82 | ||
| 83 | - `a` — id selectors | |
| 84 | - `b` — class / attribute / pseudo-class selectors | |
| 85 | - `c` — type / pseudo-element selectors | |
| 86 | ||
| 87 | `:is()`, `:not()`, `:has()`, `:matches()`, `:-moz-any()`, `:-webkit-any()` | |
| 88 | take the **maximum** specificity of their arguments. | |
| 89 | `:where()` always contributes `[0,0,0]`. | |
| 90 | ||
| 91 | The `syntax.specificity` re-export mirrors `csso.syntax.specificity` so | |
| 92 | existing call sites work without changes. | |
| 93 | ||
| 94 | ## Compose your own pipeline | |
| 95 | ||
| 96 | If you want finer control, all the building blocks are exported: | |
| 97 | ||
| 98 | ```ts | |
| 99 | import { compressTree, dedupeDeclarations, removeComments } from '@stacksjs/ts-css/optimize' | |
| 100 | import { generate, parse } from '@stacksjs/ts-css/parse' | |
| 101 | ||
| 102 | const ast = parse(input) | |
| 103 | removeComments(ast, { exclamation: true }) | |
| 104 | compressTree(ast) | |
| 105 | dedupeDeclarations(ast) | |
| 106 | const out = generate(ast) | |
| 107 | ``` | |