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/optimize.mdadded+107-0
Changes to packages/toolkit/docs/api/optimize.md
@@ -0,0 +1,107 @@
1# Optimizer API
2
3Replaces `csso`. Compact a CSS string, remove duplicate declarations,
4shorten colors, and compute selector specificity.
5
6```ts
7import { minify, minifyBlock, specificity, syntax } from '@stacksjs/ts-css'
8// or:
9import { /* … */ } from '@stacksjs/ts-css/optimize'
10```
11
12## `minify(source, options?)`
13
14Parse, compress, and re-stringify a full stylesheet.
15
16```ts
17minify(source: string, options?: MinifyOptions): { css: string, ast: CssNode }
18```
19
20```ts
21minify('.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
27Same, but parse `source` as a declaration list (the body of a `style="…"`
28attribute).
29
30```ts
31minifyBlock('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
46Inside 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
58In each `Block`, duplicate declarations are folded with **last wins**
59semantics (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
67Comments matching `options.comments` rule are stripped.
68
69## `specificity(node)`
70
71Compute the specificity of a `Selector` AST.
72
73```ts
74import { parse, syntax } from '@stacksjs/ts-css'
75
76const sel = parse('#a.b div', { context: 'selector' })
77syntax.specificity(sel) // [1, 1, 1]
78```
79
80Returns 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()`
88take the **maximum** specificity of their arguments.
89`:where()` always contributes `[0,0,0]`.
90
91The `syntax.specificity` re-export mirrors `csso.syntax.specificity` so
92existing call sites work without changes.
93
94## Compose your own pipeline
95
96If you want finer control, all the building blocks are exported:
97
98```ts
99import { compressTree, dedupeDeclarations, removeComments } from '@stacksjs/ts-css/optimize'
100import { generate, parse } from '@stacksjs/ts-css/parse'
101
102const ast = parse(input)
103removeComments(ast, { exclamation: true })
104compressTree(ast)
105dedupeDeclarations(ast)
106const out = generate(ast)
107```