haze-ui 1.26.0 → 1.28.0

package/README.md

@@ -5,6 +5,7 @@
 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
@@ -14,6 +15,15 @@ English | [简体中文](./README-zh_CN.md)
 - 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)
 
@@ -33,6 +43,42 @@ 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
@@ -52,26 +98,61 @@ modern React rather than carrying a compatibility layer for 18:
 On React 18? Upgrade first. haze-ui ships no React 18 compatibility
 layer, and none is planned.
 
-### Optional peer dependencies
-
-haze-ui's only required runtime dependency is `react-use-control` — the
-engine behind `ControlOrValue<T>`. Two integrations are optional peers,
-installed only when you use the components that need them:
+#### 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 react-f0rm              # FormItem (peer range ^1.1.1)
-npm i @tanstack/react-table   # DataTable (peer range ^9.2.4)
+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 `react-use-control`. 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 `react-f0rm`. Only bundler-less consumers
-(bare Node ESM importing the barrel, which links the module graph
-eagerly) must install both peers; the `haze-ui/form` and
-`haze-ui/components/DataTable` subpaths bypass the barrel entirely.
+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
 
@@ -126,7 +207,7 @@ re-deriving file names — the mapping changes in lockstep with the build.
 
 ### Server Components (Next.js App Router)
 
-Every JS module in `dist/` starts with the `'use client'` directive,
+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
@@ -141,6 +222,26 @@ export function Actions() {
 }
 ```
 
+**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).
@@ -222,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.
@@ -245,29 +456,167 @@ 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 101 components grouped with one-line
+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** — a shadcn/ui-compatible 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>.
-Consume it with the shadcn CLI:
+**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
 ```
 
-To be precise about coverage: it contains only the **agent components** (the
-AI & Chat group plus AsyncSection). Each item is a wrapper file, not vendored
-source — it re-exports the published component and imports its stylesheet, so
-haze-ui stays an npm dependency that keeps updating underneath; treat the
-generated file as your customization layer.
+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
 
@@ -280,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
@@ -552,10 +920,25 @@ 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)
 
@@ -595,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

package/dist/components/Anchor/Anchor.js

@@ -0,0 +1,78 @@
+
+"use client";
+import { classnames as e } from "../../utils/classnames.js";
+/* empty css                 */
+import { jsx as t } from "react/jsx-runtime";
+import { useEffect as n } from "react";
+import { useControl as r } from "react-use-control";
+//#region src/lib/components/Anchor/Anchor.tsx
+var i = "haze-Anchor__nav", a = "haze-Anchor__list", o = "haze-Anchor__link", s = "haze-Anchor__linkActive";
+function c({ items: c, activeId: l, onClick: u, offsetTop: d = 0, bounds: f = 5, getContainer: p, className: m, ...h }) {
+	let [g, _] = r(l, () => c[0]?.id ?? ""), v = (e) => {
+		let t = document.getElementById(e);
+		if (!t) return;
+		let n = p?.() ?? window;
+		if (n instanceof HTMLElement) {
+			n.scrollTop = t.getBoundingClientRect().top - n.getBoundingClientRect().top + n.scrollTop - d;
+			return;
+		}
+		n.scrollTo({
+			top: t.getBoundingClientRect().top + window.scrollY - d,
+			behavior: "smooth"
+		});
+	};
+	return n(() => {
+		if (typeof IntersectionObserver > "u") return;
+		let e = /* @__PURE__ */ new Set(), t = p?.() ?? window, n = new IntersectionObserver((t) => {
+			for (let n of t) n.isIntersecting ? e.add(n.target.id) : e.delete(n.target.id);
+			let n = c.find((t) => e.has(t.id));
+			n && _(n.id);
+		}, {
+			root: t instanceof HTMLElement ? t : null,
+			rootMargin: `${-d}px 0px 0px 0px`
+		});
+		for (let e of c) {
+			let t = document.getElementById(e.id);
+			t && n.observe(t);
+		}
+		return () => n.disconnect();
+	}, [
+		c,
+		d,
+		p,
+		_
+	]), n(() => {
+		if (typeof IntersectionObserver < "u") return;
+		let e = p?.() ?? window, t = e instanceof HTMLElement ? e : window, n = e instanceof HTMLElement ? e.getBoundingClientRect().top : 0, r = () => {
+			let e;
+			for (let t of c) {
+				let r = document.getElementById(t.id);
+				r && r.getBoundingClientRect().top - n <= f && (e = t.id);
+			}
+			e && _(e);
+		};
+		return t.addEventListener("scroll", r, { passive: !0 }), () => t.removeEventListener("scroll", r);
+	}, [
+		c,
+		f,
+		p,
+		_
+	]), /* @__PURE__ */ t("nav", {
+		...h,
+		className: e([i, m]),
+		children: t("ul", {
+			className: e([a]),
+			children: c.map((n) => /* @__PURE__ */ t("li", { children: /* @__PURE__ */ t("a", {
+				href: `#${n.id}`,
+				"aria-current": g === n.id ? "true" : void 0,
+				onClick: (e) => {
+					e.preventDefault(), _(n.id), u?.(n.id), v(n.id);
+				},
+				className: e([o, g === n.id && s]),
+				children: n.label
+			}) }, n.id))
+		})
+	});
+}
+//#endregion
+export { c as default };

package/dist/components/Anchor/index.js

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