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/migration.mdadded+125-0
Changes to packages/toolkit/docs/migration.md
@@ -0,0 +1,125 @@
1# Migration guide
2
3Migrating from `css-tree` / `css-select` / `css-what` / `csso` to
4`@stacksjs/ts-css` is one block of `import` lines.
5
6## The diff
7
8```diff
9- import * as csstree from 'css-tree'
10- import * as csswhat from 'css-what'
11- import { is, selectAll, selectOne } from 'css-select'
12- import * as csso from 'csso'
13
14+ import {
15+ csstree, // namespace mirror of css-tree
16+ cssWhat as csswhat, // namespace mirror of css-what
17+ csso, // namespace mirror of csso
18+ is, selectAll, selectOne, // top-level css-select APIs
19+ } from '@stacksjs/ts-css'
20```
21
22That's it. Every method real consumers use is preserved.
23
24## Per-library compatibility
25
26### `css-tree`
27
28| Surface | Compat |
29| -------------------------------------------- | ------ |
30| `parse(source, opts)` — all `context` modes | ✅ |
31| `walk(ast, cb)` & `walk(ast, { visit, enter, leave })` | ✅ |
32| `walk.skip` / `walk.stop` | ✅ |
33| `this.atrule` / `this.rule` context inside callbacks | ✅ |
34| `generate(node)` | ✅ |
35| `clone(node)` | ✅ |
36| `List` class — `forEach(data, item, list)`, `insert`, `remove`, `replace`, `prepend`, `append`, `prependList`, `appendList`, `insertList`, `createItem`, `first`, `last`, `isEmpty` | ✅ |
37| Lexer (`syntax.lexer.match*`, `syntax.match*`) | ❌ — see below |
38
39### `css-what`
40
41| Surface | Compat |
42| -------------------- | ------ |
43| `parse(selector)` | ✅ |
44| `stringify(ast)` | ✅ |
45| `isTraversal(token)` | ✅ |
46| Selector segment shape (incl. `ignoreCase: 'quirks'`) | ✅ |
47
48### `css-select`
49
50| Surface | Compat |
51| ------------------------------------------- | ------ |
52| `selectAll(sel, root, opts)` | ✅ |
53| `selectOne(sel, root, opts)` | ✅ |
54| `is(node, sel, opts)` | ✅ |
55| `compile(sel, opts)` | ✅ |
56| `Adapter` interface | ✅ — same shape, including state hooks (`isActive`, etc.) |
57| `pseudos` extension | ✅ |
58| `:has`, `:is`, `:not`, `:where`, `:matches` | ✅ |
59| `:nth-child`, `:nth-last-child`, `:nth-of-type`, `:nth-last-of-type`, `:first-child`, `:last-child`, `:only-child`, `:first-of-type`, `:last-of-type`, `:only-of-type` | ✅ |
60| `:empty`, `:root`, `:scope` | ✅ |
61| Stateful pseudos via adapter hooks | ✅ |
62
63### `csso`
64
65| Surface | Compat |
66| -------------------------------------------- | ------ |
67| `minify(source, opts)` | ✅ |
68| `minifyBlock(source, opts)` | ✅ |
69| `syntax.specificity(node)` | ✅ |
70| Restructuring across rules / selectors | ❌ — declaration-level only |
71
72## What's intentionally not ported
73
74We dropped two large chunks of the original libs that real consumers
75rarely need:
76
77### `css-tree`'s lexer (`syntax.lexer`)
78
79`css-tree` ships ~3000 lines of CSS spec data that lets you ask "is the
80string `red 1px solid` a valid `<border>` shorthand?". This is great for
81linters and editors, but downstream consumers like CSSO, SVGO, and most
82formatters never touch it.
83
84The AST that ts-css produces is **rich enough** for you to add lexer
85behaviour back on top — every node carries its source slice and a typed
86discriminated union, so a value-type checker is a straightforward
87external library.
88
89### CSSO's restructuring pass
90
91`csso` does heroic work to merge declarations across rules:
92
93```css
94.a { color: red; padding: 4px }
95.b { color: red }
96.c { padding: 4px }
97```
98
99→ rewritten to share declarations between rules. Beyond gzip's reach
100this saves **single-digit percent**, costs ~1000 lines, and breaks subtly
101in edge cases (specificity, source-order dependencies, vendor-prefix
102collisions). ts-css does declaration-level minification (numbers,
103colors, dedup-within-rule) which catches the bulk of the bytes.
104
105If you have a use case where restructuring matters, file an issue —
106adding it back is straightforward, but we'd rather not ship dead code.
107
108## Real-world swap: `ts-svg`
109
110[`ts-svg`](https://github.com/stacksjs/ts-svg)'s SVGO port uses ts-css.
111The migration was 7 files and looked like:
112
113```diff
114- import * as csstree from 'css-tree'
115- import * as csswhat from 'css-what'
116- import { is, selectAll, selectOne } from 'css-select'
117- import { syntax } from 'csso'
118- import * as csso from 'csso'
119
120+ import { csstree, cssWhat as csswhat, csso, is, selectAll, selectOne } from '@stacksjs/ts-css'
121+ const { syntax } = csso
122```
123
124The full SVGO test suite (82 tests) passes after the swap with no
125behaviour changes, and removes 4 transitive dep trees from `node_modules`.