haze-ui 1.32.0 → 1.33.0

package/README.md

@@ -1,6 +1,6 @@
 # Haze UI
 
-> The React UI Component Library with controllable states.
+> The React UI component library with controllable states.
 
 English | [简体中文](./README-zh_CN.md)
 
@@ -8,1246 +8,123 @@ English | [简体中文](./README-zh_CN.md)
 [![downloads](https://img.shields.io/npm/dm/haze-ui.svg)](https://www.npmjs.com/package/haze-ui)
 [![CI](https://github.com/wmzy/haze-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/wmzy/haze-ui/actions/workflows/ci.yml)
 
-## Features
+haze-ui is a React 19 component library styled with Linaria (zero-runtime
+CSS-in-JS) against `--haze-*` design tokens: 140 components in 9 groups,
+ESM-only with a tree-shakeable `preserveModules` dist, RTL by construction,
+and an RSC-aware split (`'use client'` is pre-injected only on interactive
+modules, so the static subset renders as React Server Components). Every
+stateful component speaks the same `ControlOrValue<T>` protocol — one prop,
+`checked?: Control<T> | T`, covers controlled *and* uncontrolled usage.
+Only `react` and `react-dom` (v19) are peers; every engine (react-f0rm,
+TanStack Table, recharts, dnd-kit, qrcode) is a regular dependency that
+tree-shakes away when your imports never reach it.
 
-- Integrated [react use control](https://github.com/wmzy/react-use-control) provides component internal states
-- Built for React 19+ (`ref` as a prop, `ControlOrValue<T>` state protocol) — no React 18 compatibility layer
-- Keep strict, provide lightweight, composable, and easily extendable components
-- Support themes customization
-- Support Tree-shaking
-- RTL by construction: CSS logical properties, mirrored horizontal-key
-  semantics (Tabs, Rating, Slider, Carousel, Calendar, menus, …) and
-  mirrored floating placements under `dir="rtl"`
-- RSC-aware dist: interactive modules carry `'use client'`; 36 static,
-  hook-free modules (tokens, Badge, Card, Typography, …) ship without it
-  so they render as React Server Components
-- Tested like a product: 120+ unit test files, axe accessibility cases in
-  every component test suite, ~50 Playwright e2e scenarios across
-  Chromium/Firefox/WebKit, and pixel-locked visual baselines
-
-## Why npm-distributed (not copy-paste)
-
-**Interaction states are formulas, not values.** Every hover/active/subtle/focus-ring color is a CSS relative-color expression — `oklch(from var(--haze-color-primary) calc(l - 0.045) c h)` — baked into `tokens.css`. Override `--haze-color-primary` on a theme class and the entire interaction-state family re-derives at runtime in the browser, no rebuild, no codegen. In a copy-paste setup every pasted file owns its own copy of that formula, and each theme tweak means re-applying it by hand, file by file.
-
-**`haze-ui/css-manifest.json` is machine-readable data.** The authoritative export → CSS-file mapping (family absorption included) is regenerated on every build, so bundler plugins and codemods read one source of truth instead of re-deriving kebab-case file names. A directory of pasted components has no equivalent — the mapping exists only in your head or your fork, and it drifts.
-
-**The `ControlOrValue<T>` protocol needs a real runtime.** One prop — `checked?: Control<T> | T` — covers controlled *and* uncontrolled usage because `react-use-control` carries the wiring; a published package is the contract that keeps that behavior identical across every component and version. None of this is hostile to the shadcn / Base UI ecosystem: haze-ui tokens are plain CSS custom properties, and haze components compose alongside copy-pasted primitives wherever each fits.
-
-## Getting Started
-
-### Quickstart via create-haze-ui
-
-Scaffold a ready-to-run app with the official templates — the CLI has zero
-runtime dependencies and needs no network access beyond dependency install:
-
-```sh
-pnpm create haze-ui my-app                    # vite template (default)
-pnpm create haze-ui my-app --template nextjs  # or: npm create haze-ui@latest my-app --
-```
-
-The **vite** template is a React 19 + Vite + TypeScript single-page demo
-(`Button` / `Input` / `Dialog` / `Toast`) with the theme classes mounted on
-the page root; the **nextjs** template is a Next.js 15 App Router starter
-whose home page renders the RSC-safe static subset (`Badge` / `Card` /
-`Typography`) as a server component, with a client island for the
-interactive pieces. Prefer wiring an existing project by hand? Continue
-with Installation below.
-
-### Installation
+## Quickstart
 
 ```sh
 npm i haze-ui
-// or
+# or
 pnpm add haze-ui
 ```
 
-### Install via shadcn CLI (GitHub registry)
-
-The repository is also a [shadcn registry](https://ui.shadcn.com/docs/registry/github),
-so the shadcn CLI installs any component directly from GitHub — no manual
-npm setup:
-
-```sh
-pnpm dlx shadcn@latest add wmzy/haze-ui/button
-pnpm dlx shadcn@latest add wmzy/haze-ui/dialog wmzy/haze-ui/tabs
-pnpm dlx shadcn@latest add wmzy/haze-ui/base   # everything at once
-pnpm dlx shadcn@latest list wmzy/haze-ui   # browse all items
-```
-
-The `base` item (type `registry:base`) is the one-command path: it
-installs the theme-token activation plus a wrapper for every component in
-a single `shadcn add` — the 107 component items are pulled in through
-`registryDependencies` (full `wmzy/haze-ui/<item>` addresses, since plain
-names would resolve against the official shadcn registry).
-
-Every **styled** export is covered (107 component items — one per CSS
-family, so compound components like `tabs` arrive as `Tabs`/`TabList`/
-`Tab`/`TabPanel` together). What lands in your project is a thin
-**wrapper** file under `components/ui/haze/` that re-exports the
-component from `haze-ui` and imports its stylesheet — not vendored
-source. The wrapper is your customization layer (fork it, wrap it,
-restyle it), while `haze-ui` itself is installed as a normal npm
-dependency and keeps updating through your package manager. Common items:
-`button`, `input`, `select`, `dialog`, `tabs`, `toast`, `sidebar`,
-`form`, `data-table`, `chart`, `chat-message`, plus `tokens` (the theme
-classes) and `haze-tokens` (a token onboarding guide doc). Each item also
-carries `docs` (markdown usage — description, install command, theme
-activation — printed by `shadcn view`) and `categories` (kebab-case tags
-— `form`, `overlay`, `data-display`, `agent`, … — used by registry
-search/filter tooling). See [registry/README.md](./registry/README.md)
-for the full picture.
-
-### React 19+ by design
-
-The peer range is `react: ^19.0.0` on purpose — haze-ui is built on
-modern React rather than carrying a compatibility layer for 18:
-
-- **`ref` as a prop.** React 19 passes `ref` to function components
-  directly, so components that expose refs accept one prop instead of a
-  `forwardRef` wrapper layer.
-- **A modern-platform baseline.** Floating panels (Popover, DropdownMenu,
-  Tooltip, ContextMenu, Combobox, Datepicker) choose between three tiers
-  by feature detection — native `popover` + CSS anchor positioning,
-  `popover` alone, or a JS fallback — with the newest platform features
-  as the primary path, not an enhancement layered on top.
-- **`ControlOrValue<T>`** — the `Control<T> | T` state protocol — is
-  designed for modern React semantics throughout.
-
-On React 18? Upgrade first. haze-ui ships no React 18 compatibility
-layer, and none is planned.
-
-#### Migrating from React 18
-
-Once the app itself is on React 19, run through the haze-ui-relevant
-checklist:
-
-- **`ref` is a prop.** React 19 passes `ref` to function components
-  directly — drop any `forwardRef` wrapper you had around haze components
-  and pass `ref` like any other prop.
-- **No `defaultValue` dual track.** Stateful components speak
-  `ControlOrValue<T>` (`checked?: Control<T> | boolean`): one prop covers
-  controlled *and* uncontrolled usage, so there is no
-  `defaultChecked`/`defaultValue` pair to migrate. Where you used to pass
-  `defaultValue`, pass the plain value (uncontrolled) or switch to
-  controlled with `onChange`.
-- **Floating panels assume the modern-platform baseline.** Popover,
-  DropdownMenu, Tooltip, ContextMenu, Combobox and Datepicker
-  feature-detect between native `popover` + CSS anchor positioning,
-  `popover` alone, or a JS fallback — no polyfills to carry over from
-  your React 18 setup, but the floor from [Browser support](#browser-support)
-  applies.
-- **Colors are OKLCH with runtime-derived interaction states.** Requires
-  Chrome/Edge 119+, Safari 16.4+ or Firefox 128+; no HSL/hex fallbacks
-  are shipped.
-- **`'use client'` is pre-injected on interactive modules.** Every
-  stateful module in `dist/` starts with the directive; the static,
-  hook-free set (tokens and presentational components) ships without it
-  so those render as React Server Components (see
-  [Server Components](#server-components-nextjs-app-router)).
-
-### Dependencies
-
-haze-ui declares only the host environment as peers: `react` and
-`react-dom` (^19). Everything else is a regular dependency — one
-`npm i haze-ui` and every component works:
-
-- `react-use-control` — the engine behind `ControlOrValue<T>`
-- `react-f0rm` (^1.3) — the form engine behind `FormItem`/`FormList`
-  (the same author's headless form store)
-- `@tanstack/react-table` — DataTable
-- `recharts` — Chart
-- `@dnd-kit/core` / `@dnd-kit/sortable` / `@dnd-kit/utilities` — the
-  sortable TagInput/TagGroup variants
-- `qrcode` — QRCode
-
-Swapping any of these engines for another library is invisible to your
-code (the one deliberate exception: DataTable's column API exposes
-TanStack's `ColumnDef` types). The dist is ESM with `preserveModules`
-and side-effect-free JS, and engines are imported only by the components
-that need them, so bundlers (Next.js, Vite, webpack, Turbopack, Rollup)
-tree-shake the unused re-export chains: `import { Button } from
-'haze-ui'` never pulls `@tanstack/react-table` into the bundle. Engines
-install as regular dependencies, so even bundler-less consumers (bare
-Node ESM importing the barrel, which links the module graph eagerly)
-work with zero manual installs; the `haze-ui/components/DataTable` and
-`haze-ui/components/Chart` subpaths bypass the barrel entirely.
-
-### Browser support
-
-Since v1.13, haze-ui colors are generated in **OKLCH**, with interaction
-states (hover/active/subtle/focus-ring) derived at runtime via CSS relative
-color syntax. This requires Chrome/Edge 119+, Safari 16.4+, or Firefox 128+;
-no HSL/hex fallbacks are shipped.
-
-### Usage
-
-Import the component and its CSS. Two CSS loading modes:
+Load the CSS — pick one of two modes:
 
 ```jsx
-// Full stylesheet (simplest, ~12kB gzipped)
+// A) one full stylesheet (simplest)
 import 'haze-ui/styles.css';
-import { lightTheme, spacing, typography, Button } from 'haze-ui';
-
-// …or per-component CSS (pay only for what you render).
-// Always load tokens.css once, then each component you use:
-import 'haze-ui/css/tokens.css';
-import 'haze-ui/css/button.css';
-import { Button } from 'haze-ui';
-
-// …or zero CSS imports at all — the official Vite plugin injects the
-// right per-component CSS for you (see "Automatic CSS with haze-ui-vite"):
-// vite.config.ts → hazeCss() from 'haze-ui-vite'
-import { Button } from 'haze-ui';
-
-export default function MyComponent() {
-  return <Button>Start</Button>;
-}
 ```
 
-#### Automatic CSS with haze-ui-vite
-
-[`haze-ui-vite`](https://www.npmjs.com/package/haze-ui-vite) is the
-official companion Vite plugin: it scans each module's named imports from
-`haze-ui` (`import { Button, Select } from 'haze-ui'`), maps them through
-`haze-ui/css-manifest.json`, and prepends the matching
-`haze-ui/css/*.css` side-effect imports — `tokens.css` always first. CSS
-enters the module graph exactly where it's consumed, so code-split views
-carry only their own component CSS and HMR works through Vite's native
-pipeline.
-
 ```ts
-// vite.config.ts
+// B) the official Vite plugin injects per-component CSS automatically
+//    vite.config.ts
 import hazeCss from 'haze-ui-vite';
 
-export default {
-  plugins: [react(), hazeCss()],
-};
-```
-
-It reads the manifest shipped by your installed haze-ui version (no
-hardcoded name mapping), validates every injected file exists in the
-actual package, and warns on namespace imports it cannot collect. Works
-with Vite 5–8, zero runtime dependencies. Not on Vite? Keep the explicit
-imports above, or read `haze-ui/css-manifest.json` from your own bundler
-tooling — it's the same data the plugin uses.
-
-Component CSS files are kebab-case versions of the component name
-(`OTPInput` → `haze-ui/css/otp-input.css`). Per-component files only
-cover that component's rules — tokens (themes, spacing, typography)
-always come from `haze-ui/css/tokens.css`.
-
-Don't hardcode that kebab-case rule in tooling: sub-components and cores
-share their directory's family file (`InputCore` → `input.css`,
-`ButtonLink` → `button.css`, `Title`/`Text` → `typography.css`). The
-authoritative export → css-file mapping ships as data:
-`haze-ui/css-manifest.json`, generated at build time by
-`scripts/split-css.mjs` from the actual CSS output (never hand-edited):
-
-```json
-{
-  "families": { "Button": "button", "ButtonLink": "button", "InputCore": "input", "useToast": "toast" },
-  "noCss": ["COMPONENT_TOKENS", "TOKEN_REGISTRY", "useControl", "useTitle"]
-}
-```
-
-`families` covers every named export that has styles (family absorption
-included); `noCss` lists pure-logic exports with no css of their own.
-Bundler plugins and codemods should read this manifest instead of
-re-deriving file names — the mapping changes in lockstep with the build.
-The official [`haze-ui-vite`](https://www.npmjs.com/package/haze-ui-vite)
-plugin (above) is the reference consumer of this data.
-
-#### Styling & overriding (the `@layer haze` contract)
-
-All shipped CSS lives inside **`@layer haze`**, so your own *unlayered*
-styles beat every library rule regardless of source order or
-specificity — no `!important`, no selector wrestling:
-
-```css
-/* your stylesheet, plain CSS — always wins over the library */
-[data-slot='button'] {
-  letter-spacing: 0.02em;
-}
-```
-
-Every element a component renders carries a stable **`data-slot`**
-attribute (`data-slot='button'`, `'label'`, `'panel'`, `'menu-item'`,
-…). It is the official override surface: the attribute set is enforced
-by a coverage test, so it cannot silently drift between releases. The
-cascade is intentional — prefer, in order:
-
-1. **tokens** — `var(--haze-color-primary)` and friends re-derive whole
-   interaction-state families at runtime; per-component
-   `--haze-button-*` variables retheme one family;
-2. **`ConfigProvider` defaults** — app-wide per-component prop defaults
-   (and `classNames` where the component exposes slots);
-3. **`data-slot` CSS targeting** — structural overrides (the escape
-   hatch above);
-4. **`className` / `classNames`** — per-instance overrides, reserved
-   for one-offs.
-
-If your own framework ships layered styles too, declare order explicitly
-(e.g. `@layer haze, app;`) to keep the last word.
-
-### Server Components (Next.js App Router)
-
-Interactive modules in `dist/` carry the `'use client'` directive,
-injected at build time — the same convention Radix, Base UI and React
-Aria ship. In an App Router project you import haze-ui straight from
-your client components; there is no need for a wrapper module that
-re-exports the library under its own `'use client'` banner:
-
-```jsx
-// any client component — import straight from the package
-import { Button } from 'haze-ui';
-
-export function Actions() {
-  return <Button>Start</Button>;
-}
-```
-
-**A static subset renders as React Server Components.** Modules with no
-hooks and no DOM access ship *without* the directive, so they can be
-imported directly into server components and cost zero client JS:
-
-- tokens: everything on the `haze-ui/tokens` subpath (`lightTheme`,
-  `darkTheme`, `spacing`, `typography`, `TOKEN_REGISTRY`, OKLCH utils)
-- components: `AspectRatio`, `Badge`, `Card`, `CodeBlock`, `Container`,
-  `Divider`, `Flex`, `Grid`/`GridItem`, `Icon`, `Kbd`, `Skeleton`,
-  `Stat`/`StatGroup`, `Typography` (`Title`/`Text`/`Paragraph`)
-
-Import them from the subpath (`import { Badge } from
-'haze-ui/components/Badge'`) or the barrel — in an RSC module the
-bundler resolves the module itself, not the client-marked barrel shell.
-The emitted markup carries the usual Linaria class names, so CSS loading
-is unchanged (`haze-ui/styles.css` or the `css/*` subpaths). The safe
-list lives in `scripts/rsc-safe.mjs` and is enforced by
-`src/lib/dist-esm-contract.test.ts` (including a transitive-closure
-check: every static import inside a safe module must itself be safe) —
-new components only join the list when they stay hook-free.
-
-CSS loading is unchanged from the two modes above — `haze-ui/styles.css`
-in the root layout, or the `haze-ui/css/*` subpaths. A runnable Next.js
-15 project lives in [`examples/nextjs`](./examples/nextjs).
-
-## ButtonLink: a real anchor with the Button skin
-
-Navigation that must look like a button should still *be* a link —
-rendering `as={Button}` drops `href` onto a `<button>` (an invalid
-attribute: no ⌘/middle-click new tab, nothing for crawlers or no-JS).
-`ButtonLink` renders a native `<a>` wearing Button's full appearance —
-same `variant`/`size`/`square` props, same hover/active/focus and
-disabled visual states:
-
-```jsx
-import { ButtonLink } from 'haze-ui';
-
-<ButtonLink href='/page/2' variant='outline'>Next page</ButtonLink>
-
-// anchors have no `disabled` attribute — report the state with
-// aria-disabled (+ tabIndex={-1} to leave the focus order); ButtonLink
-// styles it exactly like Button's :disabled
-<ButtonLink href='/prev' aria-disabled tabIndex={-1}>← Previous</ButtonLink>
-```
-
-Everything else extends the native `<a>` attributes and is spread onto
-the anchor (`target`, `rel`, `download`, `aria-*`, …), with the ref
-forwarded — the same composition shape `NavLink` uses, so routers can
-swap their own Link element through an `as` prop:
-
-```jsx
-// with a typed router Link (href + SPA onClick injected by the router):
-<TypedLink to='/articles' search={{offset: 20}} as={ButtonLink}>
-  Next page
-</TypedLink>
-```
-
-Both components share one skin (a styles module), so a theme tweak to
-`Button` re-skins `ButtonLink` in lockstep. CSS: `haze-ui/css/button.css`
-covers both.
-
-## AsyncSection: loading / error / content in one place
-
-`AsyncSection` collapses the three states every async view hand-rolls into
-one component: `loading` renders the spinner placeholder, a non-null
-`error` renders an alert box with an optional `Retry` button (an `Error`
-instance contributes its `message`; `errorText` overrides), and otherwise
-the children render. `loading` wins when both are set — the retry path
-(loading again before the old error clears) shows the placeholder, not
-the stale error. All copy is configurable; the retry button only renders
-when `onRetry` is provided.
-
-```jsx
-import 'haze-ui/css/tokens.css';
-import 'haze-ui/css/async-section.css';
-import { AsyncSection } from 'haze-ui';
-
-<AsyncSection loading={loading} error={error} onRetry={refetch}>
-  {data}
-</AsyncSection>
-```
-
-## useTitle: view-level document.title
-
-`useTitle(title)` sets `document.title` while the view is mounted and
-restores the pre-entry title (the static `<title>` from the host page) on
-unmount. Two timing pitfalls are baked into the implementation: the write
-and the restore are two separate effects (a single `[title]` effect would
-restore the *previous round's* title, not the entry default, on every prop
-change), and the entry snapshot is taken at effect time, not render time —
-a route swap is one commit, so at render time the old view's cleanup has
-not run yet and `document.title` still holds the previous page.
-
-```jsx
-import { useTitle } from 'haze-ui';
-
-function SettingsView() {
-  useTitle('Settings');
-  // ...
-}
-```
-
-## Anchor: scroll-spy navigation
-
-Sticky anchor navigation with an IntersectionObserver scroll-spy (a
-scroll-listener fallback covers engines without IO). Pass `items`, and
-the highlighted section is a controllable state like everything else —
-`activeId?: ControlOrValue<string>`. Clicks scroll the container
-(`getContainer` defaults to the window) with an `offsetTop` adjustment,
-and the active link carries `aria-current="true"`.
-
-```jsx
-import 'haze-ui/css/tokens.css';
-import 'haze-ui/css/anchor.css';
-import { Anchor } from 'haze-ui';
-
-<Anchor items={[{ id: 'intro', label: 'Intro' }, { id: 'api', label: 'API' }]} />;
-```
-
-## Watermark: tiled canvas watermark
-
-A canvas-tiled watermark layer: text rows (`content: string | string[]`)
-rendered onto an off-screen tile (rotated, `gap`-spaced,
-device-pixel-ratio aware) and repeated as a background over the
-container — or the whole viewport with `fullscreen`. Default color
-follows the theme's `--haze-color-text-muted`; the layer is
-`pointer-events: none` and `aria-hidden`, and engines without a canvas
-2d context degrade to no watermark rather than crashing.
-
-```jsx
-<Watermark content="CONFIDENTIAL" rotate={-22}>
-  <Report />
-</Watermark>
-```
-
-## Fullscreen: wrap-mode fullscreen binding
-
-`useFullscreen(target?)` returns `[isFullscreen, toggle, handle]` — the
-Fullscreen API wired to `ControlOrValue` semantics: `Fullscreen`
-wraps a single trigger child (its `onClick` is preserved and composed)
-and exposes `fullscreen?: ControlOrValue<boolean>`, so browser-side
-exits (Esc, OS gestures) write back through the control and fire
-`onChange` exactly once.
-
-```jsx
-const [fs, setFs, fsCtrl] = useControl(undefined, false);
-<Fullscreen fullscreen={fsCtrl} onChange={setFs}>
-  <Button>Enter focus mode</Button>
-</Fullscreen>
-```
-
-## Utility hooks
-
-All hooks ship on the main barrel (no separate import path) and follow
-the same conventions as the components: `ControlOrValue` where state is
-user-controllable, SSR/jsdom-safe when the underlying API is missing.
-
-| Hook | Returns | Notes |
-| --- | --- | --- |
-| `useClipboard(resetMs?)` | `{ copied, copy }` | `copied` resets after `resetMs` |
-| `useDebouncedCallback(fn, delayMs)` | debounced `fn` | Stable identity across renders |
-| `useDebouncedValue(value, delayMs)` | `T` | Trails the input by `delayMs` |
-| `useFullscreen(target?)` | `[isFullscreen, toggle, handle]` | See section above |
-| `useHotkeys(map, options?)` | — | `'mod+s'`-style specs (`mod` normalizes to ⌘ on macOS, Ctrl elsewhere); skips events from editable targets unless `allowInInput`; `hotkey(...keys)` builds specs type-safely |
-| `useInView(options?)` | `[refCallback, inView]` | IntersectionObserver; `once` freezes after the first hit; `false` forever when the API is missing (SSR) |
-| `useLocalStorage(key, control?, initial?)` | `[value, setValue]` | `ControlOrValue` semantics, cross-tab `storage` sync, corrupt JSON self-heals to `initial` |
-| `useSessionStorage(key, control?, initial?)` | `[value, setValue]` | Same kernel, `sessionStorage` scope |
-| `useMediaQuery(query)` | `boolean` | Reactive `matchMedia`; `false` when missing |
-| `usePrefersReducedMotion()` | `boolean` | Token-aware animation gating |
-| `useTitle(title)` | — | Document title while mounted |
-| `useToast()` | toast API | Requires a `ToastContainer` ancestor |
-
-## Sortable tags and chips
-
-Drag reordering is an opt-in variant: `SortableTagInput` /
-`SortableTagInputCore` and `SortableTagGroup` statically import
-`@dnd-kit/core` / `@dnd-kit/sortable` / `@dnd-kit/utilities` (regular
-dependencies — the plain `TagInput`/`TagGroup` never touch them, so they
-stay out of every bundle that doesn't import a Sortable variant).
-`SortableTagInput` writes the new array through `onChange`;
-`SortableTagGroup` reports `onReorder(nextOrder)` (the new arrangement of
-original child indexes) and leaves re-rendering to the parent. Sorting is
-keyboard-complete: focus a tag, `Space` to lift, arrows to move, `Space`
-to drop, `Escape` to cancel.
-
-## Imperative overlay handles
-
-`Dialog`, `Drawer`, `BottomSheet`, `Popover` and `DropdownMenu` accept a
-`ref` (React 19 style — no `forwardRef`) exposing
-`{ open(), close(), focusTrigger() }`. The methods drive the same state
-outset as user interaction — `Dialog`'s `close()` goes through the
-native `close` event path so `onClose` and focus restoration fire
-exactly once — and they honor controlled mode, writing through the
-control.
-
-```tsx
-const dialog = useRef<DialogHandle>(null);
-<Dialog ref={dialog} …>…</Dialog>;
-<button onClick={() => dialog.current?.open()}>Show</button>;
-```
-
-## View Transitions on modals (opt-in)
-
-`Dialog`, `Drawer` and `BottomSheet` accept `viewTransition?: boolean`
-(default `false`). When enabled, their open/close state flips are wrapped
-in `document.startViewTransition(() => flushSync(...))` — the synchronous
-DOM-update pattern React requires — so modals animate through the native
-View Transitions API alongside their regular enter/exit animations. The
-transition itself degrades to a plain state flip when the engine lacks
-`startViewTransition` or the user prefers reduced motion; transition
-appearance is yours to style via `::view-transition-*`. Controlled
-consumers' own flips happen outside the component and are intentionally
-not wrapped.
-
-## Design tokens export (Figma)
-
-`toDesignTokens()` converts the token registry into a [W3C Design Tokens](https://tr.designtokens.org/) JSON file — grouped by category (`color` / `font` / `spacing` / `dimension` / `shadow`), each token carrying a W3C `$type` and the source CSS variable in `$extensions['haze-ui.css-var']`, with `$value` being the resolved value of the chosen theme (`light` by default). The Theme Editor ships a one-click entry: the **Export W3C tokens (.json)** button in the toolbar downloads the file for the mode currently being edited, live edits included. The exported file can be imported directly into Figma Tokens / Tokens Studio.
-
-```json
-{
-  "color": {
-    "color-primary": {
-      "$value": "oklch(0.563 0.241 260.8)",
-      "$type": "color",
-      "$extensions": { "haze-ui.css-var": "--haze-color-primary" }
-    }
-  },
-  "spacing": {
-    "space-2": {
-      "$value": "8px",
-      "$type": "dimension",
-      "$extensions": { "haze-ui.css-var": "--haze-space-2" }
-    }
-  }
-}
-```
-
-## Brand themes: presets, runtime generation, CLI
-
-Five preset brand themes ship as complete theme classes — `violetTheme`,
-`tealTheme`, `cyanTheme`, `orangeTheme`, `roseTheme` — each a drop-in
-replacement for `lightTheme`/`darkTheme` with primary/info/focus-ring
-rerouted to the brand's scale.
-
-**Runtime custom brands.** `createBrandTheme` (from `haze-ui` or
-`haze-ui/tokens`) runs the exact preset pipeline from your own seed hex:
-
-```ts
-import { createBrandTheme } from 'haze-ui/tokens';
-
-const brand = createBrandTheme({
-  name: 'acme',       // → --haze-acme-1…12 (lowercase kebab; not gray/green/amber/red)
-  light: '#0066ff',   // light-mode primary seed (scale step 9)
-  dark: '#0a3d99',    // optional — derived from light (oklch l +0.2) when omitted
-  overrides: { light: { 10: '#0052cc' } },  // optional extra anchors
-});
-// brand.light / brand.dark: bare declaration blocks — wrap in classes once:
-// styleEl.textContent = `.acme-light { ${brand.light} }\n.acme-dark { ${brand.dark} }`;
-```
-
-The blocks are theme *replacements* (never stack on `lightTheme`), and you
-own contrast: pick a light seed dark enough for white text — the presets'
-step-9 anchors sit near Tailwind's 600/700 range for that reason.
-
-**CLI.** Zero Node dependencies, identical output:
-
-```bash
-npx haze-ui-theme --primary '#0066ff' [--dark '#0a3d99'] [--name brand] [--out brand.css]
-```
-
-**W3C design-token archives.** Every preset is also exported per mode as
-W3C DTF JSON:
-
-```js
-import violetLight from 'haze-ui/design-tokens/violet/light.json';
-```
-
-## Component-level tokens
-
-Global `--haze-*` tokens theme the whole system; **component-level tokens**
-theme one component family without touching anything else. They are plain
-CSS custom properties consumed through a fallback chain baked into the
-component's own stylesheet:
-
-```css
-/* inside haze-ui/css/button.css */
-height: var(--haze-button-height-md, auto);
-```
-
-The library never defines these variables — nothing to register, no
-runtime. When you set one on `:root` or any ancestor of the component, your
-value wins; when you don't, the built-in fallback applies and the component
-looks exactly as shipped. Scoping is ordinary CSS inheritance: set the
-variable on a wrapper element to retheme only that subtree.
-
-`Button`/`ButtonLink` (pilot — they share one skin, so both change
-together; `Toggle` and the Toolbar items wearing the same skin follow
-along):
-
-| Token                              | Fallback (default look) |
-| ---------------------------------- | ----------------------- |
-| `--haze-button-height-sm/md/lg`    | `auto` (content-driven) |
-| `--haze-button-font-size-sm/md`    | `var(--haze-text-sm)`   |
-| `--haze-button-font-size-lg`       | `var(--haze-text-base)` |
-| `--haze-button-radius`             | `var(--haze-radius-md)` |
-
-`Dialog`:
-
-| Token                            | Fallback (default look)  |
-| -------------------------------- | ------------------------ |
-| `--haze-dialog-width`            | `480px` (on `max-width`) |
-| `--haze-dialog-radius`           | `var(--haze-radius-xl)`  |
-| `--haze-dialog-padding`          | `var(--haze-space-6)`    |
-| `--haze-dialog-title-gap`        | `var(--haze-space-4)`    |
-| `--haze-dialog-title-font-size`  | `var(--haze-text-lg)`    |
-
-```css
-/* app-wide denser buttons; every other component keeps its sizing */
-:root {
-  --haze-button-height-md: 32px;
-}
-
-/* only dialogs inside this subtree get wider */
-.wide-dialogs {
-  --haze-dialog-width: 720px;
-}
-```
-
-`COMPONENT_TOKENS` (exported from `haze-ui` and `haze-ui/tokens`) lists
-each component's component-level tokens alongside the global tokens it
-consumes.
-
-## AI-friendly distribution
-
-**llms.txt** — a markdown overview of the whole library (the `ControlOrValue<T>`
-state protocol, both CSS loading modes, all 107 components grouped with one-line
-purposes, the token system, the floating-overlay tiers, form integration) written
-for AI coding tools and crawlers. It lives at the repo root
-([llms.txt](./llms.txt)) and, on the docs site, at
-<https://wmzy.github.io/haze-ui/llms.txt> (`build:demo` copies it into `dist/`).
-
-**registry.json** — an agent-installable registry shipped as the
-`haze-ui/registry.json` npm artifact (regenerated by
-`scripts/generate-registry.mjs` on every build), also reachable at
-<https://unpkg.com/haze-ui/registry.json>. Point any registry-aware
-tooling at it — the shadcn CLI works:
-
-```sh
-pnpm dlx shadcn@latest add https://unpkg.com/haze-ui/registry.json
-```
-
-Every item is a **wrapper file, not vendored source**: it re-exports the
-component from the published haze-ui npm package and imports its
-stylesheet, so `haze-ui` stays a normal npm dependency that keeps
-updating underneath — the shadcn CLI is only the distribution channel.
-That is the point: AI coding agents (and anyone who wants a fast setup
-while keeping the npm update path) get working imports in one step,
-without the copy-paste expectation of owning pasted source. When you
-want different styles or behavior, fork the generated wrapper file — it
-is your customization layer, not a source drop. Coverage: **every styled
-export** (107 css families / 185 components), generated from the build's
-own css manifest. The same items are also installable straight from this
-GitHub repository — see
-[Install via shadcn CLI (GitHub registry)](#install-via-shadcn-cli-github-registry).
-
-## AI / MCP
-
-**`haze-ui-mcp`** — an [MCP server](https://modelcontextprotocol.io) that puts the
-whole component reference in your AI coding agent's tool belt. It serves the
-same docs the site renders (props tables with types/defaults/descriptions,
-import statements, CSS paths, peer deps, the full token registry), so the
-agent never guesses a prop name or a stylesheet path again:
-
-| Tool | What it returns |
-| --- | --- |
-| `haze_list_components` | Every component with its css family |
-| `haze_get_component` | One component's full reference — props tables, import statement, CSS imports. Name matching is case-insensitive and accepts kebab-case (`data-table`) or PascalCase (`DataTable`) |
-| `haze_get_tokens` | The `--haze-*` token registry with light and dark values, optionally filtered by category (`color`, `typography`, `spacing`, `radius`, `shadow`) |
-| `haze_search_docs` | Top-10 ranked matches across component names, css families, prop names and descriptions |
-
-**Claude Code**:
-
-```sh
-claude mcp add haze-ui -- npx haze-ui-mcp
-```
-
-**Cursor** (`.cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "haze-ui": {
-      "command": "npx",
-      "args": ["haze-ui-mcp"]
-    }
-  }
-}
-```
-
-The server speaks stdio JSON-RPC and ships its own docs snapshot
-(`dist/mcp-docs.json`, regenerated on every build by
-`scripts/generate-mcp-docs.mjs`) — no project access, no indexing on startup.
-In this repository you can run it directly against the local snapshot:
-
-```sh
-node scripts/generate-mcp-docs.mjs
-node mcp/index.mjs
-```
-
-Point it at a custom snapshot with `HAZE_UI_MCP_DOCS=/path/to/mcp-docs.json`.
-
-## AI runtime integration (Vercel AI SDK `useChat`)
-
-haze-ui ships the agent chat surface as **presentational** components —
-`ChatContainer` (scrolling), `ChatMessage` (bubbles), `StreamingText`
-(typewriter reveal), `ToolCallCard` (tool input/output), `ThinkingIndicator`
-(waiting dots), `ChatInput` (composer) — with no opinion about where
-messages come from. The Vercel AI SDK's `useChat` is the stateful half: it
-owns `messages` (a `UIMessage[]` of typed `parts`), `status`
-(`submitted | streaming | ready | error`) and the `sendMessage`/`stop`
-pair. One small adapter bridges them — pure functions over duck-typed
-shapes, so the `ai` package never enters your dependency tree through
-haze-ui:
-
-```tsx
-import { useChat } from '@ai-sdk/react';
-import { DefaultChatTransport } from 'ai';
-import { Button, ChatContainer, ChatInput } from 'haze-ui';
-
-import { useHazeChat } from './ai-chat-adapter'; // the recipe module
-
-function SupportChat() {
-  const chat = useChat({ transport: new DefaultChatTransport({ api: '/api/chat' }) });
-  const { messages, busy, send, stop } = useHazeChat(chat);
-
-  return (
-    <div>
-      <ChatContainer>{messages}</ChatContainer>
-      <ChatInput disabled={busy} onSend={send} />
-      {busy && <Button variant='outline' onClick={stop}>Stop</Button>}
-    </div>
-  );
-}
-```
-
-The mapping rules: text parts → `ChatMessage` bubbles (`StreamingText`
-typewriter while a part streams), reasoning → `ThinkingIndicator` then a
-collapsible transcript, `tool-*` parts → `ToolCallCard` driven by v5
-`states` (with v4 `tool-call`/`tool-result` pairs folded into one card by
-`toolCallId`), sources → links; `status: submitted` → thinking dots before
-the first token, `error` → a system bubble with the transport error. The
-whole thing is one small, unit-tested module that never throws on odd
-payloads — unknown part types are skipped, so future SDK parts degrade
-instead of crashing.
-
-The full recipe — live runnable demo (same adapter over a mock streaming
-source, no network), the complete adapter source, the `useHazeChat` hook,
-per-part mapping table and known limits (attachments, branching, voice out
-of scope; `StreamingText` restart-on-grow caveat for char-by-char
-transports) — lives on the docs site:
-**<https://wmzy.github.io/haze-ui/recipes>**.
-
-## Headless primitives
-
-The behavior layer the styled components are built on ships as its own
-subpath: `haze-ui/headless`. Component authors assembling their own panels
-get the same primitives Popover, DropdownMenu and Tooltip use internally —
-with the same version, no re-implementation:
-
-- `useFloating` — the three-tier floating engine (native `popover` + CSS
-  anchor positioning → `popover` alone → JS fallback), plus
-  `placeFloatingPanel`, `useFloatingPosition` and the placement/panel types
-- `Presence` — mount/unmount with exit animations
-- `useFocusScope` / `isTabbable` / `getTabbables` — focus trapping and
-  tab-order queries
-- `computeFloatingPosition` — the flip/shift collision math as a pure
-  function
-
-```jsx
-import { useFloating, Presence } from 'haze-ui/headless';
-```
-
-Stable public API — same semver commitment as the component library:
-breaking changes land only on a major version.
-
-## react-f0rm Integration
-
-react-f0rm owns form field state, and its headless `useField` hook is
-the single binding layer — the same channel its built-in
-`Field`/`Checkbox`/`Select` components use. haze-ui contributes the
-views: controlled cores (`InputCore`, `SelectCore`, `SwitchCore`, `TextareaCore`,
-`TagInputCore`, `TransferCore`, `UploadCore`, ...) take the plain `{value, onChange}`
-pair with zero adapters, and `FormItem` wraps the hook's state in label,
-error and aria wiring. The sugar components (`Input`, `Select`, ...)
-keep their `ControlOrValue<T>` (`Control<T> | T`) API for standalone use outside forms.
-
-Beyond `FormItem`, the `haze-ui` barrel re-exports the whole form layer
-so consumers never import react-f0rm directly: `FormList` (array fields
-over `useFieldArray` — append/prepend/insert/remove/swap/move with
-stable row keys), `FormProvider`/`useFormContext` (`FormItem`/`FormList`
-fall back to context when the `form` prop is omitted), the imperative
-APIs (`setValue`, `getValue`, `reset`, `trigger`, `setFocus`,
-`setServerErrors`, `useWatch`, ...), and schema resolvers:
-
-```jsx
-import { FormItem, FormList, zodResolver, standardSchemaResolver } from 'haze-ui';
-```
-
-`zodResolver` adapts any zod schema (v4) as a field validator;
-`standardSchemaResolver` adapts any Standard Schema v1 implementation
-(zod, valibot, arktype, ...) the same way. Field controls forward refs
-to their focusable element and `FormItem` wires f0rm's `focusRef`
-channel, so `setFocus(form, 'name')` and a failed submit's
-first-error auto-focus land on the real input.
-
-### useField: field → {value, onChange}
-
-```jsx
-import { useForm, useField } from 'react-f0rm';
-import { InputCore } from 'haze-ui';
-
-function NameField({ form }) {
-  const { value, onChange } = useField({ form, name: 'name' });
-  return <InputCore value={value} onChange={onChange} />; // two-way bound
-}
+export default { plugins: [react(), hazeCss()] };
 ```
 
-The hook subscribes to the field (sibling fields stay isolated), and
-`onChange` writes through react-f0rm's user-change channel — a write
-fires exactly the validation a user typing into the field would fire:
-the field's effective `mode` (a `FormItem`/`useField` per-field override
-included) and the form's `reValidateMode`. With the default
-`mode: 'onSubmit'` + `reValidateMode: 'onChange'`, typing through a bound
-core after a failed submit re-validates per keystroke and clears the
-error as soon as the value is valid — no blur, no resubmit. `onChange`
-accepts plain values only (controlled cores emit the next value, never
-functional updaters; read the previous value from `value` on the next
-render). `reset(form, newValues)` re-seeds every binding with no
-remounting.
-
-### FormItem: label, errors and aria wiring
+Then render your first component:
 
 ```jsx
-import { Form, useForm } from 'react-f0rm';
-import { FormItem, InputCore } from 'haze-ui';
+import { lightTheme, Button } from 'haze-ui';
 
-function ProfileForm() {
-  const form = useForm({ initialValues: { email: '' } });
+export function App() {
   return (
-    <Form form={form} onSubmit={...}>
-      <FormItem
-        form={form}
-        name="email"
-        label="Email"
-        validate={(v) => (v.includes('@') ? undefined : 'must be an email')}
-      >
-        {({ id, errorId, invalid, value, onChange }) => (
-          <InputCore id={id} value={value} onChange={onChange} aria-invalid={invalid} aria-describedby={errorId} />
-        )}
-      </FormItem>
-    </Form>
+    <main className={lightTheme}>
+      <Button onClick={() => console.log('haze!')}>Start</Button>
+    </main>
   );
 }
 ```
 
-`FormItem` generates the field/error ids, renders `<label htmlFor>`, and
-surfaces the first error in a `role="alert"` element — no manual
-`FieldError` wiring.
-
-#### `as`: declarative binding (react-f0rm Field-style)
-
-Skip the render-prop: pass any component as `as` and `FormItem` wires the
-id, aria attributes, `onBlur` and `onChange` itself — the same props shape
-as react-f0rm's `Field`, not Radix's `asChild`. `as` and the children
-render-prop are mutually exclusive.
-
-```jsx
-// text field: nothing else to wire
-<FormItem form={form} name="email" label="Email" as={InputCore} />
-
-// checkbox-style control: value lives in `checked`
-<FormItem
-  form={form}
-  name="subscribed"
-  label="Subscribe"
-  as={CheckboxCore}
-  valueToProps={(checked) => ({ checked: !!checked })}
-/>
-
-// DOM-element-shaped control: adapt event and value in one line each
-<FormItem
-  form={form}
-  name="email"
-  as={NativeInput}
-  eventToValue={(e) => e.target.value}
-  renderError={(error, id) => <em id={id}>{error}</em>}
-/>
-```
-
-- `eventToValue` defaults to identity — haze cores' `onChange` emits the
-  next plain value; pass `(e) => e.target.value` when `as` is a raw DOM
-  element component.
-- `asProps` spreads extra props onto the control before the value props,
-  so `value`/`valueToProps` win conflicts (Field.tsx precedence).
-- `renderError(error, id)` replaces the built-in error span's content;
-  the span itself (`id`, `role="alert"`, styling) stays FormItem's.
-- With a typed form, `validate`'s value argument is the field's actual
-  type (`PathValueOf<TValues, P>`), not `any`.
-
-#### `input`: declarative binding for cores and raw DOM controls (typed prop forwarding)
-
-The ergonomic form for the controlled cores — pass the component and the
-rest of the JSX goes straight to it, type-checked against its own props:
-
-```jsx
-<FormItem
-  form={form}
-  name="email"
-  label="Email"
-  input={InputCore}
-  placeholder="you@x.dev"
-  mode="onBlur"
-  validate={(v) => (v.includes('@') ? undefined : 'must be an email')}
-/>
-
-// JSX children forward too — a SelectCore's options:
-<FormItem form={form} name="role" label="Role" input={SelectCore}>
-  <option value="admin">Admin</option>
-  <option value="viewer">Viewer</option>
-</FormItem>
-
-// checkbox-style controls keep the valueToProps adapter:
-<FormItem
-  form={form}
-  name="subscribed"
-  label="Subscribe"
-  input={CheckboxCore}
-  valueToProps={(checked) => ({ checked })}
-/>
-```
-
-`input` wires the same id/aria/`onBlur`/`onChange`/value contract as `as`
-— every haze core (`InputCore`, `TextareaCore`, `SelectCore`,
-`TagInputCore`, `TransferCore`, `UploadCore`, `CheckboxCore`, `SwitchCore`, …)
-speaks the plain `{value, onChange}` pair, so the default adapters need
-nothing (`TagInputCore`'s `onChange` already emits the next `string[]`;
-`TransferCore` emits the next `string[]` plus move metadata, `UploadCore`
-the next `File[]`; a checkbox-style core pairs with `valueToProps`). The
-differences from `as`:
-
-- Forwarded props are **type-checked against the core's own props** —
-  `input={InputCore} size="xl"` is a compile error, while `asProps` is an
-  untyped bag.
-- JSX **children** forward to the core (a `SelectCore`'s `<option>`s);
-  the render-prop children and `input` are mutually exclusive (a
-  render-prop next to `input` throws — it's a migration leftover).
-- The wiring (`id`, `aria-invalid`, `aria-describedby`, `onBlur`,
-  `onChange`, `value`/`checked`) and FormItem's own prop names are
-  **reserved**: they are excluded from the forwarded type and always win
-  at runtime. A control prop that collides with one (e.g. CheckboxCore's
-  own `label`) is unreachable through `input` — use the render-prop or
-  `as`/`asProps` for it.
-
-`input` also takes raw DOM bindings — no core required. The two raw
-forms are explicit about their `eventToValue` adapter, so the value
-channel is never guessed:
-
-```jsx
-// a native form element: the binding pairs the tag with its adapter,
-// and the rest of the JSX is type-checked against that element's own
-// HTML attributes (rows on a textarea, options as a select's children)
-<FormItem
-  form={form}
-  name="bio"
-  label="Bio"
-  input={{element: 'textarea', eventToValue: (e) => e.target.value}}
-  rows={4}
-/>
-
-// a DOM-element-shaped component: the top-level eventToValue is the
-// explicit opt-in from plain-value (core) to event-emitting (raw)
-<FormItem
-  form={form}
-  name="email"
-  label="Email"
-  input={NativeInput}
-  eventToValue={(e) => e.target.value}
-/>
-```
-
-- The element binding accepts `'input' | 'textarea' | 'select'` and
-  **requires** its `eventToValue` — `input={{element: 'input'}}` without
-  the adapter is a compile error (at runtime an untyped caller that
-  skips it still gets `e.target.value`, the DOM contract, never an Event
-  in the store).
-- The top-level `eventToValue` next to a component `input` switches that
-  binding to raw semantics, mirroring the `as` channel; forwarded props
-  still check against the component's own props.
-- The same reserved-prop rule applies: `id`, `onBlur`, `onChange`,
-  `value`/`checked`, aria-*, and FormItem's own names are never
-  forwarded on the raw channel either.
-
-#### `mode`: per-field validation timing (react-f0rm ≥ 0.6)
-
-Pass `mode` to validate one field on its own schedule instead of the
-form-wide validation mode — other fields are unaffected. It accepts
-react-f0rm's `ValidationMode` values: `'onSubmit'` (default form
-behavior), `'onBlur'`, `'onChange'`, `'onTouched'` or `'all'`. Omit it to
-keep the form's mode.
-
-```jsx
-<FormItem
-  form={form}
-  name="email"
-  label="Email"
-  mode="onBlur"
-  validate={(v) => (v.includes('@') ? undefined : 'must be an email')}
->
-  {({ id, errorId, invalid, onBlur, value, onChange }) => (
-    <InputCore
-      id={id}
-      value={value}
-      onChange={onChange}
-      aria-invalid={invalid}
-      aria-describedby={errorId}
-      onBlur={onBlur}
-    />
-  )}
-</FormItem>
-```
-
-With `mode="onBlur"` (and the binding's `onBlur` passed to the core, as
-above) the email field is validated the moment it loses focus — no
-submit needed. `mode` accepts `'onSubmit'`, `'onBlur'`, `'onChange'`,
-`'onTouched'` or `'all'`; only this field's schedule changes, the rest
-of the form keeps its own `mode`.
-
-#### `validateDebounce` / `delayError` / `rules` (react-f0rm ≥ 0.6)
-
-`FormItem` passes these field-level options straight through to
-react-f0rm's `useField`:
-
-- `validateDebounce={300}` — debounce this field's validation kicks:
-  only the last kick inside the window runs the validator (e.g. keeps a
-  per-keystroke async validator from firing while the user types fast).
-  While the timer is pending the field counts as validating, so
-  `trigger`/submit wait it out.
-- `delayError={500}` — delay *showing* a newly appearing error in the
-  rendered error span (and the binding's `invalid`/`errors`). The form's
-  error state stays immediate — submit and `getError` still gate on it.
-  An error that clears inside the window never shows.
-- `rules={{ required: 'Email is required', minLength: 4, pattern: { value: /@/, message: 'Must be an email' } }}`
-  — declarative constraints (a subset of react-hook-form's `register`
-  rules) compiled into a validator that runs *before* `validate`; both
-  sources' errors merge into the field's error list, rules errors ahead.
-
-```jsx
-<FormItem
-  form={form}
-  name="email"
-  label="Email"
-  validateDebounce={300}
-  delayError={500}
-  rules={{ required: 'Email is required' }}
-  validate={(v) => (v.includes('@') ? undefined : 'must be an email')}
->
-  {({ id, errorId, invalid, value, onChange }) => (
-    <InputCore id={id} value={value} onChange={onChange} aria-invalid={invalid} aria-describedby={errorId} />
-  )}
-</FormItem>
-```
-
-All three are optional; omit them and the field behaves exactly as
-before (immediate validation per the form's `mode`, immediate error
-display, `validate`-only).
-
-## Accessibility & RTL
-
-Accessibility is a baseline, not an opt-in: every component's test suite
-includes axe checks, and the token sheet ships a global
-`@media (prefers-reduced-motion: reduce)` block that collapses every
-animation duration token to `0ms` — motion-sensitive users get instant
-state changes with no per-component wiring.
-
-haze-ui supports RTL via CSS logical properties wherever a side is
-semantic (the *start/end* of reading flow), not just decorative. Set
-`dir="rtl"` (or `direction: rtl`) on an ancestor and those sides mirror
-automatically — no component props change. The same goes for keyboard
-semantics: horizontal arrow keys invert their meaning in RTL (Tabs,
-Rating, Slider, Carousel, Calendar, Toolbar, Cascader, Tour and
-horizontal menus), and floating placements are logical — a panel with
-`placement="bottom"` in an RTL document lands on the mirrored inline
-side without passing a mirrored placement. `src/lib/rtl.test.tsx` is a
-four-layer contract suite (rendering + axe, keyboard mirroring, floating
-mirroring, and a CSS-codemod guard with an explicit exemption list),
-backed by `e2e/rtl.spec.ts` cross-engine checks.
-
-`LocaleProvider` takes an optional `direction` prop (`'ltr' | 'rtl'`,
-explicit wins over derivation from the locale — Arabic, Hebrew, Farsi
-and friends are derived automatically) and feeds `useDirection()`, the
-hook components use internally. `getDirection(el)` (DOM resolution with
-`[dir]` fallback) and `localeDirection(locale)` are exported from the
-barrel alongside it, plus `createStrings(base, overrides)` — a
-`DeepPartial<HazeStrings>` deep-merge for deriving locale packs without
-forking a whole string table (see the *Adding a locale* recipe on the
-docs site).
-
-### Direction-responsive by construction (no physical CSS)
-
-- **Progress (bar)** — the fill is a normal-flow block with a percentage
-  `width`, so it grows from the inline-start edge (right in RTL) with no
-  `left`/`right` in its CSS.
-- **Slider** — a native `<input type="range">`; the browser mirrors fill
-  and thumb under `dir="rtl"`.
-- **Flex gap / `flex-direction: row`** — gap and row order follow the
-  writing mode, so icon-to-label spacing in Tag, ChatMessage, Alert, etc.
-  mirrors for free.
-- **Carousel track scrolling** — uses `scrollIntoView({ inline: 'start' })`,
-  a logical scroll position.
-
-### Fixed: physical → logical conversions
-
-| File | Change |
+The theme class activates the token set — that is the whole setup. Prefer a
+scaffolded start? `pnpm create haze-ui my-app` ships runnable Vite and
+Next.js App Router templates.
+
+Colors are generated in OKLCH with interaction states derived at runtime via
+CSS relative colors, so the browser floor is Chrome/Edge 119+, Safari 16.4+
+or Firefox 128+ (no HSL/hex fallbacks).
+
+## Highlights
+
+- **Accessibility as a release gate** — an axe case in every component test
+  suite, Playwright e2e across Chromium/Firefox/WebKit plus a phone-viewport
+  project, pixel-locked visual baselines, and a real VoiceOver smoke suite on
+  macOS CI.
+  → [Accessibility guide](https://wmzy.github.io/haze-ui/guides/a11y) ·
+  [A11y contracts](https://wmzy.github.io/haze-ui/guides/a11y-contracts)
+- **Per-component CSS** — the JS entry imports no stylesheet. Load the full
+  `haze-ui/styles.css`, cherry-pick `haze-ui/css/*.css` subpaths, or let
+  [haze-ui-vite](https://www.npmjs.com/package/haze-ui-vite) inject the right
+  files per import through `haze-ui/css-manifest.json`.
+  → [Getting started](https://wmzy.github.io/haze-ui/getting-started)
+- **`Control<T> | T` controllable state** — one state prop per component,
+  powered by [react-use-control](https://github.com/wmzy/react-use-control);
+  no `defaultXxx`/`xxx` dual API to keep in sync.
+  → [Getting started](https://wmzy.github.io/haze-ui/getting-started)
+- **AI / chat component family** — `ChatContainer`, `ChatMessage`,
+  `StreamingText`, `ToolCallCard`, `ThinkingIndicator` and `ChatInput` cover
+  the agent chat surface, with a unit-tested adapter recipe for the Vercel AI
+  SDK's `useChat`.
+  → [AI showcase](https://wmzy.github.io/haze-ui/ai-showcase) ·
+  [Recipes](https://wmzy.github.io/haze-ui/recipes)
+- **Multi-calendar date layer** — Gregorian plus six built-in adapters
+  (Hijri Umm al-Qura, Persian, Hebrew, Japanese era, Buddhist, Ethiopic):
+  integer-arithmetic implementations cross-verified against full-ICU `Intl`
+  oracles, exported from the barrel via `getAdapter()`.
+  → [Components](https://wmzy.github.io/haze-ui/components)
+- **OKLCH tokens with W3C DTF export** — hover/active/focus-ring colors
+  re-derive at runtime from CSS relative-color formulas, and the whole token
+  registry exports to the W3C Design Tokens format for Figma / Tokens Studio.
+  → [Tokens](https://wmzy.github.io/haze-ui/tokens) ·
+  [Theme editor](https://wmzy.github.io/haze-ui/theme-editor)
+
+## Ecosystem
+
+| Resource | Link |
 | --- | --- |
-| `Carousel.tsx` | prev/next buttons `left`/`right` → `inset-inline-start`/`inset-inline-end`, plus a `[dir='rtl']` `scale: -1 1` mirror so the `‹`/`›` glyphs point along the reading direction |
-| `ChatMessage.tsx` | bubble tail corners `border-bottom-right-radius` / `border-bottom-left-radius` → `border-end-end-radius` / `border-end-start-radius` (tail follows the bubble's anchored side) |
-| `Chip.tsx` | close-button `margin-left` → `margin-inline-start` |
-| `Container.tsx` | `margin-left/right: auto` → `margin-inline: auto`; `padding-left/right` → `padding-inline` |
-| `ContextMenuItem.tsx`, `DropdownMenuItem.tsx`, `MenuItem.tsx`, `ConversationItem.tsx` | `text-align: left` → `text-align: start` |
-| `DiffViewer.tsx` | line-number gutter `text-align: right` → `end`, `border-right` → `border-inline-end` (gutter stays on the leading side) |
-| `List.tsx` | `padding-left` → `padding-inline-start` (list indent), both variants |
-| `NavigationBar.tsx` | end-slot `margin-left: auto` → `margin-inline-start: auto` |
-| `StepTimeline.tsx` | connector line `left` → `inset-inline-start` (stays under the inline-start marker column) |
-| `Stepper/Step.tsx` | connector `left: 50%` → `inset-inline-start: 50%` (extends toward the next step) |
-| `TableHead.tsx` | `th { text-align: left }` → `start` |
-| `TreeItem.tsx` | checkbox/icon `margin-right` → `margin-inline-end`; indent guide `border-left` → `border-inline-start` |
-
-Kept physical on purpose — glyph geometry or symmetric layout, not
-reading-flow sides: the rotated border chevrons in Accordion/Disclosure,
-Checkbox's rotated checkmark, Radio's centered dot, Affix's symmetric
-`left: 0; right: 0` stretch.
-
-### Partial support: known gaps
-
-- **Floating panels (Popover, DropdownMenu, Tooltip, ContextMenu,
-  Combobox, Datepicker)** — *fixed*: `FloatingPlacement` is logical now.
-  Tier 1 uses logical `position-area` values (`span-inline-end
-  block-end`, …) where engines accept them and falls back to
-  dir-switched physical classes; the tier-2 JS math
-  (`utils/collision.ts` → `computeFloatingPosition(..., { dir })`)
-  mirrors the x-axis. In RTL the panels open on the mirrored side
-  automatically.
-- **Input adornments** — `SelectCore` / `ModelPicker` chevrons
-  (`background-position: right …` + `padding-right`) and
-  `PasswordInputCore`'s absolute reveal button sit on the physical right
-  with matching padding. Consistent under RTL, but not mirrored.
-- **Progress (circle)** — SVG `stroke-dashoffset` fill runs clockwise
-  regardless of direction (SVG has no inline axis).
-- **Physical-by-design placement APIs** — `Drawer` `placement`
-  (`'left'`/`'right'`), `Toast` placement (`'top-left'`, …),
-  `SwipeAction` left/right action edges, `BackToTop`'s bottom-right
-  corner, `CodeBlock`'s top-right language badge: the side is the API,
-  so it stays physical.
-
-### Workaround for remaining gaps
-
-Wrap with `dir="rtl"` for everything above; for the physical-by-design
-cases, override with logical insets through the `className` every
-component accepts:
-
-```jsx
-<Drawer placement="right" className="rtl-drawer" />
-```
+| Documentation | <https://wmzy.github.io/haze-ui/> |
+| Getting started | <https://wmzy.github.io/haze-ui/getting-started> |
+| Migration guide (AntD / shadcn) | <https://wmzy.github.io/haze-ui/guides/migration> |
+| llms.txt / full API for AI readers | <https://wmzy.github.io/haze-ui/llms.txt> |
+| MCP server (`haze-ui-mcp`) | <https://www.npmjs.com/package/haze-ui-mcp> |
+| shadcn registry | [registry/README.md](./registry/README.md) — `pnpm dlx shadcn@latest add wmzy/haze-ui/button` |
+| create-haze-ui (CLI scaffolding) | <https://www.npmjs.com/package/create-haze-ui> |
+| haze-ui-vite (CSS auto-injection) | <https://www.npmjs.com/package/haze-ui-vite> |
 
-```css
-[dir='rtl'] .rtl-drawer {
-  /* nudge a physical placement back to the reading-flow side */
-  inset-inline-end: 0;
-}
-```
-
-## Related Projects
+Every styled export is also installable through the shadcn CLI as a thin
+wrapper over the npm package — see [registry/README.md](./registry/README.md).
 
-- [react-use-control](https://github.com/wmzy/react-use-control)
+## Community
 
-## How to Contribute
+- 🐛 [Report a bug](https://github.com/wmzy/haze-ui/issues/new?template=bug_report.yml)
+- ✨ [Request a feature](https://github.com/wmzy/haze-ui/issues/new?template=feature_request.yml)
+- 📖 [Contribute to the project](./CONTRIBUTING.md)
+- 🔒 [Security policy](./SECURITY.md)
 
-Anyone and everyone is welcome to contribute. 
+**Building with haze-ui?** We would love to feature you. Open an issue
+titled `used by: <your project>` with the project name, a link and (optionally)
+a logo, and it will be added to this README.
 
 ## License
 
 [MIT](https://choosealicense.com/licenses/mit/)
-
-## FAQ
-
-### Components render without any styles
-
-haze-ui ships styles as separate CSS subpaths — the JS entry does not
-import any stylesheet. Import the full bundle once:
-
-```js
-import 'haze-ui/styles.css';
-```
-
-or import the tokens plus each component's own rules:
-
-```js
-import 'haze-ui/css/tokens.css';
-import 'haze-ui/css/button.css';
-```
-
-### Is there a CommonJS build?
-
-No — haze-ui is ESM-only (`"type": "module"`). Use a bundler or runtime
-with ESM support (Vite, webpack 5, Next.js, Node ≥ 18, …).
-
-### Does haze-ui support React 18?
-
-No — the peer range is `react@^19.0.0` by design (see
-[React 19+ by design](#react-19-by-design)). Upgrade to React 19 first;
-haze-ui ships no React 18 compatibility layer.
-
-### How do I detect (or degrade) the relative-color syntax?
-
-Since v1.13, theme interaction states are derived with CSS relative
-colors, so the browser baseline from [Browser support](#browser-support)
-applies — Chrome/Edge 119+, Safari 16.4+, Firefox 128+, with no HSL/hex
-fallbacks shipped. To gate your own fallback styling on support, probe
-the syntax in CSS:
-
-```css
-@supports (color: oklch(from red calc(l + 0.05) 0 h)) {
-  /* relative colors available: derive custom states from tokens */
-}
-```
-
-or from JS before deciding which stylesheet to load:
-
-```js
-if (CSS.supports('color: oklch(from red calc(l + 0.05) 0 h)')) {
-  // relative colors available — load the v1.13+ token sheet
-} else {
-  // below baseline: pin a pre-OKLCH version or ship your own fallbacks
-}
-```
-