@stacksjs/ts-css 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,173 @@
+### 🐛 Bug Fixes
+
+- add setup-bun to publish-commit job ([ba0a364](https://github.com/stacksjs/ts-css/commit/ba0a364)) _(by glennmichael123 <gtorregosa@gmail.com>)_
+
+### 🧹 Chores
+
+- add --bun flag to changelog scripts ([fd558f1](https://github.com/stacksjs/ts-css/commit/fd558f1)) _(by glennmichael123 <gtorregosa@gmail.com>)_
+- normalize CI action versions to match other repos ([f2cfd71](https://github.com/stacksjs/ts-css/commit/f2cfd71)) _(by glennmichael123 <gtorregosa@gmail.com>)_
+- fix lint and typecheck errors ([9b61350](https://github.com/stacksjs/ts-css/commit/9b61350)) _(by glennmichael123 <gtorregosa@gmail.com>)_
+- wip ([7e8a9b5](https://github.com/stacksjs/ts-css/commit/7e8a9b5)) _(by Chris <chrisbreuer93@gmail.com>)_
+- wip ([5624fd4](https://github.com/stacksjs/ts-css/commit/5624fd4)) _(by Chris <chrisbreuer93@gmail.com>)_
+- wip ([e793c83](https://github.com/stacksjs/ts-css/commit/e793c83)) _(by Chris <chrisbreuer93@gmail.com>)_
+- wip ([57b551c](https://github.com/stacksjs/ts-css/commit/57b551c)) _(by Chris <chrisbreuer93@gmail.com>)_
+- wip ([10a6e56](https://github.com/stacksjs/ts-css/commit/10a6e56)) _(by Chris <chrisbreuer93@gmail.com>)_
+- wip ([19a0620](https://github.com/stacksjs/ts-css/commit/19a0620)) _(by Chris <chrisbreuer93@gmail.com>)_
+- wip ([8649287](https://github.com/stacksjs/ts-css/commit/8649287)) _(by Chris <chrisbreuer93@gmail.com>)_
+- initial commit ([ee6a5e0](https://github.com/stacksjs/ts-css/commit/ee6a5e0)) _(by Chris <chrisbreuer93@gmail.com>)_
+
+### Contributors
+
+- _Chris <chrisbreuer93@gmail.com>_
+- _glennmichael123 <gtorregosa@gmail.com>_
+
+## v0.3.1...main
+
+[compare changes](https://github.com/stacksjs/ts-starter/compare/v0.3.1...main)
+
+### 🚀 Enhancements
+
+- Add `bun-plugin-dts-auto` ([c0c487b](https://github.com/stacksjs/ts-starter/commit/c0c487b))
+
+### ❤️ Contributors
+
+- Chris <chrisbreuer93@gmail.com>
+
+## v0.3.0...main
+
+[compare changes](https://github.com/stacksjs/ts-starter/compare/v0.3.0...main)
+
+### 🏡 Chore
+
+- Fix isolatedDeclarations setting ([b87b6b1](https://github.com/stacksjs/ts-starter/commit/b87b6b1))
+- Adjust urls ([0a40b72](https://github.com/stacksjs/ts-starter/commit/0a40b72))
+
+### ❤️ Contributors
+
+- Chris <chrisbreuer93@gmail.com>
+
+## v0.2.1...main
+
+[compare changes](https://github.com/stacksjs/ts-starter/compare/v0.2.1...main)
+
+### 🚀 Enhancements
+
+- Add `noFallthroughCasesInSwitch` ([b9cfa30](https://github.com/stacksjs/ts-starter/commit/b9cfa30))
+- Add `verbatimModuleSyntax` ([c495d17](https://github.com/stacksjs/ts-starter/commit/c495d17))
+- Several updates ([f703179](https://github.com/stacksjs/ts-starter/commit/f703179))
+
+### 🩹 Fixes
+
+- Properly use bun types ([7144221](https://github.com/stacksjs/ts-starter/commit/7144221))
+
+### 🏡 Chore
+
+- Adjust badge links ([432aff7](https://github.com/stacksjs/ts-starter/commit/432aff7))
+- Add `runs-on` options ([9a5b97f](https://github.com/stacksjs/ts-starter/commit/9a5b97f))
+- Cache node_modules ([ba2f6ce](https://github.com/stacksjs/ts-starter/commit/ba2f6ce))
+- Use `ubuntu-latest` for now ([1add684](https://github.com/stacksjs/ts-starter/commit/1add684))
+- Minor updates ([1007cff](https://github.com/stacksjs/ts-starter/commit/1007cff))
+- Lint ([d531bdc](https://github.com/stacksjs/ts-starter/commit/d531bdc))
+- Remove bunx usage ([e1a5575](https://github.com/stacksjs/ts-starter/commit/e1a5575))
+- Pass bun flag ([960976f](https://github.com/stacksjs/ts-starter/commit/960976f))
+- Use defaults ([157455b](https://github.com/stacksjs/ts-starter/commit/157455b))
+- Run typecheck using bun flag ([f22f3b1](https://github.com/stacksjs/ts-starter/commit/f22f3b1))
+- Test ([0b3c3a1](https://github.com/stacksjs/ts-starter/commit/0b3c3a1))
+- Use modern js for commitlint ([4bd6978](https://github.com/stacksjs/ts-starter/commit/4bd6978))
+- Update worklows readme ([f54aae9](https://github.com/stacksjs/ts-starter/commit/f54aae9))
+- Adjust readme ([92d7ff1](https://github.com/stacksjs/ts-starter/commit/92d7ff1))
+- More updates ([0225587](https://github.com/stacksjs/ts-starter/commit/0225587))
+- Add .zed settings for biome ([1688024](https://github.com/stacksjs/ts-starter/commit/1688024))
+- Extend via alias ([b108d30](https://github.com/stacksjs/ts-starter/commit/b108d30))
+- Lint ([d961b2a](https://github.com/stacksjs/ts-starter/commit/d961b2a))
+- Minor updates ([e66d44a](https://github.com/stacksjs/ts-starter/commit/e66d44a))
+
+### ❤️ Contributors
+
+- Chris <chrisbreuer93@gmail.com>
+
+## v0.2.0...main
+
+[compare changes](https://github.com/stacksjs/ts-starter/compare/v0.2.0...main)
+
+### 🏡 Chore
+
+- Remove unused action ([066f85a](https://github.com/stacksjs/ts-starter/commit/066f85a))
+- Housekeeping ([fc4e24d](https://github.com/stacksjs/ts-starter/commit/fc4e24d))
+
+### ❤️ Contributors
+
+- Chris <chrisbreuer93@gmail.com>
+
+## v0.1.1...main
+
+[compare changes](https://github.com/stacksjs/ts-starter/compare/v0.1.1...main)
+
+### 🏡 Chore
+
+- Adjust eslint config name ([53c2aa6](https://github.com/stacksjs/ts-starter/commit/53c2aa6))
+- Set type module ([22dde14](https://github.com/stacksjs/ts-starter/commit/22dde14))
+
+### ❤️ Contributors
+
+- Chris <chrisbreuer93@gmail.com>
+
+## v0.1.0...main
+
+[compare changes](https://github.com/stacksjs/ts-starter/compare/v0.1.0...main)
+
+### 🏡 Chore
+
+- Use correct cover image ([75bd3ae](https://github.com/stacksjs/ts-starter/commit/75bd3ae))
+
+### ❤️ Contributors
+
+- Chris <chrisbreuer93@gmail.com>
+
+## v0.0.5...main
+
+[compare changes](https://github.com/stacksjs/ts-starter/compare/v0.0.5...main)
+
+### 🚀 Enhancements
+
+- Add pkgx deps ([319c066](https://github.com/stacksjs/ts-starter/commit/319c066))
+- Use flat eslint config ([cdb0093](https://github.com/stacksjs/ts-starter/commit/cdb0093))
+
+### 🏡 Chore
+
+- Fix badge ([bc3b000](https://github.com/stacksjs/ts-starter/commit/bc3b000))
+- Minor updates ([78dc522](https://github.com/stacksjs/ts-starter/commit/78dc522))
+- Housekeeping ([e1cba3b](https://github.com/stacksjs/ts-starter/commit/e1cba3b))
+- Additional housekeeping ([f5dc625](https://github.com/stacksjs/ts-starter/commit/f5dc625))
+- Add `.gitattributes` ([7080f8c](https://github.com/stacksjs/ts-starter/commit/7080f8c))
+- Adjust deps ([cc71b42](https://github.com/stacksjs/ts-starter/commit/cc71b42))
+- Adjust wording ([3bc54b3](https://github.com/stacksjs/ts-starter/commit/3bc54b3))
+- Adjust readme cover ([e6acbb2](https://github.com/stacksjs/ts-starter/commit/e6acbb2))
+
+### ❤️ Contributors
+
+- Chris <chrisbreuer93@gmail.com>
+
+## v0.0.5...main
+
+[compare changes](https://github.com/stacksjs/ts-starter/compare/v0.0.5...main)
+
+### 🚀 Enhancements
+
+- Add pkgx deps ([319c066](https://github.com/stacksjs/ts-starter/commit/319c066))
+- Use flat eslint config ([cdb0093](https://github.com/stacksjs/ts-starter/commit/cdb0093))
+
+### 🏡 Chore
+
+- Fix badge ([bc3b000](https://github.com/stacksjs/ts-starter/commit/bc3b000))
+- Minor updates ([78dc522](https://github.com/stacksjs/ts-starter/commit/78dc522))
+- Housekeeping ([e1cba3b](https://github.com/stacksjs/ts-starter/commit/e1cba3b))
+- Additional housekeeping ([f5dc625](https://github.com/stacksjs/ts-starter/commit/f5dc625))
+- Add `.gitattributes` ([7080f8c](https://github.com/stacksjs/ts-starter/commit/7080f8c))
+- Adjust deps ([cc71b42](https://github.com/stacksjs/ts-starter/commit/cc71b42))
+- Adjust wording ([3bc54b3](https://github.com/stacksjs/ts-starter/commit/3bc54b3))
+- Adjust readme cover ([e6acbb2](https://github.com/stacksjs/ts-starter/commit/e6acbb2))
+
+### ❤️ Contributors
+
+- Chris <chrisbreuer93@gmail.com>

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# @stacksjs/ts-css
+
+> Pure-TypeScript CSS toolkit for Bun & Node. Zero runtime dependencies.
+
+`ts-css` is a CSS toolkit for build tools, linters, design-system pipelines,
+SSR templating, runtime style transforms — anything that needs to read,
+walk, query, transform, or minify CSS in a JS/TS environment. Written from
+scratch in TypeScript with strict types and the CSS Syntax Module Level 3
+tokenizer.
+
+It bundles every common CSS pipeline primitive — tokenizer, AST parser,
+visitor walker, generator, selector parser, selector matcher, and minifier —
+into a single zero-dep package. The shape of each sub-API mirrors the
+de-facto community standard for that capability (`css-tree`-style AST and
+walker, `css-what`-style selector tokens, the `css-select` adapter contract,
+`csso`-style minify result), so adopting `ts-css` rarely requires call-site
+changes — but the project stands on its own and isn't pitched as "the
+replacement for X."
+
+## Highlights
+
+- **Zero runtime deps.** Only ts-css's own code. Ships ~4.5k lines of TS.
+- **One install for the whole CSS pipeline.** Tokenizer, parser, walker,
+  generator, selector parser/matcher, and minifier — all behind sub-module
+  imports at `@stacksjs/ts-css/parse`, `/what`, `/select`, `/optimize`.
+- **Familiar API shapes.** Visitor/walker callbacks, AST node types, and
+  the `css-select` adapter contract follow the conventions established by
+  the popular community libraries, so most existing call sites work
+  unchanged.
+- **Bun-first.** Built and tested on Bun, works on Node ≥18.
+- **Strict TypeScript.** Strict mode, isolatedDeclarations, verbatimModuleSyntax.
+
+## Install
+
+```bash
+bun add @stacksjs/ts-css
+# or
+npm i @stacksjs/ts-css
+```
+
+## Quick start
+
+### Parse, walk, generate
+
+```ts
+import { generate, parse, walk } from '@stacksjs/ts-css'
+
+const ast = parse(`
+  .foo, .bar > .baz {
+    color: red;
+    background: url("/x.png") no-repeat;
+  }
+`)
+
+walk(ast, {
+  visit: 'Declaration',
+  enter(decl) {
+    console.log(decl.property, '→', generate(decl.value))
+  },
+})
+// color → red
+// background → url("/x.png") no-repeat
+
+console.log(generate(ast))
+// .foo,.bar>.baz{color:red;background:url("/x.png") no-repeat}
+```
+
+### Match selectors against any tree
+
+```ts
+import { selectAll } from '@stacksjs/ts-css'
+
+const adapter = {
+  isTag: (n) => n?.type === 'el',
+  getName: (e) => e.name,
+  getAttributeValue: (e, n) => e.attrs[n],
+  // …other adapter methods (see docs/api/select.md)
+}
+
+selectAll('p > span.foo:not(.disabled)', root, { adapter, xmlMode: true })
+```
+
+The matcher is decoupled from any DOM implementation: pass an `Adapter`
+describing your tree (HTML, XML, an SVG AST, your design-system component
+graph, anything with `parent`/`children`/`name`/`attrs`-like access) and
+ts-css will match standard CSS selectors against it.
+
+### Minify CSS
+
+```ts
+import { minify } from '@stacksjs/ts-css'
+
+minify(`
+  .a {
+    margin: 0px 0.5em 10.000px;
+    color: #aabbcc;
+    color: blue; /* later wins */
+  }
+`).css
+// → ".a{margin:0 .5em 10px;color:blue}"
+```
+
+### Compute selector specificity
+
+```ts
+import { parse, syntax } from '@stacksjs/ts-css'
+
+const sel = parse('#a.b div', { context: 'selector' })
+syntax.specificity(sel) // [1, 1, 1]
+```
+
+## API surface
+
+`ts-css` exposes a complete CSS pipeline. The named exports below cover the
+endpoints most build/lint/transform tools reach for:
+
+| Capability                       | Export                       |
+| -------------------------------- | ---------------------------- |
+| Parse a stylesheet to an AST (`stylesheet`/`rule`/`declaration`/`selectorList`/etc. contexts) | `parse(source, opts?)` |
+| Walk the AST with `enter`/`leave` callbacks, `visit` filtering, and a `walk.skip` sentinel | `walk(ast, fn \| visitor)` |
+| Stringify any AST node back to CSS source | `generate(node)` |
+| Deep-clone an AST subtree | `clone(node)` |
+| Doubly-linked children container with cursor-safe `forEach(data, item, list)` mid-walk mutation | `List` / `ListItem` |
+| Tokenize a selector string into segments | `cssWhat.parse(selector)` |
+| Detect combinator/traversal segments | `cssWhat.isTraversal(seg)` |
+| Match a selector against an arbitrary tree via the `Adapter` contract | `selectAll`, `selectOne`, `is`, `compile` |
+| Minify with declaration/value compression and whitespace collapse | `minify`, `minifyBlock` |
+| Compute selector specificity tuple | `syntax.specificity(node)` |
+
+A namespace export (`csstree`, `cssWhat`, `cssSelect`, `csso`) is also
+available so existing code that imports from those packages can typically
+switch by just changing the import path.
+
+## CLI
+
+```bash
+ts-css minify input.css > output.css
+ts-css parse  input.css                # AST as JSON on stdout
+ts-css format input.css                # round-trip through parser/generator
+```
+
+## What's not (yet) in scope
+
+This is a pragmatic toolkit — full surface area where it's load-bearing,
+trimmed where edge cases would force in spec data or rarely-used passes:
+
+- ❌ **No CSS-spec-aware value lexer.** Validating that `red` is a valid
+  `<color>`, or that `1px` is the right syntax for a given property, is
+  thousands of lines of spec grammar that most pipelines don't need. The
+  AST preserves enough information to layer that on top if you do.
+- ❌ **No cross-rule restructuring pass.** Reordering rules across the
+  whole stylesheet to fold compatible declarations is complex and gives
+  marginal gains beyond gzip. Declaration-level minification (numbers,
+  colors, dedup, longhand collapse) ships fully.
+
+Everything else round-trips byte-equivalent.
+
+## Project layout
+
+```
+src/
+  parse/     # tokenizer, parser, AST types, walker, generator, clone, List
+  what/      # selector parser/stringifier
+  select/    # selectAll/selectOne/is engine + pseudo-class compilers
+  optimize/  # minifier, value compressors, specificity
+```
+
+Each sub-module is exported as a separate entry point so you can import
+just what you need:
+
+```ts
+import { parse, walk } from '@stacksjs/ts-css/parse'
+import { selectAll } from '@stacksjs/ts-css/select'
+import { minify } from '@stacksjs/ts-css/optimize'
+```
+
+## Performance
+
+End-to-end (parse → minify → generate) on a 6 KB representative fixture
+(Apple M3 Pro, Bun 1.3):
+
+| Pipeline                    | Time/iter |
+| --------------------------- | --------- |
+| `ts-css.minify(source)`     | **~270 µs** |
+| `csso.minify(source)`       | ~890 µs    |
+
+→ **~3.3× faster end-to-end** with zero runtime deps. Per-API breakdown
+in [`docs/benchmarks.md`](./docs/benchmarks.md). Run them yourself with
+`bun run bench`.
+
+## Documentation
+
+Full docs: see [`./docs`](./docs) or run `bun run dev:docs` to start the
+local docs site.
+
+- [Getting started](./docs/intro.md)
+- [Parser API](./docs/api/parse.md)
+- [Selector parser API](./docs/api/what.md)
+- [Selector matcher API](./docs/api/select.md)
+- [Optimizer API](./docs/api/optimize.md)
+- [Migration guide](./docs/migration.md)
+- [Benchmarks](./docs/benchmarks.md)
+
+## License
+
+MIT — see [`LICENSE.md`](./LICENSE.md).
+
+`ts-css` is an independent implementation. The visitor / linked-list shape
+in `src/parse`, the selector tokenizer model in `src/what`, the adapter
+pattern in `src/select`, and the minification plan in `src/optimize` all
+follow conventions established by the long-standing community libraries in
+each area, so call sites that already use those conventions tend to drop in
+without changes. All such projects are MIT-licensed.

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { CSSConfig } from './types';
+export declare function getConfig(): Promise<CSSConfig>;
+export declare const defaultConfig: CSSConfig;
+export declare const config: CSSConfig;

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export type { CssNode, CssNodeType, ListItem, ParseOptions } from './parse';
+export type { Adapter, CompiledQuery, Options } from './select';
+export type { Selector, SelectorType } from './what';
+export type { MinifyOptions, MinifyResult, Specificity } from './optimize';
+/**
+ * @stacksjs/ts-css — pure-TypeScript CSS toolkit.
+ *
+ * Top-level surface re-exports the four sub-modules:
+ *   - parse    — CSS parser/walker/generator   (replaces css-tree)
+ *   - what     — selector parser               (replaces css-what)
+ *   - select   — selector matching             (replaces css-select)
+ *   - optimize — CSS minifier + specificity    (replaces csso)
+ */
+export * from './config';
+// Sub-module namespaces — `import * as csstree from '@stacksjs/ts-css'` etc.
+export * as csstree from './parse';
+export * as cssWhat from './what';
+export * as cssSelect from './select';
+export * as csso from './optimize';
+// Top-level convenience re-exports
+export { clone, generate, List, parse, walk } from './parse';
+export { is, selectAll, selectOne } from './select';
+export { isTraversal, parse as parseSelector, stringify as stringifySelector } from './what';
+export { minify, minifyBlock, specificity, syntax } from './optimize';
+export * from './types';