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/intro.mdadded+99-0
Changes to packages/toolkit/docs/intro.md
@@ -0,0 +1,99 @@
1# Getting started
2
3`@stacksjs/ts-css` is a pure-TypeScript CSS toolkit — a parser, walker,
4generator, selector engine, and minifier — all in one **zero-dependency**
5package. It's a drop-in replacement for the four-library quartet most CSS
6pipelines pull in:
7
8| Replaces | Provides |
9| ------------- | ----------------------------------------------------- |
10| `css-tree` | Tokenizer, parser, walker, generator, clone, `List` |
11| `css-what` | Selector parser & stringifier |
12| `css-select` | `selectAll` / `selectOne` / `is` against any tree |
13| `csso` | Minifier + `syntax.specificity` |
14
15If you've worked with any of those four libraries before, the migration
16is one block of `import` lines (see the [migration guide](./migration.md)).
17
18## Install
19
20```bash
21bun add @stacksjs/ts-css
22# or
23npm i @stacksjs/ts-css
24```
25
26## Your first parse
27
28```ts
29import { generate, parse, walk } from '@stacksjs/ts-css'
30
31const ast = parse('.foo { color: red }')
32
33walk(ast, (node) => {
34 if (node.type === 'Declaration')
35 console.log(node.property)
36})
37// → "color"
38
39console.log(generate(ast))
40// → ".foo{color:red}"
41```
42
43That's the full pipeline: parse → walk/transform → generate.
44
45## Exploring the AST
46
47Pass a `context` to parse a fragment instead of a full stylesheet:
48
49```ts
50parse('color: red', { context: 'declaration' })
51parse('color: red; font-size: 12px', { context: 'declarationList' })
52parse('.a > .b', { context: 'selector' })
53parse('@media (min-width: 800px)', { context: 'atrulePrelude' })
54```
55
56The full set of contexts is in the [parser API reference](./api/parse.md).
57
58## Selecting nodes
59
60`ts-css` ships a tree-agnostic selector engine. Provide an `Adapter` for
61your tree and you can run any CSS selector against it:
62
63```ts
64import { selectAll } from '@stacksjs/ts-css'
65
66const matches = selectAll('p > span.foo:not(.disabled)', root, {
67 adapter: myAdapter,
68 xmlMode: true,
69})
70```
71
72[Full selector matcher API →](./api/select.md)
73
74## Minifying
75
76```ts
77import { minify } from '@stacksjs/ts-css'
78
79minify('.a { margin: 0px; color: #aabbcc }').css
80// → ".a{margin:0;color:#abc}"
81```
82
83[Full minifier API →](./api/optimize.md)
84
85## CLI
86
87```bash
88ts-css minify input.css > output.css
89ts-css parse input.css | jq
90ts-css format input.css
91```
92
93## Where to next
94
95- [**Parser** API](./api/parse.md) — `parse`, `walk`, `generate`, `clone`, `List`
96- [**Selector parser** API](./api/what.md) — `parse`, `stringify`, `isTraversal`
97- [**Selector matcher** API](./api/select.md) — `selectAll`, `selectOne`, `is`
98- [**Optimizer** API](./api/optimize.md) — `minify`, `minifyBlock`, `specificity`
99- [**Migration** guide](./migration.md) — moving off the four-library setup