@cube-dev/ui-kit 0.154.1 → 0.155.0

package/docs/tasty/injector.md

@@ -11,7 +11,7 @@ The Style Injector is the core engine behind Tasty's styling system, providing:
 - **Hash-based deduplication** - Identical CSS gets the same className
 - **Reference counting** - Automatic cleanup when components unmount (refCount = 0)
 - **CSS nesting flattening** - Handles `&`, `.Class`, `SubElement` patterns
-- **Keyframes injection** - First-class `@keyframes` support with immediate disposal
+- **At-rule injection** - First-class `@keyframes`, `@property`, `@font-face`, `@counter-style`, and `@function` support
 - **Smart cleanup** - CSS rules batched cleanup, keyframes disposed immediately
 - **SSR support** - Deterministic class names and CSS extraction
 - **Multiple roots** - Works with Document and ShadowRoot
@@ -250,6 +250,33 @@ Dispose, ref-counted cleanup and GC therefore behave identically in every mode.
 
 ---
 
+### At-rule injection
+
+Beyond ordinary rules, the injector has a dedicated entry point per at-rule. All of them deduplicate by name and are **permanent** — there is no ref-counting or dispose, because a rule that other CSS references by name cannot be safely removed while any of it might still apply.
+
+| Function | Injects | Notes |
+|---|---|---|
+| `keyframes(steps, nameOrOptions?)` | `@keyframes` | The exception: ref-counted and disposed immediately when unused. Returns the injected name, which may differ from the requested one. |
+| `property(name, options?)` | `@property` | `name` accepts `$name`, `#name`, or `--name`. Usually unnecessary — types are inferred automatically unless `configure({ autoPropertyTypes: false })`. |
+| `fontFace(family, descriptors, options?)` | `@font-face` | Deduplicated by family **and** descriptor content, so several faces of one family coexist. |
+| `counterStyle(name, descriptors, options?)` | `@counter-style` | |
+| `func(name, definition, options?)` | `@function` | `name` accepts `$$name`, `$name`, or `--name`. Abbreviated because `function` is a reserved word. |
+
+Every one of these takes an optional `root` (a `Document` or `ShadowRoot`).
+
+`func()` also accepts `weak: true`, which registers the rule **without** overriding an existing one of the same name. `configure()` uses it for global `@function` definitions so a component-local definition always wins over the global default, regardless of which is injected first.
+
+```ts
+import { counterStyle, fontFace, func, property } from '@tenphi/tasty';
+
+property('$card-elevation', { syntax: '<number>', initialValue: '0' });
+fontFace('Inter', { src: 'url(/inter.woff2)', fontWeight: '400 700' });
+counterStyle('dashes', { system: 'cyclic', symbols: '"—"', suffix: ' ' });
+func('$$negative', { args: ['$value'], result: '(-1 * $value)' });
+```
+
+---
+
 ## Advanced Features
 
 ### Style Result Format
@@ -365,14 +392,14 @@ const shadowAnimation = keyframes({
 ### Server-Side Rendering
 
 ```typescript
-import { getCssText, getCssTextForNode } from '@tenphi/tasty';
+import { getCSSText, getCSSTextForNode } from '@tenphi/tasty';
 
 // Extract all CSS for SSR
-const cssText = getCssText();
+const cssText = getCSSText();
 
 // Extract CSS for specific DOM subtree (like jest-styled-components)
 const container = render(<MyComponent />);
-const componentCSS = getCssTextForNode(container);
+const componentCSS = getCSSTextForNode(container);
 ```
 
 ### Test Environment Detection

package/docs/tasty/methodology.md

@@ -214,7 +214,7 @@ The array form is simpler but types all values as `ModValue`:
 modProps: ['isLoading', 'isSelected'] as const,
 ```
 
-For the full API reference, see [Runtime — Mod Props](react-api.md#mod-props).
+For the full API reference, see [React API — Mod Props](react-api.md#mod-props).
 
 ---
 

package/docs/tasty/migration-v3.md

@@ -0,0 +1,285 @@
+# Migration Guide: v2 → v3
+
+Everything that changes when you upgrade from `@tenphi/tasty` 2.x to 3.0, in the order you will hit it.
+
+Most of the work is mechanical renames — see the [search-and-replace cheat sheet](#search-and-replace-cheat-sheet) at the end. The parts that need real attention are the [directional shorthand](#2-directional-shorthand) rule and the [behavior changes](#8-behavior-changes-that-are-not-renames).
+
+- [At a glance](#at-a-glance)
+- [1. Styles-object keys](#1-styles-object-keys)
+- [2. Directional shorthand](#2-directional-shorthand)
+- [3. Config keys](#3-config-keys)
+- [4. Renamed exports](#4-renamed-exports)
+- [5. Removed exports](#5-removed-exports)
+- [6. Removed props](#6-removed-props)
+- [7. Moved subpath](#7-moved-subpath)
+- [8. Behavior changes that are not renames](#8-behavior-changes-that-are-not-renames)
+- [9. New in v3](#9-new-in-v3)
+- [Search-and-replace cheat sheet](#search-and-replace-cheat-sheet)
+- [Not changed](#not-changed)
+
+---
+
+## At a glance
+
+| v2.11 | v3.0 | Find it with |
+|---|---|---|
+| `'@properties': { … }` | `'@property': { … }` | `rg "'@properties'"` |
+| `'@fontFace': { … }` | `'@font-face': { … }` | `rg "'@fontFace'"` |
+| `'@counterStyle': { … }` | `'@counter-style': { … }` | `rg "'@counterStyle'"` |
+| `padding: '2x 4x top right'` | `padding: '2x top, 4x right'` | dev-mode console warning |
+| `fade: '3x 1x top bottom'` | `fade: '3x top, 1x bottom'` | dev-mode console warning |
+| `configure({ funcs })` | `configure({ functions })` | `rg "funcs"` |
+| `configure({ fontFace })` | `configure({ fontFaces })` | `rg "fontFace:"` |
+| `configure({ counterStyle })` | `configure({ counterStyles })` | `rg "counterStyle:"` |
+| `getCssText()` | `getCSSText()` | `rg "getCssText"` |
+| `getCssTextForNode()` | `getCSSTextForNode()` | `rg "getCssTextForNode"` |
+| `getCssTextForClasses()` | `getCSSTextForClasses()` | `rg "getCssTextForClasses"` |
+| `getGlobalFontFace()` | `getGlobalFontFaces()` | `rg "getGlobalFontFace\b"` |
+| `getGlobalCounterStyle()` | `getGlobalCounterStyles()` | `rg "getGlobalCounterStyle\b"` |
+| `getGlobalFunction()` | `getGlobalFunctions()` | `rg "getGlobalFunction\b"` |
+| `okhslFunc` / `okhstFunc` | `okhslFunction` / `okhstFunction` | `rg "okhs[lt]Func\b"` |
+| `CssOptions` | `CSSOptions` | `rg "CssOptions"` |
+| `ParserOptions.funcs` | `ParserOptions.functions` | `rg "funcs:"` |
+| `StyleParser#setFuncs()` | `StyleParser#setFunctions()` | `rg "setFuncs"` |
+| `ChunkInfo` (from `tastyDebug`) | `DebugChunkInfo` | `rg "ChunkInfo"` |
+| `@tenphi/tasty/next` | `@tenphi/tasty/zero/next` | `rg "tasty/next"` |
+| `getIsTestEnvironment()` | `isTestEnvironment()` | `rg "getIsTestEnvironment"` |
+| `hydrateTastyCache()` | `hydrateTastyClasses()` | `rg "hydrateTastyCache"` |
+
+---
+
+## 1. Styles-object keys
+
+At-rule keys now match the real CSS at-rule names Tasty already emits, so they are kebab-case rather than camelCase. The generated CSS is unchanged.
+
+```diff
+  const Card = tasty({
+    styles: {
+-     '@properties': { '$elevation': { syntax: '<number>' } },
+-     '@fontFace': { Inter: { src: 'url(/inter.woff2)' } },
+-     '@counterStyle': { dashes: { system: 'cyclic', symbols: '"—"' } },
++     '@property': { '$elevation': { syntax: '<number>' } },
++     '@font-face': { Inter: { src: 'url(/inter.woff2)' } },
++     '@counter-style': { dashes: { system: 'cyclic', symbols: '"—"' } },
+    },
+  });
+```
+
+`@keyframes` and `@starting` are unchanged — they were already spec-faithful.
+
+---
+
+## 2. Directional shorthand
+
+**This is the one change that can alter rendered CSS without a rename.** A style group that names direction modifiers now takes a **single** value, applied to every direction it names.
+
+The old form looked positional but never was: the parser buckets values and modifiers into separate arrays per comma group, so `'2x 4x top right'`, `'2x top 4x right'`, and `'top 2x right 4x'` were all the same input, and the pairing was decided by the order the *modifiers* happened to appear in. `'1x 2x right top'` and `'1x 2x top right'` produced different CSS, and `'1x 2x top top'` silently assigned `top` twice.
+
+Per-side values now come from comma-separated groups:
+
+```diff
+- padding: '2x 4x top right'
++ padding: '2x top, 4x right'
+
+- margin: 'right 1x top 2x'
++ margin: '1x right, 2x top'
+
+- inset: 'left 2x right 1x'
++ inset: '2x left, 1x right'
+
+- fade: '3x 1x top bottom'
++ fade: '3x top, 1x bottom'
+```
+
+Affects `padding`, `margin`, `inset`, `scrollMargin`, and `fade`. Extra values are ignored with a **development-mode warning** naming the offending value, so run your app in dev and watch the console — that is the reliable way to find every occurrence. Production is silent and never throws.
+
+**Unchanged:** single-value directional groups (`padding: '2x top'`, `'1x left right'`), every value-only CSS shorthand form (`padding: '1x 2x'`, `'1x 2x 3x 4x'`, and `fade: '3x 1x'` — a group that names no direction is unambiguous and keeps plain shorthand order), CSS-wide keywords, and the `longhand` modifier.
+
+`inset`'s `dock` modifier keeps its two-value form with sharper semantics: the first value applies to the named edge, the second to the perpendicular sides it spans, so `inset: '2x 4x bottom dock'` still gives `auto 32px 16px 32px`. A third value with `dock`, or a second value without it, now warns.
+
+---
+
+## 3. Config keys
+
+```diff
+  configure({
+-   funcs: { double: (groups) => `calc(2 * ${groups[0].output})` },
+-   fontFace: { Inter: { src: 'url(/inter.woff2)' } },
+-   counterStyle: { dashes: { system: 'cyclic', symbols: '"—"' } },
++   functions: { double: (groups) => `calc(2 * ${groups[0].output})` },
++   fontFaces: { Inter: { src: 'url(/inter.woff2)' } },
++   counterStyles: { dashes: { system: 'cyclic', symbols: '"—"' } },
+  });
+```
+
+`functions` is a single map holding both flavors, discriminated by value type:
+
+- **bare key + function value** → a parse-time function, called as `name(...)`
+- **`$$name` key + object value** → a declarative CSS `@function`, called as `$$name(...)`
+
+A key whose prefix doesn't match its value type is ignored with a development warning.
+
+> If you are coming from a pre-release build of v3, note the intermediate `function` config key never shipped. Upgraders from 2.x only ever wrote `funcs`.
+
+---
+
+## 4. Renamed exports
+
+**Raw-CSS family** — aligned on the `CSS` initialism already used by `useRawCSS` / `injectRawCSS` / `getRawCSSText`:
+
+- `getCssText()` → `getCSSText()`
+- `getCssTextForNode()` → `getCSSTextForNode()`
+- `StyleInjector#getCssTextForClasses()` → `getCSSTextForClasses()`
+- `CssOptions` → `CSSOptions`
+
+**Config getters** — pluralized to match their already-plural config keys:
+
+- `getGlobalFontFace()` → `getGlobalFontFaces()`
+- `getGlobalCounterStyle()` → `getGlobalCounterStyles()`
+- `getGlobalFunction()` → `getGlobalFunctions()`
+
+**Color functions** — aligned with the `useFunction` / `FunctionDefinition` family:
+
+- `okhslFunc` → `okhslFunction`
+- `okhstFunc` → `okhstFunction`
+- `createColorFunc(name, channelLabel, convert)` → `createColorFunc(name, convert, label?)` — the label is now an optional trailing argument used only to format development warnings
+
+**Parser** (`@tenphi/tasty/core`):
+
+- `ParserOptions.funcs` → `ParserOptions.functions`
+- `StyleParser#setFuncs()` → `StyleParser#setFunctions()`
+
+**Debug types:** the debug-local `ChunkInfo` is now `DebugChunkInfo`, so it no longer collides with the parser's `ChunkInfo`.
+
+---
+
+## 5. Removed exports
+
+| Removed | Use instead |
+|---|---|
+| `getIsTestEnvironment()` | `isTestEnvironment()` |
+| `hydrateTastyCache()` | `hydrateTastyClasses()` |
+| `customFunc()` | `configure({ functions })` |
+| `getGlobalFuncs()` | `getGlobalFunctions()` for `@function` definitions; the parse-function registry is internal |
+| `resetGlobalFuncs()` | `resetConfig()` |
+| `setGlobalPredefinedTokens()` | `configure({ replaceTokens })` |
+| `resetGlobalPredefinedTokens()` | `resetConfig()` |
+| `setMiddlewareTransferCache()` / `getMiddlewareTransferCache()` | internal; no replacement needed |
+| `clearWriterCache()` | internal test utility |
+| `DEFAULT_PLUGINS` | nothing — it was never consumed, and passing it to `configure({ plugins })` was a no-op. The default `okhsl`/`okhst` functions are registered automatically. |
+| `registerDefaultFunctions()` | internal bootstrap helper |
+| `warn()` / `deprecationWarning()` | internal helpers with no callers |
+| `Bucket` enum | parser-internal |
+| `Props` type | inline `Record<string, any>` |
+| `UseStylesOptions` | `useStyles()` takes `Styles \| undefined` directly |
+| `GlobalStyledProps` | its only member was the already-dead `breakpoints` prop |
+| duplicate `PropertyOptions` | the single `PropertyOptions` from `injector/types` |
+
+`getGlobalFuncs()` deserves a note: it returned the **live mutable internal registry**, and writing to it bypassed the parser's cache invalidation, so the write silently never took effect. If you were mutating it, move to `configure({ functions })`.
+
+---
+
+## 6. Removed props
+
+`css`, `block`, `inline`, and `breakpoints` are gone from `BaseProps` / `TastySpecificKeys`. All four were typed but never consumed — passing them did nothing in v2 either.
+
+---
+
+## 7. Moved subpath
+
+```diff
+- import { withTasty } from '@tenphi/tasty/next';
++ import { withTasty } from '@tenphi/tasty/zero/next';
+```
+
+The zero-runtime Next.js wrapper already lived under the `zero` namespace internally; the top-level `/next` path collided confusingly with `@tenphi/tasty/ssr/next`, which is a different integration.
+
+---
+
+## 8. Behavior changes that are not renames
+
+**Repeated `configure()` calls now merge.** `recipes`, `keyframes`, `properties`, `fontFaces`, `counterStyles`, and CSS `@function` definitions used to replace wholesale, so a design-system `configure()` followed by an application `configure()` silently dropped the design system's values. All of them now merge, with the later call winning on a key conflict — matching `tokens` and `globalStyles`, which already merged. If you were relying on a second call to *clear* a collection, use `resetConfig()`.
+
+`configure({ polyfills })` is now correctly rejected after the first render, like every sibling option, and shallow-merges so an unrelated later call cannot switch a polyfill off.
+
+**The `theme` prop is now implemented.** It maps to a `data-theme` attribute on the rendered element; previously it fell through and was spread onto the DOM raw. Augment `TastyThemeNames` for autocomplete.
+
+**`tasty(Component, options)` no longer leaks factory-only options.** `variants`, `elements`, `styleProps`, `modProps`, and `tokenProps` are stripped instead of being passed to the wrapped component as runtime props, matching the element factory.
+
+**Replacing a built-in style handler now warns.** Built-in handlers are shared across style names, so `configure({ handlers: { fill } })` also takes over `image` and the whole `background-*` family, and `configure({ handlers: { display } })` takes down `flow`, `gap`, `hide`, `overflow`, `whiteSpace`, and `textOverflow`. This was always true; what's new is that a development-mode warning now names exactly what was displaced. If you see it, either declare the whole group and delegate the rest to `styleHandlers.*`, or pick a narrower name. See [Plugins](plugins.md#custom-style-handlers).
+
+**Multi-dependency custom handlers are fixed.** A handler whose dependencies mixed known and unknown style names was invoked once per chunk with only *part* of its dependencies, and could emit stale CSS. Unknown names now join their handler's chunk, so it is invoked once with all of them. No built-in style moved, so no existing class name changes.
+
+**`isChecked` added to the root prop types.** It already worked at runtime; it was just missing from `BaseProps` / `AllBaseProps`.
+
+**The `okhsl`/`okhst` "expected 3 values" warning is now development-only** and follows the `[Tasty]` prefix convention: `[Tasty] okhsl(): expected 3 values (H S L), got: …`. It previously fired in production.
+
+---
+
+## 9. New in v3
+
+Nothing here is required to upgrade.
+
+- **CSS `@function` support** — reusable, parameterized functions via the `'@function'` styles key, the `useFunction` style function, or `configure({ functions })`. Works across client, SSR/RSC, and zero-runtime. `configure({ polyfills: { functions: true } })` inlines every call into plain CSS for browsers that don't ship the at-rule yet. See [Style DSL](dsl.md#functions-function).
+- **Custom color plugins with no core special-casing** — `okhsl`/`okhst` are now ordinary one-line plugins, and a third-party color space can achieve identical integration. New `createColorFunc` and `resolveFunctionColor` helpers.
+- **`configure({ propHandlers })`** — props middleware for every component: props in, props out. The extension point for props that aren't style values.
+- **`configure({ baseStyleProps })`** — expose style properties as props on every component without listing them in each `styleProps`.
+- **`defineHandler(deps, fn)`** — infers a multi-dependency handler's parameter types from its dependency list.
+- **Plugins can supply `properties`, `keyframes`, `fontFaces`, and `counterStyles`** in addition to what they already could.
+- See [Plugins & Extension Points](plugins.md) for all of the above.
+
+---
+
+## Search-and-replace cheat sheet
+
+Run these in order — the `Css` → `CSS` renames must happen before any broader pattern, and the quoted at-rule keys must stay quote-anchored so they can't hit `configure({ properties })`.
+
+```bash
+# 1. Raw-CSS family (before anything that touches "Css")
+rg -l 'getCssTextForClasses' | xargs sed -i '' 's/getCssTextForClasses/getCSSTextForClasses/g'
+rg -l 'getCssTextForNode'    | xargs sed -i '' 's/getCssTextForNode/getCSSTextForNode/g'
+rg -l 'getCssText'           | xargs sed -i '' 's/getCssText/getCSSText/g'
+rg -l 'CssOptions'           | xargs sed -i '' 's/CssOptions/CSSOptions/g'
+
+# 2. Styles-object at-rule keys (quote-anchored)
+rg -l "'@properties'"   | xargs sed -i '' "s/'@properties'/'@property'/g"
+rg -l "'@fontFace'"     | xargs sed -i '' "s/'@fontFace'/'@font-face'/g"
+rg -l "'@counterStyle'" | xargs sed -i '' "s/'@counterStyle'/'@counter-style'/g"
+
+# 3. Config getters (word-anchored so the plural forms are not double-pluralized)
+rg -l 'getGlobalFontFace\b'     | xargs sed -i '' 's/getGlobalFontFace\b/getGlobalFontFaces/g'
+rg -l 'getGlobalCounterStyle\b' | xargs sed -i '' 's/getGlobalCounterStyle\b/getGlobalCounterStyles/g'
+rg -l 'getGlobalFunction\b'     | xargs sed -i '' 's/getGlobalFunction\b/getGlobalFunctions/g'
+
+# 4. Color functions and parser methods
+rg -l 'okhslFunc\b' | xargs sed -i '' 's/okhslFunc\b/okhslFunction/g'
+rg -l 'okhstFunc\b' | xargs sed -i '' 's/okhstFunc\b/okhstFunction/g'
+rg -l 'setFuncs'    | xargs sed -i '' 's/setFuncs/setFunctions/g'
+
+# 5. Removed exports with direct replacements
+rg -l 'getIsTestEnvironment' | xargs sed -i '' 's/getIsTestEnvironment/isTestEnvironment/g'
+rg -l 'hydrateTastyCache'    | xargs sed -i '' 's/hydrateTastyCache/hydrateTastyClasses/g'
+
+# 6. Moved subpath
+rg -l "@tenphi/tasty/next" | xargs sed -i '' "s|@tenphi/tasty/next|@tenphi/tasty/zero/next|g"
+
+# 7. Verify nothing is left (should print nothing)
+rg "getCssText|CssOptions|'@properties'|'@fontFace'|'@counterStyle'|okhs[lt]Func\b|setFuncs|getIsTestEnvironment|hydrateTastyCache|@tenphi/tasty/next|getGlobalFontFace\b|getGlobalCounterStyle\b|getGlobalFunction\b"
+```
+
+`configure({ funcs })` → `functions`, `fontFace` → `fontFaces`, and `counterStyle` → `counterStyles` are deliberately **not** scripted: those words appear in many other contexts, so change them by hand and let TypeScript find the call sites.
+
+The directional shorthand cannot be scripted at all — the whole point is that the old form's meaning was not recoverable from its text. Run your app in development and follow the console warnings.
+
+---
+
+## Not changed
+
+Worth stating explicitly, because it's easy to assume otherwise:
+
+- **At-rule styles-object keys are CSS-spec-faithful, not JS-conventional.** `@keyframes`, `@property`, `@font-face`, `@counter-style`, `@function`, `@starting` — kebab-case, matching what Tasty emits.
+- **The `func()` injector method stays abbreviated.** `function` is a reserved word.
+- `injector.fontFace()` and `injector.counterStyle()` keep their singular names — only the *config keys* and *getters* were pluralized.
+- `useFontFace` and `useCounterStyle` are unchanged.
+- `configure({ properties })` and `autoPropertyTypes` are unchanged; only the styles-object `@property` key was renamed.
+- **The deprecated style aliases are retained deliberately.** `backgroundColor`, `background`, `backgroundImage`, `flex`, `grid`, and `flexDirection` still carry `@deprecated` tags and still work. They are the guardrail that discourages their use in projects that have not enabled `@tenphi/eslint-plugin-tasty` yet — read the tags as guidance, not as a removal notice.

package/docs/tasty/pipeline.md

@@ -6,7 +6,7 @@ This document describes the style rendering pipeline that transforms style objec
 
 ## Overview
 
-The pipeline takes a `Styles` object and produces an array of `CSSRule` objects ready for injection into the DOM. Entry points include `renderStylesPipeline` (full pipeline + optional class-name prefixing) and `renderStyles` (direct selector/class mode). The per-handler flow is:
+The pipeline takes a `Styles` object and produces an array of `CSSRule` objects ready for injection into the DOM. The entry point is `renderStyles`, which has two overloads: called with a selector or class (`renderStyles(styles, '.t1')`) it returns the rules directly; called without one (`renderStyles(styles)`) it returns `{ rules }` for a caller that will allocate the class name itself. The per-handler flow is:
 
 ```
 Input: Styles Object
@@ -539,7 +539,7 @@ interface CSSRule {
 }
 ```
 
-When `renderStylesPipeline` runs **without** a class name, returned rules include `needsClassName: true` (compatibility field for the injector); that flag is not part of `CSSRule` inside `materialize.ts`.
+When `renderStyles` runs **without** a selector, returned rules include `needsClassName: true` (compatibility field for the injector); that flag is not part of `CSSRule` inside `materialize.ts`.
 
 ---
 
@@ -691,7 +691,7 @@ Each snapshot yields distinct declarations; no merge.
 
 ### Stage 7: Materialize CSS
 
-Using `renderStyles(styles, '.t1')` (single class prefix; `renderStylesPipeline` doubles the class for specificity when a class name is supplied):
+Using `renderStyles(styles, '.t1')` (the class is doubled — `.t1.t1` — so Tasty owns specificity without `!important`):
 
 ```css
 .t1[data-hovered] {