@tenphi/tasty 3.1.0 → 3.3.0

package/docs/configuration.md

@@ -71,32 +71,212 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 | `globalStyles` | `Record<string, Styles>` | - | Global Tasty styles keyed by CSS selector |
 | `plugins` | `TastyPlugin[]` | - | Plugins that bundle any of the above (processed in order; later override earlier, and direct config wins over all). See [Plugins](plugins.md) |
 | `gc` | `GCConfig` | - | Garbage-collection tuning for unused styles (`{ touchInterval, capacity }`) |
-| `colorSpace` | `'rgb' \| 'hsl' \| 'oklch'` | `'oklch'` | Color space for decomposed color token companion variables |
+| `batchInjection` | `boolean \| 'always'` | `false` | Defer stylesheet writes and apply them in one batch. See [Batched injection](#batched-injection) |
+| `colorSpace` | `'rgb' \| 'hsl' \| 'oklch'` | - | **Deprecated** — no longer has any effect. See [Color space](#color-space) |
 | `namePrefix` | `string` | `'t'` (runtime) / `'ts'` (zero-runtime) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. See [Name prefix](#name-prefix). |
 
 ---
 
+## Batched Injection
+
+Every `insertRule()` on a live stylesheet invalidates style for that sheet's
+scope. Components inject during React's render phase, and if anything else reads
+layout in the same pass, the two interleave:
+
+```
+inject -> read (forced style recalc) -> inject -> read (forced recalc) -> ...
+```
+
+A UI kit that measures during render — popovers, autosizing inputs, virtualized
+lists — can turn one mount into a dozen full-tree recalculations. `batchInjection`
+queues the writes instead and applies them together, so the tree is invalidated
+once per flush.
+
+```tsx
+import { configure, TastyBatchProvider } from '@tenphi/tasty';
+
+configure({ batchInjection: true });
+
+createRoot(el).render(
+  <TastyBatchProvider>
+    <App />
+  </TastyBatchProvider>,
+);
+```
+
+### Why the provider is required
+
+Deferring a write past React's layout phase would let a `useLayoutEffect`
+measure an element whose rules are not in the sheet yet and read its *unstyled*
+box — a wrong number, not a stale one, so it never self-corrects.
+
+`TastyBatchProvider` closes that hole. It opens a *batch window* during its
+render and closes it — flushing — in `useInsertionEffect`, which React runs in
+the mutation phase, before any layout effect:
+
+```
+provider renders          -> window OPEN
+  children render         -> injections queued
+provider insertionEffect  -> FLUSH, window CLOSED
+layout effects run        -> rules are in the sheet
+```
+
+With `batchInjection: true` a write is only ever queued inside such a window, so
+turning the flag on can make injection cheaper but can never make a measurement
+wrong. Injections outside a window are written straight through, exactly as with
+batching off:
+
+- a deep update that did not re-render the provider
+- an injection from a layout effect, an event handler or an async callback
+- SSR and RSC, where there is no live sheet at all
+
+Mount the provider as high in the tree as you can: batching applies to the
+commits it takes part in.
+
+### Modes
+
+| Value | Behaviour |
+|-------|-----------|
+| `false` (default) | One `insertRule()` per component, synchronously. |
+| `true` | Batch inside a provider window only. Cannot affect measurement. Without the provider nothing is batched, and dev mode says so once. |
+| `'always'` | Batch every injection, flushing on a microtask when no window is open. Covers more commits; a `useLayoutEffect` measuring a freshly mounted element can read its unstyled box. Paint is unaffected — microtasks always drain before the browser paints. |
+
+### Ordering
+
+All writes share one FIFO queue — component rules, global rules, raw CSS,
+`@property`, `@keyframes`, `@font-face`, `@counter-style` and `@function`.
+Draining it in insertion order keeps the sheet byte-identical to unbatched
+output, which matters because equal-specificity rules resolve by document order.
+
+### SSR, RSC and zero-runtime
+
+**Server render — nothing to batch, safe to leave enabled.** SSR and RSC collect
+CSS as text through `ServerStyleCollector`; the runtime injector never runs
+there, so `batchInjection` changes nothing either way. `<TastyBatchProvider>`
+renders its children and does nothing else: the window it opens is a no-op
+without a `document`, and the `useInsertionEffect` that would close it never
+fires on the server. Configure the flag once in shared code — no environment
+branching needed.
+
+**Hydration — the better your SSR coverage, the less there is to batch.**
+`hydrateTastyClasses()` (wired up for you by `@tenphi/tasty/ssr/next` and the
+Astro integration) pre-populates the injector from `window.__TASTY__`, so
+hydrating a server-rendered class is a cache hit that produces no sheet write at
+all. Batching pays off on what SSR could not cover: client-only routes, styles
+that first appear after hydration (a `styles` prop that changes on interaction, a
+modal or popover mounting), and dynamic tokens.
+
+**Astro islands — one provider per island, or `'always'`.** Every island is its
+own React root, so a provider inside one island does not open a window for
+another. With `batchInjection: true`, wrap each island root that renders enough
+tasty components to be worth it. `'always'` needs no provider and covers every
+island, at the cost of the measurement hazard above. Either way, an island that
+only re-hydrates server-rendered classes has nothing to batch.
+
+**Zero-runtime (`tastyStatic`) — unaffected.** Build-time extraction never
+touches the injector: the babel plugin emits either a CSS file import or an
+`injectCSS()` call from `@tenphi/tasty/static/inject`, which appends text to a
+single `<style data-tasty-static>` element. `batchInjection` only defers CSSOM
+writes made by the runtime injector, so extracted styles are unchanged. In an app
+that mixes both, it still applies to the runtime half.
+
+### `flushStyles()`
+
+Applies every pending write immediately. Every injector read API calls it for
+you — `getCSSText`, `getCSSTextForClasses`, `getCSSTextForNode`,
+`getRawCSSText`, `isPropertyDefined`, `getMetrics`, `cleanup`, `gc` and
+`destroy` — so a read never observes a partial sheet.
+Call it directly before measuring in code that runs outside a batch window under
+`'always'`:
+
+```tsx
+import { flushStyles } from '@tenphi/tasty';
+
+useLayoutEffect(() => {
+  flushStyles();
+  const { width } = ref.current.getBoundingClientRect();
+}, []);
+```
+
+`hasPendingStyleWrites()` reports whether anything is queued, and
+`resetStyleBatch()` drops the queue without applying it (tests only).
+
+---
+
 ## Color Space
 
-Controls the CSS color space used for decomposed color token companion variables. When you define `#name` color tokens, tasty generates both `--name-color` (the color) and `--name-color-{suffix}` (its channels, decomposed).
+> **Deprecated.** `configure({ colorSpace })` no longer has any effect and will
+> be removed in the next major. Setting it warns in development.
+
+A `#name` token's value used to be rewritten into a configured color space, so
+`#brand: '#ff8800'` declared `--brand-color: oklch(0.75 0.16 55)`. That existed
+to serve the opacity suffix, which needed numeric channels to write an alpha
+into. Opacity now uses CSS relative color syntax —
+`oklch(from var(--brand-color) l c h / .5)` — which has the browser read the
+channels, so there is nothing left for the setting to decide.
+
+A color is emitted exactly as authored:
 
 ```jsx
-configure({
-  colorSpace: 'oklch', // default
-});
+configure({ tokens: { '#brand': '#ff8800' } });
+// → --brand-color: #ff8800
 ```
 
-| Color Space | Suffix | Components Format | Channel Reference |
-|---|---|---|---|
-| `rgb` | `-rgb` | `255 128 0` | `rgb(var(--name-color-rgb))` |
-| `hsl` | `-hsl` | `300 100% 25%` | `hsl(var(--name-color-hsl))` |
-| `oklch` | `-oklch` | `0.42 0.16 328` | `oklch(var(--name-color-oklch))` |
+That holds for every form: a hex literal, a native color function, a bare CSS
+color name, a `color-mix()`, a `light-dark()`, a fallback chain. A `#token`
+reference still resolves to its `var()` chain, and a plugin color function such
+as `okhsl()` is still resolved by the parser to the color it denotes.
+
+To address a token's channels, use relative color syntax against the token:
+
+```css
+background: oklch(from var(--brand-color) calc(l * 1.2) c h);
+```
 
-The `oklch` color space is the default because it provides perceptually uniform color manipulation — reaching for a channel to shift lightness or hue produces more natural-looking results.
+This works on any `<color>`, including the ones no build-time conversion could
+have evaluated — and it is what the [opacity suffix](dsl.md#color-tokens--opacity)
+itself uses. Its space is always `oklch`, which is unbounded, so a wide-gamut
+color survives a round trip a narrower space would clamp.
 
-The companion is there so you can *address the channels*: shift a lightness, animate a hue, build a derived color. It is not how the [opacity suffix](dsl.md#color-tokens--opacity) works — that sets the alpha on `--name-color` itself with relative color syntax, so it needs nothing from the companion and works on any color.
+### Migrating off `colorSpace`
+
+Drop the option. If you relied on the uniform output format, nothing in Tasty
+needs it — author your tokens in the space you want them emitted in, since the
+value now passes through untouched:
+
+```jsx
+// before: any input, normalized to the configured space on the way out
+configure({ colorSpace: 'oklch', tokens: { '#brand': '#ff8800' } });
+
+// after: author it in the space you want
+configure({ tokens: { '#brand': 'oklch(0.75 0.16 55)' } });
+```
+
+### Migrating off the channel companions
+
+A `#name` token used to declare a second variable beside `--name-color` holding
+its channels decomposed, suffixed with the configured space —
+`--brand-color-oklch: 0.75 0.16 55` — and a `color` style emitted
+`--current-color-{space}` beside `--current-color`. Both are gone, for the same
+reason: they existed so an opacity suffix had channels to write an alpha into.
+
+These were never part of the public API, but they were visible in the emitted
+CSS, so hand-authored CSS may reference one. Address the token itself instead:
+
+```css
+/* before */
+color: oklch(var(--brand-color-oklch) / 0.5);
+background: oklch(var(--brand-color-oklch));
+
+/* after */
+color: oklch(from var(--brand-color) l c h / 0.5);
+background: var(--brand-color);
+```
 
-A color the engine cannot evaluate at build time — a `color-mix()`, a `light-dark()`, a `color()` in a space it has no conversion for — has no channels to decompose, so its companion is expressed *by reference* using CSS relative color syntax (`--name-color-oklch: from color-mix(…) l c h`). Reading a channel off it still works; the browser resolves them.
+The replacement is strictly more capable — the companion could only be
+decomposed for a color the engine could evaluate at build time, while relative
+color syntax works on every `<color>`, including a `color-mix()`, a
+`light-dark()`, and a variable Tasty never defined.
 
 ---
 
@@ -167,7 +347,7 @@ configure({
 ```
 
 - `$name` keys become `--name` CSS custom properties
-- `#name` keys become `--name-color` and `--name-color-{colorSpace}` properties (suffix depends on `colorSpace`, default `oklch`)
+- `#name` keys become `--name-color` custom properties
 - Names keep their case, since CSS custom properties are case-sensitive: `$myVar` is `--myVar` and is referenced as `$myVar`. A leading capital is not supported and folds — `$Foo` and `#Purple` become `--foo` and `--purple-color` — so start names lowercase. Kebab-case (`$my-var`) remains the convention.
 
 Tokens are automatically emitted in all rendering modes: runtime (client), SSR, and zero-runtime (Babel plugin).
@@ -289,7 +469,7 @@ See [Functions (`@function`)](dsl.md#functions-function) for inline usage inside
 
 ### Custom color functions
 
-A parse function whose output is an already-supported color (`rgb`, `hsl`, `#…`, `oklch`, …) is treated as a **color function**: it works everywhere a color is accepted — style values, `#token.alpha` opacity injection, token decomposition into the configured color space, and `parseColor` — with no extra registration. This is the same mechanism the built-in `okhsl`/`okhst` plugins use; they are ordinary plugins registered by default.
+A parse function whose output is an already-supported color (`rgb`, `hsl`, `#…`, `oklch`, …) is treated as a **color function**: it works everywhere a color is accepted — style values, `#token.alpha` opacity injection, and `parseColor` — with no extra registration. This is the same mechanism the built-in `okhsl`/`okhst` plugins use; they are ordinary plugins registered by default.
 
 ```ts
 import { configure, createColorFunc } from '@tenphi/tasty';

package/docs/dsl.md

@@ -134,7 +134,7 @@ color: '#purple',           // Full opacity
 color: '#purple.5',         // 50% opacity
 color: '#purple.05',        // 5% opacity
 color: '#purple.$fade',     // Opacity from a custom property
-fill: '#current',           // → currentcolor
+fill: '#current',           // → var(--current-color)
 color: '(#primary, #secondary)',  // Fallback syntax
 ```
 
@@ -151,9 +151,9 @@ these:
 
 - a token holding a `color-mix()`, a `light-dark()`, or a `color()` in a space
   Tasty cannot convert — none of which have channels to decompose
-- `#current`, which resolves to `currentcolor`
+- `#current`, which resolves to the color the element inherits
 - a `--name-color` variable declared in your own CSS, with no Tasty token
-  definition and no companion variable behind it
+  definition behind it
 
 Two properties follow from writing the alpha slot rather than compositing:
 
@@ -163,6 +163,28 @@ Two properties follow from writing the alpha slot rather than compositing:
   `/ var(--fade)` unchanged, so it works whether `$fade` holds `.5` or `50%` —
   which is what `--*-opacity` properties are registered to accept.
 
+### Why `#current` is a variable
+
+`#current` emits `var(--current-color)`, not the `currentcolor` keyword. The
+`color` style publishes `--current-color` alongside every color it sets, and the
+property is registered with `initial-value: currentcolor` — so where nothing has
+published it, the variable resolves against each element's own inherited color
+and is indistinguishable from the keyword.
+
+The difference shows when a token is *defined* as `#current` and then faded:
+
+```jsx
+{ '#ink': '#current', fill: '#ink.5' }
+// --ink-color: var(--current-color)  → a concrete color where one was published
+// fill: oklch(from var(--ink-color) l c h / .5)
+```
+
+Relative color syntax accepts a concrete origin from Safari 16.4, while
+`oklch(from currentcolor …)` needs Safari 18. Resolving through the variable is
+what keeps that token fadeable on the wider floor. Where no `color` style
+published the variable, the origin is the keyword again and the Safari 18 floor
+applies to that case alone.
+
 ### `#current` composes instead
 
 `#current` is the one exception, and the difference is deliberate. A token *names*
@@ -182,9 +204,9 @@ step. Because a `color-mix()` percentage cannot be a `<number>`, an opacity
 custom property used as `#current.$fade` must hold a unitless number; a token
 accepts either form.
 
-The space is always `oklch`, whatever [`colorSpace`](configuration.md#color-space)
-is set to: it is unbounded, so a wide-gamut color survives a round trip that a
-gamut-limited space would clamp.
+The space is always `oklch`: it is unbounded, so a wide-gamut color survives a
+round trip that a gamut-limited space would clamp. Nothing configures this —
+see [Color space](configuration.md#color-space).
 
 ---
 

package/docs/injector.md

@@ -300,6 +300,17 @@ const styleRule: StyleResult = {
 };
 ```
 
+### Batched Injection
+
+`configure({ batchInjection: true })` queues every sheet write — component
+rules, global rules, raw CSS and at-rules — into one FIFO and applies them
+together, so the document is style-invalidated once per flush instead of once per
+component. `<TastyBatchProvider>` flushes in `useInsertionEffect`, before any
+layout effect, so a queued write can never be observed by a measurement. See
+[Batched injection](configuration.md#batched-injection) for the modes and the
+ordering guarantee. `flushStyles()` applies pending writes on demand; every read
+API here calls it for you.
+
 ### Deduplication & Performance
 
 ```typescript

package/docs/methodology.md

@@ -275,7 +275,7 @@ const ProgressBar = tasty({
 
 // Conversion:
 //   'progress'    → $progress    → --progress
-//   'accentColor' → #accent      → --accent-color + --accent-color-oklch
+//   'accentColor' → #accent      → --accent-color
 ```
 
 #### Object form

package/docs/pipeline.md

@@ -683,7 +683,7 @@ The default entry's exclusive is `!hovered & !@media(dark)` — no top-level OR,
 
 ### Stages 4–5: Compute combinations and call handler
 
-Single style, three snapshots; the `color` handler emits `color` plus `--current-color*` variables.
+Single style, three snapshots; the `color` handler emits `color` plus a `--current-color` variable.
 
 ### Stage 6: Merge by value
 
@@ -697,20 +697,17 @@ Using `renderStyles(styles, '.t1')` (the class is doubled — `.t1.t1` — so Ta
 .t1[data-hovered] {
   color: var(--highlight-color);
   --current-color: var(--highlight-color);
-  --current-color-oklch: var(--highlight-color-oklch);
 }
 @media (prefers-color-scheme: dark) {
   .t1:not([data-hovered]) {
     color: var(--dark-color);
     --current-color: var(--dark-color);
-    --current-color-oklch: var(--dark-color-oklch);
   }
 }
 @media (not (prefers-color-scheme: dark)) {
   .t1:not([data-hovered]) {
     color: var(--white-color);
     --current-color: var(--white-color);
-    --current-color-oklch: var(--white-color-oklch);
   }
 }
 ```

package/docs/react-api.md

@@ -224,7 +224,7 @@ const ProgressBar = tasty({
 
 <ProgressBar progress="75%" accentColor="#purple" />
 // 'progress'    → $progress    → --progress
-// 'accentColor' → #accent      → --accent-color + --accent-color-oklch
+// 'accentColor' → #accent      → --accent-color
 ```
 
 ### Object form

package/docs/styles.md

@@ -290,7 +290,12 @@ Text color with design token support.
 | `"light-dark(#dark, #light)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
 | `true` | `currentColor` |
 
-When set to a named color token, also sets `$current-color` and `$current-color-{colorSpace}` custom properties for downstream use (suffix depends on the configured `colorSpace`, default `oklch`). An opacity suffix does not move the companion: `color="#purple.5"` still reports `#purple`'s channels, since components carry no alpha.
+Also sets `$current-color` to the same color, which is what `#current` resolves
+through. Every color publishes it, not just a named token, so a descendant's
+`#current` always reads the nearest `color` rather than the nearest *token*
+color. A value that already reads the inherited color — `#current` itself, a
+`#current` fade, a bare `currentColor` — is not republished: that would be a
+self-reference, or would resolve a second time one level down.
 
 ### `svgFill`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -178,19 +178,19 @@
       "name": "main (import *)",
       "path": "dist/index.js",
       "import": "*",
-      "limit": "58 kB"
+      "limit": "56.6 kB"
     },
     {
       "name": "core (import *)",
       "path": "dist/core/index.js",
       "import": "*",
-      "limit": "55 kB"
+      "limit": "53.65 kB"
     },
     {
       "name": "static",
       "path": "dist/static/index.js",
       "import": "*",
-      "limit": "19.25 kB"
+      "limit": "16.8 kB"
     },
     {
       "name": "zero",
@@ -201,7 +201,7 @@
         "path",
         "crypto"
       ],
-      "limit": "33.75 kB"
+      "limit": "31.25 kB"
     },
     {
       "name": "babel-plugin",
@@ -212,7 +212,7 @@
         "path",
         "crypto"
       ],
-      "limit": "51.25 kB"
+      "limit": "49.35 kB"
     }
   ],
   "scripts": {
@@ -235,6 +235,7 @@
     "version": "changeset version",
     "release": "changeset publish",
     "knip": "knip",
+    "check:test-only": "node scripts/check-test-only-code.mjs",
     "hygiene": "pnpm lint && pnpm format:check && pnpm typecheck",
     "hygiene:fix": "pnpm lint:fix && pnpm format && pnpm typecheck"
   }