also looking at this
Merge @stacksjs/ts-css into this repo as packages/toolkit
#27
128 files
+9797
-201
| @@ -0,0 +1,99 @@ | ||
| 1 | # Getting started | |
| 2 | ||
| 3 | `@stacksjs/ts-css` is a pure-TypeScript CSS toolkit — a parser, walker, | |
| 4 | generator, selector engine, and minifier — all in one **zero-dependency** | |
| 5 | package. It's a drop-in replacement for the four-library quartet most CSS | |
| 6 | pipelines 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 | ||
| 15 | If you've worked with any of those four libraries before, the migration | |
| 16 | is one block of `import` lines (see the [migration guide](./migration.md)). | |
| 17 | ||
| 18 | ## Install | |
| 19 | ||
| 20 | ```bash | |
| 21 | bun add @stacksjs/ts-css | |
| 22 | # or | |
| 23 | npm i @stacksjs/ts-css | |
| 24 | ``` | |
| 25 | ||
| 26 | ## Your first parse | |
| 27 | ||
| 28 | ```ts | |
| 29 | import { generate, parse, walk } from '@stacksjs/ts-css' | |
| 30 | ||
| 31 | const ast = parse('.foo { color: red }') | |
| 32 | ||
| 33 | walk(ast, (node) => { | |
| 34 | if (node.type === 'Declaration') | |
| 35 | console.log(node.property) | |
| 36 | }) | |
| 37 | // → "color" | |
| 38 | ||
| 39 | console.log(generate(ast)) | |
| 40 | // → ".foo{color:red}" | |
| 41 | ``` | |
| 42 | ||
| 43 | That's the full pipeline: parse → walk/transform → generate. | |
| 44 | ||
| 45 | ## Exploring the AST | |
| 46 | ||
| 47 | Pass a `context` to parse a fragment instead of a full stylesheet: | |
| 48 | ||
| 49 | ```ts | |
| 50 | parse('color: red', { context: 'declaration' }) | |
| 51 | parse('color: red; font-size: 12px', { context: 'declarationList' }) | |
| 52 | parse('.a > .b', { context: 'selector' }) | |
| 53 | parse('@media (min-width: 800px)', { context: 'atrulePrelude' }) | |
| 54 | ``` | |
| 55 | ||
| 56 | The 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 | |
| 61 | your tree and you can run any CSS selector against it: | |
| 62 | ||
| 63 | ```ts | |
| 64 | import { selectAll } from '@stacksjs/ts-css' | |
| 65 | ||
| 66 | const 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 | |
| 77 | import { minify } from '@stacksjs/ts-css' | |
| 78 | ||
| 79 | minify('.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 | |
| 88 | ts-css minify input.css > output.css | |
| 89 | ts-css parse input.css | jq | |
| 90 | ts-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 | |