@cube-dev/ui-kit 0.154.1 → 0.156.0

package/docs/tasty/react-api.md

@@ -1,6 +1,6 @@
 # React API
 
-The React-specific `tasty()` component factory, component props, and style functions. All Tasty style functions — `tasty()` components, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, and `useCounterStyle()` — are hook-free and compatible with React Server Components. No `'use client'` directive needed. For the shared style language (state maps, tokens, units, extending semantics), see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
+The React-specific `tasty()` component factory, component props, and style functions. All Tasty style functions — `tasty()` components, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — are hook-free and compatible with React Server Components. No `'use client'` directive needed. For the shared style language (state maps, tokens, units, extending semantics), see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
 
 > **Note:** This file was previously named `runtime.md`. All functionality documented here works in both server and client contexts — "runtime" referred to style computation during React rendering, not to client-side JavaScript.
 
@@ -98,6 +98,26 @@ Style props accept state maps, so responsive values work through the same API:
 
 For predefined style prop lists (`FLOW_STYLES`, `POSITION_STYLES`, `DIMENSION_STYLES`, etc.) and guidance on which props to expose per component category, see [Methodology — styleProps as the public API](methodology.md#styleprops-as-the-public-api).
 
+### Always-available style props
+
+A small set of style properties — `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, and `transition` — are always harvested as style props on every `tasty()` component, even when `styleProps` is omitted. This means you can pass `<Card display="grid" />` or `<Text preset="h1" />` without declaring them. When you do declare `styleProps`, these base props are unioned with your list (not replaced).
+
+---
+
+## `Element`
+
+`Element` is the unstyled base component exported from the main entry — equivalent to `tasty({})` (a `div` with no default styles). It accepts all Tasty props (`styles`, `styleProps`, `mods`, `tokens`, `as`, `qa`, `theme`, the `is*` props, etc.) and is useful as a generic styled box or as a building block for layout primitives.
+
+```jsx
+import { Element } from '@tenphi/tasty';
+
+<Element as="section" padding="4x" fill="#surface">
+  Content
+</Element>
+```
+
+> Note: `Element` shadows the global DOM `Element` type when imported from `@tenphi/tasty`. In files that need the DOM type, alias the import: `import { Element as TastyElement } from '@tenphi/tasty'`.
+
 ---
 
 ## Mod Props
@@ -579,6 +599,46 @@ function useCounterStyle(
 ): string;
 ```
 
+### useFunction
+
+Register a CSS `@function` (custom function). Permanent — no cleanup on unmount. Deduplicates by function name. The function name accepts `$$name` (matching the call site `$$name(...)`), `$name`, or `--name`.
+
+```tsx
+import { tasty, useFunction } from '@tenphi/tasty';
+
+const Box = tasty({ styles: { marginTop: '$$negative(10px)' } });
+
+function Layout() {
+  useFunction('$$negative', { args: ['$value'], result: '(-1 * $value)' });
+  return <Box />;
+}
+```
+
+Call the function through the Tasty DSL rather than a raw `style` prop. An inline `style` value reaches the browser unparsed, so the `$$name(...)` sugar is never expanded — and under `configure({ polyfills: { functions: true } })` it silently does nothing, because the polyfill rewrites calls at parse time.
+
+Inside a `tasty()` component you call functions with the same `$$name(...)` sugar:
+
+```tsx
+const Box = tasty({
+  styles: {
+    '@function': { '$$negative': { args: ['$value'], result: '(-1 * $value)' } },
+    marginTop: '$$negative(10px)',
+  },
+});
+```
+
+Signature:
+
+```ts
+function useFunction(
+  name: string,
+  definition: FunctionDefinition,
+  options?: { root?: Document | ShadowRoot },
+): void;
+```
+
+See the [Functions section of the DSL reference](dsl.md#functions-function) for the full descriptor shape, token conventions, and value-sugar support. `@function` is an experimental CSS feature — unsupported browsers safely ignore the native rule, or enable the [`polyfills.functions`](configuration.md#polyfills) inline polyfill for full cross-browser support.
+
 ### Troubleshooting
 
 - Styles are not updating: make sure `configure()` runs before first render, and verify the generated class name or global rule with [Debug Utilities](debug.md).

package/docs/tasty/ssr.md

@@ -18,18 +18,18 @@ The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies
 
 ## How It Works
 
-`tasty()` components are hook-free and use `computeStyles()` internally — a synchronous, framework-agnostic function. On the server, `computeStyles()` discovers a `ServerStyleCollector` via a registered getter (module-level for Next.js, `globalThis` for Astro/generic frameworks using `AsyncLocalStorage`) and collects CSS into it instead of trying to access the DOM. On the client, CSS is injected synchronously into the DOM during render; the injector's content-based cache makes this idempotent. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `computeStyles()` skips the rendering pipeline entirely during hydration.
+`tasty()` components are hook-free and use `computeStyles()` internally — a synchronous, framework-agnostic function. On the server, `computeStyles()` discovers a `ServerStyleCollector` via a registered getter (module-level for Next.js, `globalThis` for Astro/generic frameworks using `AsyncLocalStorage`) and collects CSS into it instead of trying to access the DOM. On the client, CSS is injected synchronously into the DOM during render; the injector's content-based cache makes this idempotent. The collector accumulates all styles and serializes them as `<style>` tags plus a class-list script in the HTML. On the client, `hydrateTastyClasses()` pre-populates the injector's rules map with the rendered class names so that `computeStyles()` skips the rendering pipeline entirely during hydration.
 
 ```
 Server                         Client
 ──────                         ──────
-tasty() renders                hydrateTastyCache() pre-populates cache
-  └─ computeStyles()              └─ cacheKey → className map ready
+tasty() renders                hydrateTastyClasses() reads window.__TASTY__
+  └─ computeStyles()              └─ marks rendered class names as already-in-DOM
        └─ collector.collect()
                                  tasty() renders
 After render:                    └─ computeStyles()
-  <style data-tasty-ssr>              └─ cache hit → skip pipeline
-  <script data-tasty-cache>           └─ no CSS re-injection
+  <style data-tasty-ssr>             └─ class name known → skip pipeline
+  <script> (pushes to __TASTY__)     └─ no CSS re-injection
 ```
 
 ---
@@ -85,8 +85,8 @@ That's it. All `tasty()` components inside the tree automatically get SSR suppor
 - `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load. The `'use client'` boundary is required solely to access `useServerInsertedHTML` — **not** because `tasty()` components need the client.
 - During SSR, `TastyRegistry` creates a `ServerStyleCollector` and registers it via a module-level getter (not `globalThis` — this avoids leaking between Next.js's separate RSC and SSR module graphs). It also wraps children in a React context provider so that hooks inside the SSR tree can discover the collector. All style functions — `tasty()` components, `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, and `useCounterStyle()` — discover the collector through the module-level getter or context provider.
 - `TastyRegistry` uses `useServerInsertedHTML` to flush collected CSS into the HTML stream as `<style data-tasty-ssr>` tags. This is fully streaming-compatible — styles are injected alongside each Suspense boundary as it resolves.
-- A companion inline `<script>` tag merges the `cacheKey → className` mapping into `window.__TASTY_SSR_CACHE__` for each flush. This streaming-friendly approach accumulates cache entries incrementally as Suspense boundaries resolve.
-- When the `@tenphi/tasty/ssr/next` module loads on the client, `hydrateTastyCache()` runs automatically from `window.__TASTY_SSR_CACHE__` and pre-populates the injector cache. During hydration, `computeStyles()` hits the cache and skips the entire pipeline.
+- A companion inline `<script>` tag pushes the rendered class names into `window.__TASTY__` for each flush. This streaming-friendly approach accumulates the class list incrementally as Suspense boundaries resolve.
+- When the `@tenphi/tasty/ssr/next` module loads on the client, `hydrateTastyClasses()` runs automatically from `window.__TASTY__` and pre-populates the injector's rules map. During hydration, `computeStyles()` sees the class name is already registered and skips the entire pipeline.
 
 ### Using Tasty in Server Components
 
@@ -188,7 +188,7 @@ This gives you:
 
 - A `ServerStyleCollector` per request via `AsyncLocalStorage`, deduplicating CSS across all React trees on the page
 - A single consolidated `<style data-tasty-ssr>` injected into `</head>`
-- A `<script data-tasty-cache>` tag with the `cacheKey -> className` map for client hydration
+- A `<script>` tag pushing the rendered class names into `window.__TASTY__` for client hydration
 - Auto-injected client hydration script (via `injectScript('before-hydration')`) so islands skip the style pipeline during hydration -- no need to import anything manually in each island component
 
 All style functions (`useGlobalStyles`, `useRawCSS`, `useKeyframes`, `useProperty`, `useFontFace`, `useCounterStyle`) work on the server.
@@ -223,7 +223,7 @@ export default defineConfig({
 });
 ```
 
-This gives the same middleware deduplication and hook support, but ships zero client-side JavaScript. No `<script data-tasty-cache>` is emitted.
+This gives the same middleware deduplication and hook support, but ships zero client-side JavaScript. No class-list `<script>` is emitted.
 
 ### Manual middleware (advanced)
 
@@ -258,7 +258,7 @@ export const onRequest = tastyMiddleware({ transferCache: false });
 Astro's `@astrojs/react` renderer calls `renderToString()` for each React component without wrapping the tree in a provider. The middleware creates a `ServerStyleCollector` and binds it via `AsyncLocalStorage`. All `computeStyles()` calls within the request discover this collector automatically.
 
 - **Static components** (no `client:*`): Styles are collected during `renderToString` and injected into `</head>` as a single `<style>` tag. No JavaScript is shipped.
-- **Islands** (`client:load`, `client:visible`, etc.): Styles are collected during SSR the same way. On the client, the hydration script (auto-injected by `tastyIntegration()` or manually via `@tenphi/tasty/ssr/astro-client`) reads the cache state from `<script data-tasty-cache>` and pre-populates the injector. The island's `computeStyles()` calls hit the cache during hydration.
+- **Islands** (`client:load`, `client:visible`, etc.): Styles are collected during SSR the same way. On the client, the hydration script (auto-injected by `tastyIntegration()` or manually via `@tenphi/tasty/ssr/astro-client`) reads the class list from `window.__TASTY__` and pre-populates the injector's rules map. The island's `computeStyles()` calls see the class names as already registered and skip the pipeline during hydration.
 - The middleware reads the full response body, then injects the collected CSS into `</head>` before sending the final HTML.
 
 ### CSP nonce
@@ -274,31 +274,30 @@ Any React-based framework can integrate using `runWithCollector`, which binds a
 ```tsx
 import {
   ServerStyleCollector,
+  createServerStyleCollector,
   runWithCollector,
-  hydrateTastyCache,
+  hydrateTastyClasses,
 } from '@tenphi/tasty/ssr';
 import { renderToString } from 'react-dom/server';
 import { hydrateRoot } from 'react-dom/client';
 
 // ── Server ──────────────────────────────────────────────
 
-const collector = new ServerStyleCollector();
+const collector = createServerStyleCollector();
 
 const html = await runWithCollector(collector, () =>
   renderToString(<App />)
 );
 
 const css = collector.getCSS();
-const cacheState = collector.getCacheState();
+const classNames = collector.getRenderedClassNames();
 
 // Embed in your HTML template:
 const fullHtml = `
   <html>
     <head>
       <style data-tasty-ssr>${css}</style>
-      <script data-tasty-cache type="application/json">
-        ${JSON.stringify(cacheState)}
-      </script>
+      <script>(window.__TASTY__=window.__TASTY__||[]).push(${JSON.stringify(classNames)})</script>
     </head>
     <body>
       <div id="root">${html}</div>
@@ -309,7 +308,7 @@ const fullHtml = `
 // ── Client ──────────────────────────────────────────────
 
 // Before hydration:
-hydrateTastyCache(); // reads from <script data-tasty-cache>
+hydrateTastyClasses(); // reads from window.__TASTY__
 
 hydrateRoot(document.getElementById('root'), <App />);
 ```
@@ -319,7 +318,7 @@ hydrateRoot(document.getElementById('root'), <App />);
 For streaming with `renderToPipeableStream`, use `flushCSS()` instead of `getCSS()`:
 
 ```tsx
-const collector = new ServerStyleCollector();
+const collector = createServerStyleCollector();
 
 const stream = await runWithCollector(collector, () =>
   renderToPipeableStream(<App />, {
@@ -330,12 +329,14 @@ const stream = await runWithCollector(collector, () =>
       stream.pipe(res);
     },
     onAllReady() {
-      // Flush any remaining styles + cache state
+      // Flush any remaining styles + class list
       const css = collector.flushCSS();
       if (css) res.write(`<style data-tasty-ssr>${css}</style>`);
 
-      const state = collector.getCacheState();
-      res.write(`<script data-tasty-cache type="application/json">${JSON.stringify(state)}</script>`);
+      const classNames = collector.getRenderedClassNames();
+      res.write(
+        `<script>(window.__TASTY__=window.__TASTY__||[]).push(${JSON.stringify(classNames)})</script>`,
+      );
     },
   })
 );
@@ -349,16 +350,17 @@ const stream = await runWithCollector(collector, () =>
 
 | Import path | Description |
 |---|---|
-| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `runWithCollector`, `hydrateTastyCache` |
+| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `hydrateTastyClasses` |
 | `@tenphi/tasty/ssr/next` | Next.js App Router: `TastyRegistry` component |
 | `@tenphi/tasty/ssr/astro` | Astro: `tastyIntegration`, `tastyMiddleware` |
 | `@tenphi/tasty/ssr/astro-client` | Astro: client-side cache hydration (auto-injected by integration, or import manually) |
+| `@tenphi/tasty/ssr/astro-middleware`<br>`@tenphi/tasty/ssr/astro-middleware-static` | Astro: the middleware entrypoints `tastyIntegration()` registers via `addMiddleware()`. Exported so Astro can resolve them by specifier; you should not import them. For manual setups use `tastyMiddleware()`. |
 
 ### `ServerStyleCollector`
 
 Server-safe style collector. One instance per request.
 
-Constructor: `new ServerStyleCollector(namePrefix?)`. The optional `namePrefix` overrides the value from `configure({ namePrefix })`; in normal usage you pass nothing and let the global config drive it. See [Configuration: Name prefix](configuration.md#name-prefix).
+Constructor: `new ServerStyleCollector(namePrefix?)`, or use the `createServerStyleCollector(namePrefix?)` factory. The optional `namePrefix` overrides the value from `configure({ namePrefix })`; in normal usage you pass nothing and let the global config drive it. See [Configuration: Name prefix](configuration.md#name-prefix).
 
 | Method | Description |
 |---|---|
@@ -375,7 +377,7 @@ Constructor: `new ServerStyleCollector(namePrefix?)`. The optional `namePrefix`
 | `collectInternals()` | Collect internal `@property` rules, `:root` token defaults, `@font-face`, and `@counter-style` rules from the global config. Called automatically on first chunk collection; idempotent. |
 | `getCSS()` | Get all collected CSS as a single string. For non-streaming SSR. |
 | `flushCSS()` | Get only CSS collected since the last flush. For streaming SSR. |
-| `getCacheState()` | Serialize `{ entries: Record<cacheKey, className>, classCounter }` for client hydration. |
+| `getRenderedClassNames()` | Get the list of class names rendered so far. Serialized to `window.__TASTY__` for client hydration via `hydrateTastyClasses()`. |
 
 ### `TastyRegistry`
 
@@ -402,9 +404,9 @@ Astro middleware factory. Use for manual middleware composition.
 |---|---|---|---|
 | `transferCache` | `boolean` | `true` | Embed cache state script for island hydration |
 
-### `hydrateTastyCache(state?)`
+### `hydrateTastyClasses(classes?)`
 
-Pre-populate the client injector cache. When called without arguments, reads from `window.__TASTY_SSR_CACHE__` (streaming) or `<script data-tasty-cache>` (non-streaming).
+Pre-populate the client injector's rules map with class names rendered on the server, marking them as already present in the DOM so `computeStyles()` skips re-injection during hydration. When called without arguments, reads the class list from `window.__TASTY__` (populated by the streaming `<script>` tags emitted during SSR).
 
 ### `runWithCollector(collector, fn)`
 
@@ -420,23 +422,29 @@ The `TastyRegistry` or `tastyIntegration` is missing. Ensure your layout wraps t
 
 ### Hydration mismatch warnings
 
-Class names are deterministic for the same render order. If you see mismatches, ensure `hydrateTastyCache()` runs before React hydration. For Next.js, this is automatic. For Astro with `tastyIntegration()`, this is also automatic. For manual Astro middleware setups, import `@tenphi/tasty/ssr/astro-client` in your island components. For custom setups, call `hydrateTastyCache()` before `hydrateRoot()`.
+Class names are deterministic for the same render order. If you see mismatches, ensure `hydrateTastyClasses()` runs before React hydration. For Next.js, this is automatic. For Astro with `tastyIntegration()`, this is also automatic. For manual Astro middleware setups, import `@tenphi/tasty/ssr/astro-client` in your island components. For custom setups, call `hydrateTastyClasses()` before `hydrateRoot()`.
+
+Class names are also derived from the *resolved* styles, so the server and the client must configure Tasty identically. Anything that changes what a component's styles resolve to will produce a mismatch if it is registered on only one side — `namePrefix`, `recipes`, `handlers`, and the `propHandlers` / `baseStyleProps` extension points described in [Plugins](plugins.md). Call the same `configure()` on both; global CSS is deduplicated automatically, so no `typeof window` guard is needed.
 
 ### Styles duplicated after hydration
 
 **Global CSS** (`:root` tokens, `@property`, `globalStyles`, `@font-face`, `@counter-style`) configured via `configure()` is automatically deduplicated. When Tasty detects `<style data-tasty-ssr>` in the document, it skips client-side injection of globals that were already rendered by the SSR collector. This means `configure()` can be called with the full config on both server and client — no `typeof window === 'undefined'` guard is needed.
 
-**Component CSS**: SSR `<style data-tasty-ssr>` tags remain in the DOM. The client injector creates separate `<style>` elements for any new styles. SSR styles are never modified or removed by the client. If this is a concern for very large apps, call `cleanupSSRStyles()` after hydration:
+**Component CSS**: SSR `<style data-tasty-ssr>` tags remain in the DOM. The client injector creates separate `<style>` elements for any new styles. SSR styles are never modified or removed by the client. If this is a concern for very large apps, you can remove the SSR style tags and hydration scripts manually after hydration:
 
 ```tsx
-import { hydrateTastyCache } from '@tenphi/tasty/ssr';
+import { hydrateTastyClasses } from '@tenphi/tasty/ssr';
 
-hydrateTastyCache();
+hydrateTastyClasses();
 hydrateRoot(root, <App />);
 
-// Optional: remove SSR style tags after hydration
-document.querySelectorAll('style[data-tasty-ssr]').forEach(el => el.remove());
-document.querySelectorAll('script[data-tasty-cache]').forEach(el => el.remove());
+// Optional: remove SSR style tags and class-list scripts after hydration
+document.querySelectorAll('style[data-tasty-ssr]').forEach((el) => el.remove());
+document
+  .querySelectorAll('script')
+  .forEach((el) => {
+    if (el.textContent?.includes('__TASTY__')) el.remove();
+  });
 ```
 
 ### `AsyncLocalStorage` not available

package/docs/tasty/styles.md

@@ -1,6 +1,6 @@
 # Style Properties Reference
 
-All standard CSS properties are supported in Tasty and benefit from its syntax sugar: design tokens (`$name`, `#name`), custom units (`2x`, `1r`, `1bw`), color opacity (`#purple.5`), auto-calc (`(100% - 2x)`), and custom functions. Values are parsed through the Tasty engine automatically.
+All standard CSS properties are supported in Tasty and benefit from its syntax sugar: design tokens (`$name`, `#name`), custom units (`2x`, `1r`, `1bw`), color opacity (`#purple.5`), auto-calc (`(100% - 2x)`), and [custom functions](dsl.md#functions-function) (`$$negative(10px)`). Values are parsed through the Tasty engine automatically.
 
 The properties documented below have **custom handlers** with enhanced syntax. They should be **preferred** over their raw CSS equivalents because they:
 
@@ -100,18 +100,23 @@ For flex/grid layouts, outputs native `gap`. For block layouts, emulates gap usi
 
 Element padding with directional modifiers and multi-group support. Use **comma-separated groups** to set a base value and then override specific directions.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
 **Output modifier:** `longhand` — forces output as individual CSS longhand properties (`padding-top`, `padding-right`, `padding-bottom`, `padding-left`) instead of the `padding` shorthand. Useful when children need to selectively inherit individual directions.
 
+**One value per directional group.** A group that names direction modifiers takes **exactly one** value, applied to every direction it names. For different values per side, use comma-separated groups: `padding: '2x top, 4x right'`. Writing `padding: '2x 4x top right'` ignores `4x` and warns in development — the parser keeps values and modifiers in separate buckets, so their interleaving in the source is not recoverable and `'2x 4x top right'`, `'2x top 4x right'` and `'top 2x right 4x'` are all the same input.
+
+A group that names *no* direction keeps plain CSS shorthand order, which is unambiguous and unchanged.
+
 | Value | Effect |
 |-------|--------|
 | `"2x"` | All sides `2x` |
 | `"2x 1x"` | Top/bottom `2x`, left/right `1x` |
 | `"2x top"` | Top `2x`, right/bottom/left `0` |
 | `"1x left right"` | Left and right `1x`, top/bottom `0` |
+| `"2x top, 4x right"` | Top `2x`, right `4x`, bottom/left `0` |
 | `"1x, 2x top"` | All sides `1x`, then top overridden to `2x` |
 | `"1x, 2x top bottom"` | Left/right `1x`, top/bottom `2x` |
 | `"2x longhand"` | All sides `2x`, output as 4 individual `padding-*` properties |
@@ -128,17 +133,20 @@ Individual props `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `
 
 Element margin. Same syntax, modifiers, and multi-group support as `padding`.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
 **Output modifier:** `longhand` — forces output as individual CSS longhand properties (`margin-top`, etc.) instead of the `margin` shorthand.
 
+The [one-value-per-directional-group rule](#padding) from `padding` applies here too.
+
 | Value | Effect |
 |-------|--------|
 | `"2x"` | All sides `2x` |
 | `"2x 1x"` | Top/bottom `2x`, left/right `1x` |
 | `"2x top"` | Top `2x`, right/bottom/left `0` |
+| `"2x top, 4x right"` | Top `2x`, right `4x`, bottom/left `0` |
 | `"auto left right, 1x top bottom"` | Left/right `auto`, top/bottom `1x` |
 | `true` | All sides `1x` |
 | Number | Converted to `px` |
@@ -191,17 +199,22 @@ Separate `minHeight` and `maxHeight` props are supported and override values fro
 
 Positioning offsets with directional modifiers and multi-group support. Same directional syntax as `padding`.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
+The [one-value-per-directional-group rule](#padding) from `padding` applies here too, with `dock`
+as the single exception.
+
 **`dock` modifier:** pins the named edge and spans its full length, by also applying the value
 to the two perpendicular sides. `inset: 'bottom dock'` gives `inset: auto 0 0 0` — anchored to
 the bottom, full width. Without a direction, `dock` fills every side.
 
-A second value applies to the spanned sides: `inset: '2x 4x bottom dock'` pins the bottom at
-`2x` and insets the sides by `4x`. Intended for a single edge — combining `dock` with several
-directions has no well-defined meaning.
+`dock` is the one place a directional group takes **two** values: the first insets the named
+edge, the second the sides it spans. `inset: '2x 4x bottom dock'` pins the bottom at `2x` and
+insets the sides by `4x`. A third value, or a second value without `dock`, is ignored and warns
+in development. With several directions the first value applies to each named edge and the
+second to every side they span.
 
 **Output modifier:** `longhand` — forces output as individual CSS properties (`top`, `right`, `bottom`, `left`) instead of the `inset` shorthand.
 
@@ -572,15 +585,20 @@ Scrollbar styling using CSS standard properties (`scrollbar-width`, `scrollbar-c
 
 Gradient-based edge fading using CSS masks. Use **comma-separated groups** to set different widths and colors per direction.
 
-**Syntax:** `[width] [directions...] [#from-color] [#to-color]` — comma-separated for multiple groups
+**Syntax:** `[width] [direction...] [#from-color] [#to-color]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
+A group that names edges takes a **single** width, applied to every edge it names — different
+widths per edge come from comma groups. A group that names no edge covers all four and keeps
+plain CSS shorthand order, like `padding`. See the [`padding` rule](#padding).
+
 | Value | Effect |
 |-------|--------|
 | `"top"` | Fade top edge, default width (`2x`), all other edges unfaded |
 | `"2x left right"` | Fade left and right edges with `2x` width, top/bottom unfaded |
-| `"3x 1x top bottom"` | Fade top with `3x` width, bottom with `1x` width |
+| `"3x 1x"` | All edges faded — top/bottom `3x`, left/right `1x` (CSS shorthand order) |
+| `"3x top, 1x bottom"` | Fade top with `3x` width, bottom with `1x` width |
 | `"2x #transparent #dark"` | All edges faded with `2x` width, from `#transparent` to `#dark` |
 | `"top #a #b, bottom #c #d"` | Top fades from `#a` to `#b`, bottom fades from `#c` to `#d` |
 

package/docs/tasty/tasty-static.md

@@ -20,7 +20,7 @@ The zero-runtime mode is part of the main `@tenphi/tasty` package but requires a
 | `@babel/core` | >= 7.24 | Babel plugin (`@tenphi/tasty/babel-plugin`) |
 | `@babel/helper-plugin-utils` | >= 7.24 | Babel plugin |
 | `@babel/types` | >= 7.24 | Babel plugin |
-| `jiti` | >= 2.6 | Next.js wrapper (`@tenphi/tasty/next`) when using `configFile` option |
+| `jiti` | >= 2.6 | Next.js wrapper (`@tenphi/tasty/zero/next`) when using `configFile` option |
 
 All of these are declared as optional peer dependencies of `@tenphi/tasty`. Install only what your setup requires:
 
@@ -168,10 +168,11 @@ module.exports = {
 | `config.replaceTokens` | `Record<string, string \| number>` | — | Parse-time token substitution. Keys use `$name` for custom properties and `#name` for color tokens. |
 | `config.recipes` | `Record<string, RecipeStyles>` | `{}` | Predefined style recipes |
 | `config.keyframes` | `Record<string, KeyframesSteps>` | — | Global `@keyframes` definitions available to all `tastyStatic` calls |
-| `config.fontFace` | `Record<string, FontFaceInput>` | — | Global `@font-face` definitions |
-| `config.counterStyle` | `Record<string, CounterStyleDescriptors>` | — | Global `@counter-style` definitions |
+| `config.fontFaces` | `Record<string, FontFaceInput>` | — | Global `@font-face` definitions |
+| `config.counterStyles` | `Record<string, CounterStyleDescriptors>` | — | Global `@counter-style` definitions |
 | `config.units` | `Record<string, string \| UnitHandler>` | — | Custom units for the style parser (merged with built-ins). E.g. `{ em: 'em', vw: 'vw' }` |
-| `config.funcs` | `Record<string, Function>` | — | Custom functions for the style parser (merged with existing) |
+| `config.functions` | `Record<string, FunctionDefinition \| Function>` | — | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions |
+| `config.polyfills` | `{ functions?: boolean }` | `{}` | Opt-in polyfills. `functions: true` inlines `@function` calls into plain CSS at build time |
 | `config.plugins` | `TastyPlugin[]` | — | Plugins that extend tasty with custom functions, units, states, and handlers |
 | `config.handlers` | `Record<string, StyleHandlerDefinition>` | — | Custom style handlers that transform style properties into CSS declarations |
 | `config.presets` | `Record<string, TypographyPreset>` | — | Typography presets — shorthand for `generateTypographyTokens()`. Generated tokens merge under explicit `tokens`. |
@@ -236,7 +237,7 @@ The `withTastyZero` wrapper configures both **webpack** and **Turbopack** automa
 
 ```typescript
 // next.config.ts
-import { withTastyZero } from '@tenphi/tasty/next';
+import { withTastyZero } from '@tenphi/tasty/zero/next';
 
 export default withTastyZero({
   output: 'public/tasty.css',
@@ -395,7 +396,7 @@ With Next.js:
 
 ```typescript
 // next.config.ts
-import { withTastyZero } from '@tenphi/tasty/next';
+import { withTastyZero } from '@tenphi/tasty/zero/next';
 
 export default withTastyZero({
   mode: 'inject',
@@ -545,3 +546,4 @@ const card = tastyStatic({
 - [Style DSL](dsl.md) — State maps, tokens, units, extending semantics (shared by runtime and static)
 - [React API](react-api.md) — Runtime styling: `tasty()` factory, component props, variants, sub-elements, style functions
 - [Configuration](configuration.md) — Global configuration: tokens, recipes, custom units, and style handlers
+- [Plugins & Extension Points](plugins.md) — Which extension points work at build time (`functions`, `units`, `states`, `handlers`, `recipes`) and which do not (`propHandlers` — `tastyStatic()` takes styles objects, not props)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.154.1",
+  "version": "0.156.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -53,7 +53,7 @@
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
     "@tenphi/glaze": "1.3.0",
-    "@tenphi/tasty": "2.11.2",
+    "@tenphi/tasty": "^3.0.0",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",
@@ -90,7 +90,7 @@
     "@statoscope/cli": "^5.20.1",
     "@storybook/addon-docs": "^10.3.6",
     "@storybook/react-vite": "^10.3.6",
-    "@tenphi/eslint-plugin-tasty": "^0.11.2",
+    "@tenphi/eslint-plugin-tasty": "^1.0.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.7.0",
     "@testing-library/react": "^16.3.0",