@tenphi/tasty 0.0.0-snapshot.bbd10c7 → 0.0.0-snapshot.bbfcd75

package/docs/{runtime.md → react-api.md}

@@ -1,6 +1,10 @@
-# Runtime API
+# React API
 
-The React-specific `tasty()` component factory, component props, and hooks. `tasty()` components 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).
+Use `tasty()` to turn state-aware style definitions into normal React components, extend existing Tasty components, and expose typed styling APIs to consumers.
+
+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 is needed. For state maps, tokens, units, and extension 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.
 
 ---
 
@@ -40,6 +44,32 @@ const PrimaryButton = tasty(Button, {
 
 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.
 
+`tasty(Component, ...)` always wraps `Component` and forwards every prop to it, so `Component` must be Tasty-aware (i.e. it accepts `styles`, `mods`, `qa`, etc. and renders them through its own Tasty pipeline). To apply styles to a third-party component or a string DOM tag via `className`, use the options-only form with `as`:
+
+```jsx
+import NextLink from 'next/link';
+
+const Link = tasty({
+  as: NextLink,
+  styles: {
+    color: { '': '#accent-text', ':hover': '#text' },
+    textDecoration: 'underline',
+  },
+  styleProps: ['padding'],
+});
+
+const Span = tasty({
+  as: 'span',
+  styles: { preset: 'strong' },
+});
+
+<Link href="/blog" padding="1x">
+  Blog
+</Link>;
+```
+
+The wrapped component only needs to forward `className` (and ideally `style`/`ref`). Tasty-specific props (`qa`, `qaVal`, `mods`, `tokens`, `styleProps`, `modProps`, `tokenProps`) are consumed by Tasty and never leak to the DOM.
+
 ---
 
 ## Style Props
@@ -58,7 +88,7 @@ const FlexibleBox = tasty({
 
 <FlexibleBox gap="2x" align="center" fill="#surface">
   Content
-</FlexibleBox>
+</FlexibleBox>;
 ```
 
 Style props accept state maps, so responsive values work through the same API:
@@ -72,6 +102,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
@@ -110,9 +160,9 @@ Map modifier names to type descriptors for precise TypeScript types:
 ```tsx
 const Button = tasty({
   modProps: {
-    isLoading: Boolean,   // isLoading?: boolean
-    isSelected: Boolean,  // isSelected?: boolean
-    size: ['small', 'medium', 'large'] as const,  // size?: 'small' | 'medium' | 'large'
+    isLoading: Boolean, // isLoading?: boolean
+    isSelected: Boolean, // isSelected?: boolean
+    size: ['small', 'medium', 'large'] as const, // size?: 'small' | 'medium' | 'large'
   },
   styles: {
     padding: { '': '2x 4x', 'size=small': '1x 2x', 'size=large': '3x 6x' },
@@ -120,18 +170,20 @@ const Button = tasty({
   },
 });
 
-<Button isLoading size="large">Submit</Button>
+<Button isLoading size="large">
+  Submit
+</Button>;
 // Renders: <button data-is-loading="" data-size="large">Submit</button>
 ```
 
 Available type descriptors:
 
-| Descriptor | TypeScript type | Example |
-|---|---|---|
-| `Boolean` | `boolean` | `isLoading: Boolean` |
-| `String` | `string` | `label: String` |
-| `Number` | `number` | `count: Number` |
-| `['a', 'b'] as const` | `'a' \| 'b'` | `size: ['sm', 'md', 'lg'] as const` |
+| Descriptor            | TypeScript type | Example                             |
+| --------------------- | --------------- | ----------------------------------- |
+| `Boolean`             | `boolean`       | `isLoading: Boolean`                |
+| `String`              | `string`        | `label: String`                     |
+| `Number`              | `number`        | `count: Number`                     |
+| `['a', 'b'] as const` | `'a' \| 'b'`    | `size: ['sm', 'md', 'lg'] as const` |
 
 ### Merge with `mods`
 
@@ -144,11 +196,11 @@ Mod props and the `mods` object can be used together. Mod props take precedence:
 
 ### When to use `modProps` vs `mods`
 
-| Use case | Recommendation |
-|---|---|
+| Use case                                     | Recommendation                                           |
+| -------------------------------------------- | -------------------------------------------------------- |
 | Component has a fixed set of known modifiers | `modProps` — cleaner API, better TypeScript autocomplete |
-| Component needs arbitrary/dynamic modifiers | `mods` — open-ended `Record<string, ModValue>` |
-| Both fixed and dynamic | Combine: `modProps` for known keys, `mods` for ad-hoc |
+| Component needs arbitrary/dynamic modifiers  | `mods` — open-ended `Record<string, ModValue>`           |
+| Both fixed and dynamic                       | Combine: `modProps` for known keys, `mods` for ad-hoc    |
 
 For architecture guidance on when to use modifiers vs `styleProps`, see [Methodology — modProps and mods](methodology.md#modprops-and-mods).
 
@@ -178,7 +230,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
@@ -194,7 +246,7 @@ const Card = tasty({
   styles: { padding: '$card-size', fill: '#card-accent' },
 });
 
-<Card size="4x" color="#purple" />
+<Card size="4x" color="#purple" />;
 ```
 
 ### Merge with `tokens`
@@ -213,11 +265,11 @@ const Bar = tasty({
 
 ### When to use `tokenProps` vs `tokens`
 
-| Use case | Recommendation |
-|---|---|
-| Component has a fixed set of known token keys | `tokenProps` — cleaner API, better TypeScript autocomplete |
-| Component needs arbitrary/dynamic token values | `tokens` — open-ended `Record<string, TokenValue>` |
-| Both fixed and dynamic | Combine: `tokenProps` for known keys, `tokens` for ad-hoc |
+| Use case                                       | Recommendation                                             |
+| ---------------------------------------------- | ---------------------------------------------------------- |
+| Component has a fixed set of known token keys  | `tokenProps` — cleaner API, better TypeScript autocomplete |
+| Component needs arbitrary/dynamic token values | `tokens` — open-ended `Record<string, TokenValue>`         |
+| Both fixed and dynamic                         | Combine: `tokenProps` for known keys, `tokens` for ad-hoc  |
 
 For architecture guidance, see [Methodology — tokenProps](methodology.md#tokenprops).
 
@@ -236,11 +288,11 @@ const Button = tasty({
   variants: {
     default: { fill: '#blue', color: '#white' },
     danger: { fill: '#red', color: '#white' },
-    outline: { fill: 'transparent', color: '#blue', border: '1bw solid #blue' },
+    outline: { fill: '#clear', color: '#blue', border: '1bw solid #blue' },
   },
 });
 
-<Button variant="danger">Delete</Button>
+<Button variant="danger">Delete</Button>;
 ```
 
 ### Extending Variants with Base State Maps
@@ -296,7 +348,7 @@ const Card = tasty({
 <Card>
   <Card.Title>Card Title</Card.Title>
   <Card.Content>Card content</Card.Content>
-</Card>
+</Card>;
 ```
 
 Each entry in `elements` can be a tag name string or a config object:
@@ -322,7 +374,7 @@ const Card = tasty({
 
 <Card>
   <div data-element="Title">Card Title</div>
-</Card>
+</Card>;
 ```
 
 ### Selector Affix (`$`)
@@ -351,11 +403,15 @@ On the client, CSS is injected synchronously into the DOM (idempotent via the in
 
 ---
 
-## Hooks
+## Style Functions
+
+All style functions below are plain functions (not React hooks) and can be used in any environment: client components, SSR with a `ServerStyleCollector`, and React Server Components. They retain their `use` prefix for backward compatibility, but do not use any React hooks internally.
+
+In server-only contexts, components that use only Tasty style functions ship no Tasty styling runtime. Astro without `client:*` directives produces no client JavaScript; server-only Next.js RSC follows the same Tasty architecture, while final output depends on the application deployment. Tasty never forces the `'use client'` boundary — that decision belongs to your component when it needs React interactivity (state, effects, event handlers).
 
 ### useStyles
 
-Generate a className from a style object. Thin wrapper around `computeStyles()` that adds React context-based SSR collector discovery for backward compatibility:
+Generate a className from a style object. Thin wrapper around `computeStyles()`:
 
 ```tsx
 import { useStyles } from '@tenphi/tasty';
@@ -373,7 +429,7 @@ function MyComponent() {
 
 ### useGlobalStyles
 
-Inject global styles for a CSS selector:
+Inject global styles for a CSS selector. Accepts an optional third argument with an `id` for update tracking — when the styles change, the previous injection is disposed and the new one is injected:
 
 ```tsx
 import { useGlobalStyles } from '@tenphi/tasty';
@@ -389,9 +445,18 @@ function ThemeStyles() {
 }
 ```
 
+A slot — the `id`, or the selector when no `id` is given — holds exactly one
+injection **per `root`**. So:
+
+- Changing the styles replaces the previous CSS rather than adding to it.
+- Passing styles that produce no CSS (for example `{}`) clears the slot.
+- The same selector used in two shadow roots keeps a separate injection in each.
+- Two independent call sites that share a selector share a slot, and the last
+  render wins. Give them distinct `id`s if they should coexist.
+
 ### useRawCSS
 
-Inject raw CSS strings:
+Inject raw CSS strings. Accepts an optional `id` in the options for update tracking — when the CSS changes for the same id, the previous injection is replaced:
 
 ```tsx
 import { useRawCSS } from '@tenphi/tasty';
@@ -405,6 +470,9 @@ function GlobalReset() {
 }
 ```
 
+An `id` slot holds one injection per `root`. Without an `id` the CSS is deduped
+by content and permanent — there is nothing to replace it with later.
+
 ### useKeyframes
 
 Inject `@keyframes` rules and return the generated animation name:
@@ -418,14 +486,14 @@ function Spinner() {
       from: { transform: 'rotate(0deg)' },
       to: { transform: 'rotate(360deg)' },
     },
-    { name: 'spin' }
+    { name: 'spin' },
   );
 
   return <div style={{ animation: `${spin} 1s linear infinite` }} />;
 }
 ```
 
-`useKeyframes()` also supports a factory function with dependencies:
+`useKeyframes()` also supports a factory function. Without a `name` the factory runs on every invocation and deduplication is handled internally by content hash; with a `name`, matching deps skip the factory entirely:
 
 ```tsx
 function Pulse({ scale }: { scale: number }) {
@@ -434,13 +502,24 @@ function Pulse({ scale }: { scale: number }) {
       '0%': { transform: 'scale(1)' },
       '100%': { transform: `scale(${scale})` },
     }),
-    [scale]
+    [scale],
+    { name: 'pulse' },
   );
 
-  return <div style={{ animation: `${pulse} 500ms ease-in-out alternate infinite` }} />;
+  return (
+    <div
+      style={{ animation: `${pulse} 500ms ease-in-out alternate infinite` }}
+    />
+  );
 }
 ```
 
+Passing `name` claims a slot owned by that one call site, per `root` — much like
+`id` in `useGlobalStyles()` and `useRawCSS()`. When the steps change the previous
+`@keyframes` rule is disposed and the name is reused, so the rules don't
+accumulate and the returned name stays stable. Anonymous keyframes are permanent
+and shared by content.
+
 ### useProperty
 
 Register a CSS `@property` rule so a custom property can animate smoothly:
@@ -487,8 +566,16 @@ For multiple weights/styles, pass an array:
 
 ```tsx
 useFontFace('Brand Sans', [
-  { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
-  { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },
+  {
+    src: 'url("/fonts/brand-regular.woff2") format("woff2")',
+    fontWeight: 400,
+    fontDisplay: 'swap',
+  },
+  {
+    src: 'url("/fonts/brand-bold.woff2") format("woff2")',
+    fontWeight: 700,
+    fontDisplay: 'swap',
+  },
 ]);
 ```
 
@@ -506,11 +593,14 @@ Inject a `@counter-style` rule and get back the counter style name. Permanent
 import { useCounterStyle } from '@tenphi/tasty';
 
 function EmojiList() {
-  const styleName = useCounterStyle({
-    system: 'cyclic',
-    symbols: '"👍"',
-    suffix: '" "',
-  }, { name: 'thumbs' });
+  const styleName = useCounterStyle(
+    {
+      system: 'cyclic',
+      symbols: '"👍"',
+      suffix: '" "',
+    },
+    { name: 'thumbs' },
+  );
 
   return (
     <ol style={{ listStyleType: styleName }}>
@@ -521,43 +611,62 @@ function EmojiList() {
 }
 ```
 
-Factory form with dependencies:
+Signature:
+
+```ts
+function useCounterStyle(
+  descriptors: CounterStyleDescriptors,
+  options?: { name?: string; root?: Document | ShadowRoot },
+): 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
-function DynamicList({ marker }: { marker: string }) {
-  const styleName = useCounterStyle(
-    () => ({
-      system: 'cyclic',
-      symbols: `"${marker}"`,
-      suffix: '" "',
-    }),
-    [marker],
-  );
+import { tasty, useFunction } from '@tenphi/tasty';
+
+const Box = tasty({ styles: { margin: '$$negative(10px) top' } });
 
-  return <ol style={{ listStyleType: styleName }}>...</ol>;
+function Layout() {
+  useFunction('$$negative', { args: ['$value'], result: '(-1 * $value)' });
+  return <Box />;
 }
 ```
 
-Signatures:
+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.
 
-```ts
-function useCounterStyle(
-  descriptors: CounterStyleDescriptors,
-  options?: { name?: string; root?: Document | ShadowRoot },
-): string;
+Inside a `tasty()` component you call functions with the same `$$name(...)` sugar:
 
-function useCounterStyle(
-  factory: () => CounterStyleDescriptors,
-  deps: readonly unknown[],
-  options?: { name?: string; root?: Document | ShadowRoot },
-): string;
+```tsx
+const Box = tasty({
+  styles: {
+    '@function': { $$negative: { args: ['$value'], result: '(-1 * $value)' } },
+    margin: '$$negative(10px) top',
+  },
+});
+```
+
+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).
-- SSR output looks wrong: check the [SSR guide](ssr.md) for collector setup. `computeStyles()` discovers the SSR collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`.
+- SSR output looks wrong: check the [SSR guide](ssr.md) for collector setup. All style functions discover the SSR collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`.
 - Animation/custom property issues: prefer `useKeyframes()` and `useProperty()` over raw CSS when you want Tasty to manage injection and SSR collection for you.
+- For dynamic styles that change over the component lifecycle, use the `id` option in `useGlobalStyles()` and `useRawCSS()` to enable update tracking.
+- RSC inline mode: CSS accumulated by standalone style functions (`useGlobalStyles`, `useRawCSS`, etc.) is flushed into inline `<style>` tags by the next `tasty()` component in the render tree. If your page uses only standalone style functions without any `tasty()` component, the CSS will not be emitted. Ensure at least one `tasty()` component is present in each RSC render tree.
 
 ---
 
@@ -567,6 +676,6 @@ function useCounterStyle(
 - **[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
+- **[Build-Time Extraction (`tastyStatic`)](tasty-static.md)** — Static styling with the Babel plugin
 - **[Server-Side Rendering](ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks
 - **[Debug Utilities](debug.md)** — Inspect injected CSS, cache state, and active styles at runtime