@cube-dev/ui-kit 0.0.0-canary-ca2791e → 0.0.0-canary-20121c0

package/docs/tasty/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/tasty/dsl.md

@@ -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,41 @@ 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.
 
+### `#current` is the keyword
+
+`#current` emits the `currentcolor` keyword, so it resolves against the element
+that reads it. That is what lets it follow a color an ancestor faded — a ramp
+that expresses its disabled state once, in `color`, fades everything painted from
+`#current` below it with no further declarations.
+
+The `color` style also publishes `--current-color` beside every color it sets,
+for anything that needs the inherited color *as a color* rather than as the
+keyword — hand-authored CSS, or a place the keyword will not do. Read it as
+`$current-color`. It is registered with `initial-value: currentcolor`, so where
+nothing published it, it still resolves against each element's own color:
+
+```jsx
+fill: '$current-color'; // → var(--current-color)
+```
+
+A color that already reads the color it inherits — `#current`, a `#current` fade
+— is not published into it: resolving such a value a second time at a descendant
+would fade it twice.
+
+One case needs the wider floor to be considered. A token *defined* as `#current`
+and then faded gives relative color syntax a `currentcolor` origin, which Safari
+supports only from 18:
+
+```jsx
+{ '#ink': '#current', fill: '#ink.5' }
+// --ink-color: currentcolor
+// fill: oklch(from currentcolor l c h / .5)  → Chrome, Firefox, Safari 18+
+```
+
+Put the fade in the token instead — `{ '#ink': '#current.5' }` — and it goes
+through `color-mix()`, which works from Safari 16.2 and composes like every other
+`#current` fade.
+
 ### `#current` composes instead
 
 `#current` is the one exception, and the difference is deliberate. A token *names*
@@ -182,9 +217,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/tasty/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/tasty/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/tasty/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/tasty/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/tasty/styles.md

@@ -290,7 +290,14 @@ 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, for anything that needs the
+inherited color as a color rather than as the `currentcolor` keyword. Every color
+publishes it, not just a named token, so a reader below always takes 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: resolving it a second time one level down would fade it
+twice, and the variable into itself is a self-reference. `#current` does not go
+through it; it is the keyword.
 
 ### `svgFill`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.0.0-canary-ca2791e",
+  "version": "0.0.0-canary-20121c0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -47,8 +47,8 @@
     "probe:browser": "PROBE_TIER=browser node scripts/probe.mjs",
     "test-cover": "vitest run --coverage",
     "test-watch": "vitest",
-    "prettier": "prettier --check \"src/**/*.{js,jsx,ts,tsx}\"",
-    "prettier:fix": "prettier --write \"src/**/*.{js,jsx,ts,tsx}\"",
+    "prettier": "prettier --check \"src/**/*.{js,jsx,ts,tsx}\" \"**/*.{md,mdx}\"",
+    "prettier:fix": "prettier --write \"src/**/*.{js,jsx,ts,tsx}\" \"**/*.{md,mdx}\"",
     "oxlint": "oxlint src",
     "oxlint:fix": "oxlint --fix src",
     "lint": "npm-run-all -p oxlint prettier",
@@ -93,7 +93,7 @@
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
     "@tenphi/glaze": "2.0.0",
-    "@tenphi/tasty": "^3.1.0",
+    "@tenphi/tasty": "^3.3.1",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",