haze-ui 1.25.0 → 1.27.0

package/README.md

@@ -5,14 +5,25 @@
 English | [简体中文](./README-zh_CN.md)
 
 [![npm](https://img.shields.io/npm/v/haze-ui)](https://www.npmjs.com/package/haze-ui)
+[![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
 
 - 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)
 
@@ -32,6 +43,117 @@ npm i haze-ui
 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 ships two runtime dependencies — `react-use-control`, the engine
+behind `ControlOrValue<T>`, and `react-f0rm` (^1.3), the form engine
+behind `FormItem`/`FormList` (the same author's headless form store).
+Five integrations remain optional peers, installed only when you use the
+components that need them:
+
+```sh
+npm i @tanstack/react-table               # DataTable (peer range ^9.2.4)
+npm i recharts                            # Chart (peer range ^3.10.1)
+npm i @dnd-kit/core @dnd-kit/sortable \
+      @dnd-kit/utilities                  # TagInput/TagGroup sortable
+                                           # (^6.3.1 / ^10.0.0 / ^3.2.2)
+```
+
+Everything else — `Button`, `Input`, `Dialog`, `Select`, … — runs with
+nothing beyond `react` and the two runtime dependencies. The dist is ESM
+with `preserveModules` and side-effect-free JS, so bundlers (Next.js,
+Vite, webpack, Turbopack, Rollup) tree-shake the unused re-export chains
+and never resolve peers you haven't installed: `import { Button } from
+'haze-ui'` works without `@tanstack/react-table`. Only bundler-less
+consumers (bare Node ESM importing the barrel, which links the module
+graph eagerly) must install the optional peers; 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
@@ -83,6 +205,47 @@ 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.
 
+### 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 —
@@ -160,6 +323,116 @@ function SettingsView() {
 }
 ```
 
+## 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 (optional dnd-kit peers)
+
+`TagInput` and `TagGroup` accept `sortable?: boolean` — opt-in drag
+reordering powered by `@dnd-kit/core` / `@dnd-kit/sortable` /
+`@dnd-kit/utilities` (optional peers, same tree-shaking contract as
+recharts and TanStack Table). `TagInput` writes the new array through
+`onChange`; `TagGroup` 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.
@@ -183,6 +456,168 @@ function SettingsView() {
 }
 ```
 
+## 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 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
@@ -194,6 +629,25 @@ 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
@@ -457,13 +911,34 @@ 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. A regression smoke test
-(`src/lib/rtl.test.tsx`) renders Progress, Alert, Badge, Tag and Dialog
-in a `dir="rtl"` subtree asserting rendering, axe cleanliness and
-unchanged aria contracts.
+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)
 
@@ -503,12 +978,13 @@ Checkbox's rotated checkmark, Radio's centered dot, Affix's symmetric
 ### Partial support: known gaps
 
 - **Floating panels (Popover, DropdownMenu, Tooltip, ContextMenu,
-  Combobox, Datepicker)** — placements are physical sides
-  (`'left'`/`'right'`/`'bottom-end'`, …). The CSS anchor-positioning
-  `position-area` grid keywords and the JS collision math
-  (`utils/collision.ts`, viewport coordinates) are physical; migrating to
-  logical `position-area` keywords is a tracked future change. In RTL the
-  panels position identically to LTR.
+  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
@@ -573,6 +1049,12 @@ import 'haze-ui/css/button.css';
 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

package/dist/components/Accordion/Accordion.js

@@ -1,4 +1,5 @@
 
+"use client";
 import { classnames as e } from "../../utils/classnames.js";
 /* empty css                    */
 import { jsx as t } from "react/jsx-runtime";

package/dist/components/Accordion/AccordionItem.js

@@ -1,4 +1,5 @@
 
+"use client";
 import { classnames as e } from "../../utils/classnames.js";
 /* empty css                        */
 import { jsx as t, jsxs as n } from "react/jsx-runtime";

package/dist/components/Accordion/index.js

@@ -1,3 +1,4 @@
+"use client";
 import e from "./Accordion.js";
 import t from "./AccordionItem.js";
 export { e as Accordion, t as AccordionItem };

package/dist/components/Affix/Affix.js

@@ -1,4 +1,5 @@
 
+"use client";
 import { classnames as e } from "../../utils/classnames.js";
 /* empty css                */
 import { jsx as t } from "react/jsx-runtime";

package/dist/components/Affix/index.js

@@ -1,2 +1,3 @@
+"use client";
 import e from "./Affix.js";
 export { e as Affix };

package/dist/components/Alert/Alert.js

@@ -1,4 +1,5 @@
 
+"use client";
 import { classnames as e } from "../../utils/classnames.js";
 import { useStrings as t } from "../LocaleProvider/useStrings.js";
 /* empty css                */

package/dist/components/Alert/index.js

@@ -1,2 +1,3 @@
+"use client";
 import e from "./Alert.js";
 export { e as Alert };