@cube-dev/ui-kit 0.121.4 → 0.121.6

package/docs/tasty/runtime.md

@@ -0,0 +1,291 @@
+# Runtime API
+
+The React-specific `tasty()` component factory, component props, and hooks. For the shared style language (state maps, tokens, units, extending semantics), see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md).
+
+---
+
+## Component Creation
+
+### Create a new component
+
+```jsx
+import { tasty } from '@tenphi/tasty';
+
+const Card = tasty({
+  as: 'div',
+  styles: {
+    padding: '4x',
+    fill: '#white',
+    border: true,
+    radius: true,
+  },
+  styleProps: ['padding', 'fill'],
+});
+
+<Card>Hello World</Card>
+<Card padding="6x" fill="#gray.05">Custom Card</Card>
+```
+
+### Extend an existing component
+
+```jsx
+const PrimaryButton = tasty(Button, {
+  styles: {
+    fill: '#purple',
+    color: '#white',
+    padding: '2x 4x',
+  },
+});
+```
+
+Style maps merge intelligently — see [Style DSL — Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps) for extend mode, replace mode, `@inherit`, `null`, and `false` tombstones.
+
+---
+
+## Style Props
+
+Use `styleProps` to expose style properties as direct component props:
+
+```jsx
+const FlexibleBox = tasty({
+  as: 'div',
+  styles: {
+    display: 'flex',
+    padding: '2x',
+  },
+  styleProps: ['gap', 'align', 'placeContent', 'fill'],
+});
+
+<FlexibleBox gap="2x" align="center" fill="#surface">
+  Content
+</FlexibleBox>
+```
+
+Style props accept state maps, so responsive values work through the same API:
+
+```jsx
+<FlexibleBox
+  gap={{ '': '2x', '@tablet': '4x' }}
+  fill={{ '': '#surface', '@dark': '#surface-dark' }}
+>
+```
+
+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).
+
+---
+
+## Variants
+
+Define named style variations. Only CSS for variants actually used at runtime is injected:
+
+```jsx
+const Button = tasty({
+  styles: {
+    padding: '2x 4x',
+    border: true,
+  },
+  variants: {
+    default: { fill: '#blue', color: '#white' },
+    danger: { fill: '#red', color: '#white' },
+    outline: { fill: 'transparent', color: '#blue', border: '1bw solid #blue' },
+  },
+});
+
+<Button variant="danger">Delete</Button>
+```
+
+### Extending Variants with Base State Maps
+
+When base `styles` contain an extend-mode state map (an object **without** a `''` key), it is applied **after** the variant merge. This lets you add or override states across all variants without repeating yourself:
+
+```jsx
+const Badge = tasty({
+  styles: {
+    padding: '1x 2x',
+    border: {
+      'type=primary': '#clear',
+    },
+  },
+  variants: {
+    primary: {
+      border: { '': '#white.2', pressed: '#primary-text', disabled: '#clear' },
+      fill: { '': '#white #primary', hovered: '#white #primary-text' },
+    },
+    secondary: {
+      border: { '': '#primary.15', pressed: '#primary.3' },
+      fill: '#primary.10',
+    },
+  },
+});
+
+// Both variants get 'type=primary': '#clear' appended to their border map
+```
+
+Properties that are **not** extend-mode (simple values, state maps with `''`, `null`, `false`, selectors, sub-elements) merge with variants as before — the variant can fully replace them.
+
+---
+
+## Sub-element Styling
+
+Sub-elements are inner parts of a compound component, styled via capitalized keys in `styles` and identified by `data-element` attributes in the DOM.
+
+> Use the `elements` prop to declare sub-element components. This gives you typed, reusable sub-components (`Card.Title`, `Card.Content`) instead of manually writing `data-element` attributes.
+
+```jsx
+const Card = tasty({
+  styles: {
+    padding: '4x',
+    Title: { preset: 'h3', color: '#primary' },
+    Content: { color: '#text' },
+  },
+  elements: {
+    Title: 'h3',
+    Content: 'div',
+  },
+});
+
+<Card>
+  <Card.Title>Card Title</Card.Title>
+  <Card.Content>Card content</Card.Content>
+</Card>
+```
+
+Each entry in `elements` can be a tag name string or a config object:
+
+```jsx
+elements: {
+  Title: 'h3',                          // shorthand: tag name only
+  Icon: { as: 'span', qa: 'card-icon' }, // full form: tag + QA attribute
+}
+```
+
+The sub-components produced by `elements` support `mods`, `tokens`, `isDisabled`, `isHidden`, and `isChecked` props — the same modifier interface as the root component.
+
+If you don't need sub-components (e.g., the inner elements are already rendered by a third-party library), you can still style them by key alone — just omit `elements` and apply `data-element` manually:
+
+```jsx
+const Card = tasty({
+  styles: {
+    padding: '4x',
+    Title: { preset: 'h3', color: '#primary' },
+  },
+});
+
+<Card>
+  <div data-element="Title">Card Title</div>
+</Card>
+```
+
+### Selector Affix (`$`)
+
+Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles:
+
+| Pattern | Result | Description |
+|---------|--------|-------------|
+| *(none)* | ` [el]` | Descendant (default) |
+| `>` | `> [el]` | Direct child |
+| `>Body>Row>` | `> [Body] > [Row] > [el]` | Chained elements |
+| `::before` | `::before` | Root pseudo (no key) |
+| `@::before` | `[el]::before` | Pseudo on the sub-element |
+| `>@:hover` | `> [el]:hover` | Pseudo-class on the sub-element |
+| `>@.active` | `> [el].active` | Class on the sub-element |
+
+The `@` placeholder marks exactly where the `[data-element="..."]` selector is injected, allowing you to attach pseudo-classes, pseudo-elements, or class selectors directly to the sub-element instead of the root:
+
+```jsx
+const List = tasty({
+  styles: {
+    Item: {
+      $: '>@:last-child',
+      border: 'none',
+    },
+  },
+});
+// → .t0 > [data-element="Item"]:last-child { border: none }
+```
+
+For the mental model behind sub-elements — how they share root state context and how this differs from BEM — see [Methodology — Component architecture](methodology.md#component-architecture-root--sub-elements).
+
+---
+
+## Hooks
+
+### useStyles
+
+Generate a className from a style object:
+
+```tsx
+import { useStyles } from '@tenphi/tasty';
+
+function MyComponent() {
+  const { className } = useStyles({
+    padding: '2x',
+    fill: '#surface',
+    radius: '1r',
+  });
+
+  return <div className={className}>Styled content</div>;
+}
+```
+
+### useGlobalStyles
+
+Inject global styles for a CSS selector:
+
+```tsx
+import { useGlobalStyles } from '@tenphi/tasty';
+
+function ThemeStyles() {
+  useGlobalStyles('.card', {
+    padding: '4x',
+    fill: '#surface',
+    radius: '1r',
+  });
+
+  return null;
+}
+```
+
+### useRawCSS
+
+Inject raw CSS strings:
+
+```tsx
+import { useRawCSS } from '@tenphi/tasty';
+
+function GlobalReset() {
+  useRawCSS(`
+    body { margin: 0; padding: 0; }
+  `);
+
+  return null;
+}
+```
+
+### useMergeStyles
+
+Merge multiple style objects for compound component prop forwarding:
+
+```tsx
+import { useMergeStyles } from '@tenphi/tasty';
+
+function MyTabs({ styles, tabListStyles, prefixStyles }) {
+  const mergedStyles = useMergeStyles(styles, {
+    TabList: tabListStyles,
+    Prefix: prefixStyles,
+  });
+
+  return <TabsElement styles={mergedStyles} />;
+}
+```
+
+---
+
+## Learn more
+
+- **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
+- **[Methodology](methodology.md)** — Recommended patterns: root + sub-elements, styleProps, tokens, wrapping
+- **[Configuration](configuration.md)** — Tokens, recipes, custom units, style handlers, TypeScript extensions
+- **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
+- **[Zero Runtime (tastyStatic)](tasty-static.md)** — Build-time static styling with Babel plugin
+- **[Server-Side Rendering](ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks

package/docs/tasty/ssr.md

@@ -0,0 +1,382 @@
+# Server-Side Rendering (SSR)
+
+Tasty supports server-side rendering with zero-cost client hydration. Your existing `tasty()` components work unchanged -- SSR is opt-in and requires no per-component modifications.
+
+---
+
+## Requirements
+
+| Dependency | Version | Required for |
+|---|---|---|
+| `react` | >= 18 | All SSR entry points (peer dependency of `@tenphi/tasty`) |
+| `next` | >= 13 | Next.js integration (`@tenphi/tasty/ssr/next`) — App Router with `useServerInsertedHTML` |
+| Node.js | >= 20 | Generic / streaming SSR (`@tenphi/tasty/ssr`) — uses `node:async_hooks` for `AsyncLocalStorage` |
+
+The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies beyond `react`.
+
+---
+
+## How It Works
+
+During server rendering, `useStyles()` detects a `ServerStyleCollector` and collects CSS into it instead of trying to access the DOM. 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 `useStyles()` skips the rendering pipeline entirely during hydration.
+
+```
+Server                         Client
+──────                         ──────
+tasty() renders                hydrateTastyCache() pre-populates cache
+  └─ useStyles()                 └─ cacheKey → className map ready
+       └─ collector.collect()
+                                 tasty() renders
+After render:                    └─ useStyles()
+  <style data-tasty-ssr>              └─ cache hit → skip pipeline
+  <script data-tasty-cache>           └─ no CSS re-injection
+```
+
+---
+
+## Next.js (App Router)
+
+### 1. Create the registry
+
+Create a client component that wraps your tree with `TastyRegistry`:
+
+```tsx
+// app/tasty-registry.tsx
+'use client';
+
+import { TastyRegistry } from '@tenphi/tasty/ssr/next';
+
+export default function TastyStyleRegistry({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <TastyRegistry>{children}</TastyRegistry>;
+}
+```
+
+### 2. Add to root layout
+
+Wrap your application in the registry:
+
+```tsx
+// app/layout.tsx
+import TastyStyleRegistry from './tasty-registry';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html>
+      <body>
+        <TastyStyleRegistry>{children}</TastyStyleRegistry>
+      </body>
+    </html>
+  );
+}
+```
+
+That's it. All `tasty()` components inside the tree automatically get SSR support. No per-component changes needed.
+
+### How it works
+
+- `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load.
+- During SSR, `useStyles()` finds the collector via React context and pushes CSS rules to it.
+- `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 `<script>` tag transfers the `cacheKey → className` mapping to the client.
+- When the module loads on the client, `hydrateTastyCache()` runs automatically and pre-populates the injector cache. During hydration, `useStyles()` hits the cache and skips the entire pipeline.
+
+### Using tasty() in Server Components
+
+`tasty()` components use React hooks internally, so they require `'use client'`. However, this does **not** prevent them from being used in Server Component pages. In Next.js, `'use client'` components are still server-rendered on initial load. Dynamic `styleProps` like `<Grid flow="column">` work normally when a `tasty()` component is imported into a Server Component page.
+
+### Options
+
+```tsx
+// Skip cache state transfer (saves payload size at the cost of hydration perf)
+<TastyRegistry transferCache={false}>{children}</TastyRegistry>
+```
+
+### CSP nonce
+
+If your app uses Content Security Policy with nonces, configure it before rendering:
+
+```tsx
+// app/layout.tsx or a server-side init file
+import { configure } from '@tenphi/tasty';
+
+configure({ nonce: 'your-nonce-value' });
+```
+
+The nonce is automatically applied to all `<style>` and `<script>` tags injected by `TastyRegistry`.
+
+---
+
+## Astro
+
+### 1. Add the middleware
+
+Create or update your Astro middleware:
+
+```ts
+// src/middleware.ts
+import { tastyMiddleware } from '@tenphi/tasty/ssr/astro';
+
+export const onRequest = tastyMiddleware();
+```
+
+### 2. Use tasty() components as normal
+
+```tsx
+// src/components/Card.tsx
+import { tasty } from '@tenphi/tasty';
+
+const Card = tasty({
+  styles: {
+    padding: '4x',
+    fill: '#surface',
+    radius: '1r',
+    border: true,
+  },
+});
+
+export default Card;
+```
+
+```astro
+---
+// src/pages/index.astro
+import Card from '../components/Card.tsx';
+---
+
+<html>
+  <body>
+    <Card>Static card — styles collected by middleware</Card>
+    <Card client:load>Island card — styles hydrated on client</Card>
+  </body>
+</html>
+```
+
+### How it works
+
+Astro's `@astrojs/react` renderer calls `renderToString()` for each React component without wrapping the tree in a provider. The middleware uses `AsyncLocalStorage` to make the collector available to all `useStyles()` calls within the request.
+
+- **Static components** (no `client:*`): Styles are collected during `renderToString` and injected into `</head>`. No JavaScript is shipped for these components.
+- **Islands** (`client:load`, `client:visible`, etc.): Styles are collected during SSR the same way. On the client, importing `@tenphi/tasty/ssr/astro` auto-hydrates the cache from `<script data-tasty-cache>`. The island's `useStyles()` calls hit the cache during hydration.
+
+### Client-side hydration for islands
+
+The `@tenphi/tasty/ssr/astro` module auto-hydrates when imported on the client. To ensure the cache is warm before any island renders, import it in a shared entry point or in each island component:
+
+```tsx
+// src/components/MyIsland.tsx
+import '@tenphi/tasty/ssr/astro'; // auto-hydrates cache on import
+import { tasty } from '@tenphi/tasty';
+
+const MyIsland = tasty({
+  styles: { padding: '2x', fill: '#blue' },
+});
+
+export default MyIsland;
+```
+
+### Options
+
+```ts
+// Skip cache state transfer
+export const onRequest = tastyMiddleware({ transferCache: false });
+```
+
+### CSP nonce
+
+Same as Next.js -- call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected tags.
+
+---
+
+## Generic Framework Integration
+
+Any React-based framework can integrate using the core SSR API:
+
+```tsx
+import {
+  ServerStyleCollector,
+  TastySSRContext,
+  hydrateTastyCache,
+} from '@tenphi/tasty/ssr';
+import { renderToString } from 'react-dom/server';
+import { hydrateRoot } from 'react-dom/client';
+
+// ── Server ──────────────────────────────────────────────
+
+const collector = new ServerStyleCollector();
+
+const html = renderToString(
+  <TastySSRContext.Provider value={collector}>
+    <App />
+  </TastySSRContext.Provider>
+);
+
+const css = collector.getCSS();
+const cacheState = collector.getCacheState();
+
+// 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>
+    </head>
+    <body>
+      <div id="root">${html}</div>
+    </body>
+  </html>
+`;
+
+// ── Client ──────────────────────────────────────────────
+
+// Before hydration:
+hydrateTastyCache(); // reads from <script data-tasty-cache>
+
+hydrateRoot(document.getElementById('root'), <App />);
+```
+
+### Streaming SSR
+
+For streaming with `renderToPipeableStream`, use `flushCSS()` instead of `getCSS()`:
+
+```tsx
+const collector = new ServerStyleCollector();
+
+const stream = renderToPipeableStream(
+  <TastySSRContext.Provider value={collector}>
+    <App />
+  </TastySSRContext.Provider>,
+  {
+    onShellReady() {
+      // Flush styles collected so far
+      const css = collector.flushCSS();
+      res.write(`<style data-tasty-ssr>${css}</style>`);
+      stream.pipe(res);
+    },
+    onAllReady() {
+      // Flush any remaining styles + cache state
+      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>`);
+    },
+  }
+);
+```
+
+### AsyncLocalStorage (no React context)
+
+If your framework doesn't support wrapping the React tree with a provider, use `runWithCollector`:
+
+```tsx
+import {
+  ServerStyleCollector,
+  runWithCollector,
+  hydrateTastyCache,
+} from '@tenphi/tasty/ssr';
+
+const collector = new ServerStyleCollector();
+
+const html = await runWithCollector(collector, () =>
+  renderToString(<App />)
+);
+
+const css = collector.getCSS();
+// ... inject into HTML as above
+```
+
+---
+
+## API Reference
+
+### Entry points
+
+| Import path | Description |
+|---|---|
+| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `TastySSRContext`, `runWithCollector`, `hydrateTastyCache` |
+| `@tenphi/tasty/ssr/next` | Next.js App Router: `TastyRegistry` component |
+| `@tenphi/tasty/ssr/astro` | Astro: `tastyMiddleware`, auto-hydration on import |
+
+### `ServerStyleCollector`
+
+Server-safe style collector. One instance per request.
+
+| Method | Description |
+|---|---|
+| `allocateClassName(cacheKey)` | Allocate a sequential class name (`t0`, `t1`, ...) for a cache key. Returns `{ className, isNewAllocation }`. |
+| `collectChunk(cacheKey, className, rules)` | Record CSS rules for a chunk. Deduplicated by `cacheKey`. |
+| `collectKeyframes(name, css)` | Record a `@keyframes` rule. Deduplicated by name. |
+| `collectProperty(name, css)` | Record a `@property` rule. Deduplicated by name. |
+| `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. |
+
+### `TastySSRContext`
+
+React context (`createContext<ServerStyleCollector | null>(null)`). Used by `useStyles()` to find the collector during SSR.
+
+### `TastyRegistry`
+
+Next.js App Router component. Props:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | required | Application tree |
+| `transferCache` | `boolean` | `true` | Embed cache state script for zero-cost hydration |
+
+### `tastyMiddleware(options?)`
+
+Astro middleware factory. Options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `transferCache` | `boolean` | `true` | Embed cache state script for island hydration |
+
+### `hydrateTastyCache(state?)`
+
+Pre-populate the client injector cache. When called without arguments, reads from `window.__TASTY_SSR_CACHE__` (streaming) or `<script data-tasty-cache>` (non-streaming).
+
+### `runWithCollector(collector, fn)`
+
+Run a function with a `ServerStyleCollector` bound to the current async context via `AsyncLocalStorage`. All `useStyles()` calls within `fn` (and async continuations) will find this collector.
+
+---
+
+## Troubleshooting
+
+### Styles flash on page load (FOUC)
+
+The `TastyRegistry` or `tastyMiddleware` is missing. Ensure your layout wraps the app with `TastyRegistry` (Next.js) or the middleware is registered (Astro).
+
+### 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, import `@tenphi/tasty/ssr/astro` in your island components. For custom setups, call `hydrateTastyCache()` before `hydrateRoot()`.
+
+### Styles duplicated after hydration
+
+This is expected and harmless. 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:
+
+```tsx
+import { hydrateTastyCache } from '@tenphi/tasty/ssr';
+
+hydrateTastyCache();
+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());
+```
+
+### `AsyncLocalStorage` not available
+
+The `@tenphi/tasty/ssr` entry point imports from `node:async_hooks`. This is excluded from client bundles by the build configuration. If you see import errors on the client, ensure your bundler treats `node:async_hooks` as external or use the `@tenphi/tasty/ssr/next` entry point (which does not use ALS).

package/docs/tasty/styles.md

@@ -344,7 +344,7 @@ Box shadow. Supports multiple shadows comma-separated.
 
 | Value | Effect |
 |-------|--------|
-| `true` | Default shadow (from `$shadow` token) |
+| `true` | Default shadow (uses `var(--shadow)` — define a `$shadow` token in your design system) |
 | `"1x .5x .5x #dark.50"` | Custom shadow with Tasty units/colors |
 | `"0 1x 2x #dark.20"` | Standard shadow |
 | `"inset 0 1x 2x #dark.10"` | Inset shadow |
@@ -511,7 +511,7 @@ Scrollbar styling using CSS standard properties (`scrollbar-width`, `scrollbar-c
 
 **Colors:** Up to 2 color values for thumb and track (optional), applied via `scrollbar-color`.
 
-**Defaults:** When no colors are specified, the thumb color comes from the `#scrollbar-thumb` token (`#text.5`) and the track color from the `#scrollbar-track` token (`#dark-bg`). These tokens are provided by the base token set. If the base tokens are not loaded, the track falls back to `transparent` via a CSS fallback, while the thumb has no CSS-level fallback — the browser treats the entire `scrollbar-color` declaration as invalid and reverts to the platform-default scrollbar appearance.
+**Defaults:** When no colors are specified, the thumb color comes from `var(--scrollbar-thumb-color)` and the track color from `var(--scrollbar-track-color, transparent)`. These are not built-in — your design system should define `#scrollbar-thumb` and `#scrollbar-track` tokens (e.g. `'#text.5'` and `'#dark-bg'`). If neither token is defined, the track falls back to `transparent` via a CSS fallback, while the thumb has no CSS-level fallback — the browser treats the entire `scrollbar-color` declaration as invalid and reverts to the platform-default scrollbar appearance.
 
 **Note:** `none` takes precedence over all other modifiers and colors. Combining `none` with other tokens (e.g., `"none always #red"`) produces a warning, and only `scrollbar-width: none` is applied.