@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/Modal.md

@@ -0,0 +1,107 @@
+# `<Modal>` — focus-locked dialog
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Button onClick={() => setOpen(true)}>Edit contact</Button>
+
+<Modal open={open} onOpenChange={setOpen} size="md">
+  <Modal.Header>Edit contact</Modal.Header>
+  <Modal.Body>
+    <Stack gap="md">
+      <Input label="Name" value={name} onChange={(e) => setName(e.target.value)} />
+    </Stack>
+  </Modal.Body>
+  <Modal.Footer>
+    <Modal.Close><Button variant="secondary">Cancel</Button></Modal.Close>
+    <Button onClick={save}>Save</Button>
+  </Modal.Footer>
+</Modal>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `ModalProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `open` | `boolean` | yes | Controlled open state. Required. |
+| `onOpenChange` | `(open: boolean) => void` | yes | Fired when Modal wants to change open state — Esc, overlay click, Close button, programmatic. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'full'` | no | Size preset. Defaults to `'md'`. - `'sm'` (400px) — confirms and short prompts. - `'md'` (560px) — the default; typical forms. - `'lg'` (800px) — wide forms, tables, previews. - `'full'` (95vw × 90dvh, fixed height) — long documents, e.g. an HTML email. See {@link ModalSize}. |
+| `overlay` | `'solid' \| 'blur'` | no | Overlay variant. 'solid' (default) paints a dark dimming layer. 'blur' uses a light tinted background plus `backdrop-filter: blur(4px)` for a frosted-glass effect. 'blur' costs an extra compositor layer — fine for normal use; avoid stacking three blurred modals at once. |
+| `stackMode` | `'replace' \| 'overlay'` | no | How this modal relates to existing modals in the stack when it opens. - `'overlay'` (default): if there's a modal below this one, it stays visible underneath. This modal's own overlay paints transparent so the parent's dim shows through. Only the bottom modal (depth 0) paints the actual dim/blur. The user sees the parent's context behind the active modal. - `'replace'`: any modals below this one are hidden via `display: none` (React state preserved). This modal paints its own overlay normally. Best for forced-step modals where the parent context is irrelevant. Has no effect when this is the only open modal. |
+| `disableEscapeClose` | `boolean` | no | Disable Escape-to-close. Default false. Combined with `dismissOnOverlayClick: false` and omitting `<Modal.Close>` produces a fully forced step. |
+| `dismissOnOverlayClick` | `boolean` | no | When false, clicking the overlay backdrop does NOT close the modal. Default true. |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | no | Initial focus target on open. Default: the dialog container itself. Pass a ref to override (e.g. focus the first input in a form). |
+| `returnFocusRef` | `RefObject<HTMLElement \| null>` | no | Where focus goes when the modal closes. Default: back to whatever was focused when it opened. That default breaks whenever the opener is gone by close time — a row's "⋯" trigger whose row was just deleted, or a button that unmounts in the same commit that opens the modal (the capture then snapshots `<body>`). Focus lands on `<body>` and a keyboard user loses their place. The ref is read **at close time**, not at open time, so it may be pointed at whatever still exists once the work is done — the next row's trigger, the empty state's first button. If it is empty or its element has also left the document, Modal falls back to the captured opener, and then to doing nothing, exactly as before this prop existed. The target is scrolled into view (`block: 'nearest'`) after focus; the captured opener is not. |
+| `children` | `ReactNode` | yes | Compound children: Header / Body / Footer / Close + any consumer JSX. |
+| `className` | `string` | no | className passes through to the dialog container. |
+| `style` | `CSSProperties` | no | style passes through to the dialog container. |
+| `aria-label` | `string` | no | Required for a11y when no Modal.Header is rendered. When Header IS rendered, aria-labelledby auto-binds to the heading id; this prop is then ignored. |
+| `aria-describedby` | `string` | no | Optional id of an external descriptor element; sets aria-describedby on the dialog. |
+
+### `ModalBodyProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `padding` | `'none' \| 'default'` | no | Override body's padding. Default 'default' (--space-4). 'none' for edge-to-edge content. |
+| …native | | | plus native `<div>` attributes |
+
+### `ModalCloseProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one React element. Close clones this element to inject an `onClick` that closes the modal, chained with the child's existing `onClick` (consumer runs first). |
+
+### `ModalFooterProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `align` | `'start' \| 'end' \| 'space-between'` | no | Horizontal action alignment. Default 'end'. |
+| …native | | | plus native `<div>` attributes |
+
+### `ModalHeaderProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `closeButton` | `boolean` | no | Show the built-in × close button on the right edge. Default true. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Controlled-only.** Pass `open` + `onOpenChange` always. There is no `<Modal.Trigger>` — wire your own button(s).
+- **Four sizes:** `sm` (400px), `md` (560px, default), `lg` (800px) size to their content; `full` is a near-full-screen reader, a **fixed** 95vw × 90dvh by default (tokens `--modal-content-width-full` / `--modal-content-height-full`) with Body scrolling between a pinned Header/Footer. Use it for long documents like an HTML email, not for short forms, which float in a mostly empty box. Below 640px every size goes fullscreen.
+- **Overlay variant:** `overlay="solid"` (default, dark dim) or `overlay="blur"` (frosted-glass effect — light tint + `backdrop-filter: blur(4px)`). Avoid stacking three blurred modals — extra compositor cost per layer.
+- **`<Modal.Header>` auto-wires `aria-labelledby`.** Pass `closeButton={false}` to hide the built-in × button (e.g. forced-step modals). The Header's children become the dialog title.
+- **`<Modal.Body>` scrolls** when content overflows. `padding="none"` for edge-to-edge children (e.g. a tabs strip).
+- **Footer actions wrap, not clip.** When the actions do not fit on one row (e.g. three buttons in `size="sm"`), they wrap onto a second row.
+- **`<Modal.Footer>` defaults to right-aligned actions.** Use `align="space-between"` to split a danger action away from save/cancel.
+- **`<Modal.Close>`** wraps a clickable child and fires `onOpenChange(false)` on click. Chains with the child's existing `onClick`.
+- **Forced step:** combine `disableEscapeClose`, `dismissOnOverlayClick={false}`, omit `<Modal.Close>`, and pass `<Modal.Header closeButton={false}>` to lock the user into the modal until they resolve it programmatically.
+- **Stacked modals.** Default `stackMode="overlay"`: the parent stays visible underneath and the inner overlay paints transparent so the parent's dim shows through (one effective dim layer for the stack). Use `stackMode="replace"` to hide the parent via `display: none` (React state preserved) — best for forced steps where the parent context is irrelevant. Escape still closes only the topmost — and yields to any open floating surface first (Select/Popover/menu/date-time popover: the first press closes the surface, the next closes the modal); body scroll stays locked across the whole stack.
+- **Initial focus:** pass `initialFocusRef` to focus a specific element (e.g. the first input). Otherwise the dialog container receives focus and the focus trap takes over.
+- **Return focus:** on close, focus goes back to whatever was focused when the modal opened. When that element will not survive the modal — a deleted row's `⋯` trigger, or a button that unmounts in the same commit that opens the modal — pass `returnFocusRef` and point it at something that still exists. It is read at CLOSE time, so you can set `returnFocusRef.current` after the work finishes (next row's trigger, or the empty state's first button). If it is empty or detached, Modal falls back to the captured opener, then to doing nothing. A `returnFocusRef` target is scrolled into view (`{ block: 'nearest' }`) since it may be far from where the user was; the captured opener is not scrolled. A Modal unmounted while still open (e.g. `{row && <Modal open …/>}`) restores the same way, but only if focus was lost — an element your code focused after the unmount keeps it.
+
+**Anti-patterns:**
+
+- ❌ Rendering a Modal as a child of another component that itself uses `position: fixed` — the portal escapes that container anyway, so the fixed positioning is dead code. Just render `<Modal>` at any level; it portals to `document.body`.
+- ❌ Calling `onOpenChange={() => {}}` AND providing `<Modal.Close>` — the Close button calls `onOpenChange(false)` which then no-ops. Use `disableEscapeClose + dismissOnOverlayClick={false}` + omit Close for forced steps.
+- ❌ Mutating an `initialFocusRef.current` value after open — Modal reads the ref when the modal opens AND whenever it becomes the top of the stack again (e.g., after a nested modal closes). Don't rely on a specific number of reads; instead, ensure the ref points at a stable element while the modal is open.
+- ❌ Moving focus yourself in an effect after `onOpenChange(false)` — you race Modal's own restore, which runs in a layout effect. Pass `returnFocusRef` instead.
+- ❌ Using `<Modal>` for popovers or non-blocking notifications. Use `<Popover>`, `<DropdownMenu>`, or wait for `<Toast>`.
+
+- **`<Modal.Footer>`** is `role="group"` so screen readers announce the action set as a unit.
+- **`<Modal.Close>`** requires exactly one React element child (it throws otherwise).
+- ❌ Long scrollable forms with sticky footers containing additional sticky elements inside Body — flexbox + sticky compose badly. Use `<Modal.Footer>` for the actions and let Body scroll.
+- ❌ Opening a modal from inside another modal without using `<Modal>` itself (e.g. a custom div with `position: fixed`) — skipping the stack registry breaks Esc routing and z-index ordering.
+- ❌ Passing neither a `<Modal.Header>` nor an `aria-label` — warns in development; screen-reader users get no announcement on open.
+- ❌ Inline confirms attached to a button — use `<ConfirmationPopover>`.
+
+**See also:** `<Drawer>` for edge-anchored variant.

package/docs/components/MoneyInput.md

@@ -0,0 +1,62 @@
+# `<MoneyInput>`
+
+Money field: currency picker (`CurrencySelect`) + formatted amount `Input`, controlled on one `value: MoneyValue` (`{ amount: string | null; currency: string }`), `onChange(value)`. `amount` is a **canonical decimal string** (`"1234.50"`, `"-3"`) or `null` — never a JS number. `currencies` (ISO 4217, required) lists what the picker offers; exactly one renders a static prefix instead. The amount groups as you type in the locale's separators, keeps the caret where you are editing, rejects keystrokes past the currency's precision (2 for EUR, 0 for JPY, 3 for KWD) — a digit typed inside a full fraction overwrites the next one. Backspace/Delete step over group separators, and over the decimal while a fraction follows it (select the decimal to remove it). Blur pads the fraction (`12` → `12.00`). Switching currency rounds the amount half-up to the new precision (and pads it, as blur would). An external `amount` that is not a canonical decimal string displays empty with a dev warning. In comma-decimal locales the numpad `.` key types the decimal; a paste or drop is parsed on its own, then spliced over the selection. It must be exactly one number, optionally with currency symbols, a label word before it (`Total`, `Итого:`) and a currency word after it (an ISO code or `руб.`/`р.` — never a magnitude like `K`, `млн`, `million`) and a sign (`-5`, `−5`, `+5`, `5-`, `(1,234.50)`). Grouping must be unambiguous — first group 1–3 digits, then exactly 3, one kind of group character (`,` `.` space, NBSP, apostrophe) — and with both `.` and `,` the last one is the decimal whatever the locale. Anything doubtful (`12,34` or `1.234` in en, `15.01.2024`, `$5K`, `5 10`, a line break, extra words, a second number, stray parentheses) is rejected with no change, as is a partial paste that adds a second decimal, a sign, or fraction digits past the precision. A whole-value paste truncates to the precision (`$1,234.5678` → `1,234.56`). A negative paste must replace the whole value and needs `allowNegative` (or an already-negative value). `allowNegative` permits a leading `-`; without it, adding a `-` (typed or pasted) is rejected rather than silently dropped, and an existing external negative keeps its sign while edited. `onChange` fires on every edit and currency switch — never for blur-without-edit or external value changes. `name` emits hidden `<name>` / `<name>_currency` inputs.
+
+```tsx
+const [price, setPrice] = useState<MoneyValue>({ amount: null, currency: 'EUR' });
+<MoneyInput
+  aria-label="Price"
+  currencies={['EUR', 'USD', 'GBP']}
+  value={price}
+  onChange={setPrice}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `MoneyValue` | yes | Controlled value. `amount` is a canonical decimal string or `null`; `currency` an ISO 4217 code. |
+| `onChange` | `(value: MoneyValue) => void` | yes | Fires on every amount edit and currency switch. Never fires for blur-without-edit or external value changes. |
+| `currencies` | `string[]` | yes | ISO 4217 codes to offer. Exactly one renders a static prefix instead of a picker. |
+| `currencyDisplay` | `'code' \| 'symbol' \| 'both'` | no | How the selected currency renders: `"code"` (default), `"symbol"` or `"both"`. |
+| `currencyLabel` | `string` | no | Overrides the currency picker's accessible name (default: "<group label> Currency"). |
+| `allowNegative` | `boolean` | no | Allow a leading minus. Default `false`. |
+| `locale` | `string` | no | BCP-47 locale for separators and currency names. Defaults to the i18n locale. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Control size, forwarded to both controls. Default `"md"`. |
+| `invalid` | `boolean` | no | Error chrome on both controls. |
+| `disabled` | `boolean` | no | Disable both controls. |
+| `readOnly` | `boolean` | no | Make both controls read-only. |
+| `required` | `boolean` | no | Mark the amount required. |
+| `placeholder` | `string` | no | Placeholder for the amount field. |
+| `name` | `string` | no | Emits hidden `<name>` (canonical amount) and `<name>_currency` inputs for native form posts. |
+| `id` | `string` | no | Stable id; placed on the amount field so an external `<label htmlFor>` focuses it. |
+| `aria-label` | `string` | no | Accessible name when used STANDALONE (outside `<Field>`). |
+| `aria-labelledby` | `string` | no | Ids of elements labelling the group (injected by `<Field>`). |
+| `aria-describedby` | `string` | no | Ids of description/error elements; forwarded to the amount field (injected by `<Field>`). |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+Inside a `<Field>` the label and error wiring are injected (the picker is named "Price Currency"):
+
+```tsx
+<Field label="Price" error={price.amount === null ? 'Required' : undefined}>
+  <MoneyInput currencies={['EUR', 'USD']} value={price} onChange={setPrice} />
+</Field>
+```
+
+**When NOT to use:** a currency without an amount — use `CurrencySelect`. Plain quantities or non-money decimals — `<Input inputMode="decimal">`.
+
+**Anti-patterns**
+
+- ❌ Storing the formatted display (`"1,234.50"`) — persist the emitted `amount` + `currency`; the display is reconstructed from them.
+- ❌ `parseFloat(amount)` for maths — floats lose cents; use a decimal library or integer minor units.
+- ❌ Comparing `amount` strings for dirtiness — `"12"` and `"12.00"` are the same money (blur pads). Compare amounts numerically (decimal-aware), not as strings.
+
+**Known limitations**
+
+- Latin digits and 3-digit grouping only: locales with other numerals or grouping (e.g. Indian lakh `12,34,567`) display Latin digits grouped in threes.

package/docs/components/OptionsPicker.md

@@ -0,0 +1,123 @@
+# `<OptionsPicker>` — filter picker (multi/single, grouped, searchable)
+
+**Use for filter UX, not form fields.** A compound picker that opens a Popover
+with a search input and grouped/flat checkbox (multi) or radio (single) options.
+Multi mode buffers a draft until Apply; single mode commits per click.
+
+```tsx
+<OptionsPicker selected={events} onApply={setEvents}>
+  <OptionsPicker.Trigger>
+    <Button variant="secondary">
+      Events <ChevronDown size={14} />
+    </Button>
+  </OptionsPicker.Trigger>
+  <OptionsPicker.Content
+    label="Filter events"
+    groups={catalogGroups} // OR `options={flatOptions}` — XOR
+  />
+</OptionsPicker>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `OptionsPickerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `mode` | `"multi" \| "single"` | no |  |
+| `selected` | `string[] \| string \| null` | yes | Committed selection: `string[]` (multi) or `string \| null` (single). Multi: pass a stable array (state, or memoized) — a new array identity on every render resets the open panel's draft. |
+| `onApply` | `(next: string[], options: OptionsPickerOption[]) => void \| (next: string \| null, option: OptionsPickerOption \| null) => void` | yes | Called on Apply with the committed values and their option objects, in the same order. |
+| `onCancel` | `(() => void)` | no |  |
+| `open` | `boolean` | no |  |
+| `onOpenChange` | `((open: boolean) => void)` | no |  |
+| `children` | `ReactNode` | yes |  |
+
+### `OptionsPickerContentProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `options` | `OptionsPickerOption[]` | no |  |
+| `groups` | `OptionsPickerGroup[]` | no |  |
+| `loadOptions` | `(query: string, signal: AbortSignal) => Promise<OptionsPickerOption[]>` | no | Server search: called with the search query (`''` on every open) after `searchDebounceMs`, and its answer replaces the list — no client-side filtering on top. Flat options only. The previous request is aborted via `signal` when a newer one starts. Takes precedence over `options` / `groups` (dev warning if both are passed). The latest function is always the one called; a new identity (e.g. an inline arrow) does not refetch. |
+| `selectedOptions` | `OptionsPickerOption[]` | no | Option objects for currently selected values that may not be in any server answer (e.g. values restored from a URL), so they can be labelled. |
+| `searchDebounceMs` | `number` | no | Delay between the last keystroke (or opening) and the `loadOptions` call. Default `250`. |
+| `label` | `string` | yes | Accessible label on the panel (the dialog's `aria-label`). |
+| `emptyState` | `ReactNode` | no | Rendered when search produces zero matches. Defaults to the `optionsPicker.noMatches` i18n string (en: `'No matches'`). With `loadOptions` the visible row is hidden from assistive tech and a live region announces it instead — this text when it is a string, otherwise the default. An EMPTY string counts as unset, matching every other label override in the library. There is no way to suppress the message entirely — a blank listbox reads as a broken filter rather than as a deliberate silence. |
+| `footerCount` | `((selected: number, total: number) => ReactNode)` | no | Footer count formatter (multi only). Default `'${selected} of ${total}'`. Not called with `loadOptions` — there is no known total, so the footer reads `optionsPicker.selectedCount` (en: `'N selected'`). |
+| `searchable` | `boolean` | no | Whether to render the search bar at the top of the panel. Defaults to `true`. Hide it (`false`) for small/curated option lists where typing filters would just be noise — the selection-count header is hidden alongside the search input (the footer's `N of TOTAL` text still shows in multi mode). Ignored with `loadOptions`: server search needs the input, so it always shows. |
+| `className` | `string` | no |  |
+
+### `OptionsPickerTriggerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Must be a single React element that accepts a ref (e.g. `<Button>`). |
+
+<!-- props:end -->
+
+`mode="single"` for single-select: `selected: string | null`, `onApply(value | null)`, no Apply/Cancel footer.
+
+Don't use for form selects (use `<Select>`), action menus (use `<DropdownMenu>`),
+or single boolean toggles (use `<Checkbox>` or `<Switch>`).
+
+Multi mode (default) keeps a draft until Apply; Cancel, Esc and click-outside revert it. Single mode commits through `onApply` on each click and closes the panel.
+
+```tsx
+<OptionsPicker mode="single" selected={tenantId} onApply={setTenantId}>
+  <OptionsPicker.Trigger>
+    <Button variant="secondary">Tenant</Button>
+  </OptionsPicker.Trigger>
+  <OptionsPicker.Content
+    label="Filter tenant"
+    options={tenants.map((t) => ({ value: t.id, label: t.slug }))}
+  />
+</OptionsPicker>
+```
+
+## Async (server search)
+
+For lists too large to ship to the client, pass `loadOptions` to Content instead of `options` / `groups`.
+
+```tsx
+<OptionsPicker
+  selected={ids}
+  onApply={(next, options) => {
+    setIds(next);
+    setPicked(options); // use these to label the trigger
+  }}
+>
+  <OptionsPicker.Trigger>
+    <Button variant="secondary">{picked.map((o) => o.label).join(', ') || 'Members'}</Button>
+  </OptionsPicker.Trigger>
+  <OptionsPicker.Content
+    label="Filter members"
+    loadOptions={(query, signal) => fetchMembers(query, signal)} // returns { value, label }[]
+    selectedOptions={picked} // labels for values restored from URL/state
+  />
+</OptionsPicker>
+```
+
+- **Fetching.** `loadOptions(query, signal)` returns a flat `OptionsPickerOption[]`. It is called with `''` on every open and after `searchDebounceMs` (default `250`) following each keystroke; the previous request is aborted via `signal`, so pass it to `fetch`. The latest `loadOptions` is always the one called, and a new function identity does not refetch, so an inline arrow is fine. The server's answer replaces the list: there is no client-side filtering on top. The search input is always shown (`searchable` is ignored).
+- **Rows.** Loading, error (with a Retry action) and "No matches" rows are built in. Groups are not supported in async mode (flat only). `loadOptions` wins over `options` / `groups` (dev warning if both are passed).
+- **Selected rows are pinned** above the server results (snapshot taken on open and on each query change); ticking or unticking never moves rows under the pointer.
+- **Labels.** Selected values are labelled from a cache of every answer seen while the picker is mounted plus `selectedOptions`; an unknown value falls back to its raw string. **Pass `selectedOptions` for values restored from URL/state** (e.g. a deep link), otherwise their rows read as raw ids.
+- **`onApply` second argument.** Multi: `onApply(values, options)`; single: `onApply(value, option | null)`. Use it to label the trigger and keep `selectedOptions` for the next render. Also works for static `options` / `groups`.
+- **Footer.** Multi mode reads "N selected"; `footerCount` is not called (there is no known total).
+- **Screen readers (Hard rule 10).** One polite live region announces loading, failure and no-matches (a failure reads "Failed to load options.", no-matches uses `emptyState` when it is a string, otherwise the default). The visible loading / error / empty rows are hidden from assistive tech so nothing is announced twice. Success is silent: the list is the result.
+
+`<OptionsPicker.Trigger>` takes a single ref-accepting element (typically a `<Button>`); open wiring and ARIA (`aria-haspopup`, `aria-expanded`, `aria-controls`) are injected, and your own ref on the child still receives the DOM node. `<OptionsPicker.Content>` hosts the search bar, the option list and (multi mode) the Apply/Cancel footer.
+
+OptionsPicker has no `name` attribute and no form association. Action menus (Edit / Delete / Archive) are commands, not filters — use `<DropdownMenu>`.
+
+**Anti-patterns**
+
+- ❌ Passing BOTH `options` and `groups` to Content — TypeScript rejects it. Pick one.
+- ❌ Calling `onApply` yourself inside Content's render — the picker owns the commit; treat `onApply(next)` as the single source of truth and update React state from it.
+- ❌ Multi-mode `selected` as a fresh array each render (e.g. `selected={ids.filter(…)}` inline) — a new identity resets the open panel's draft. Keep it in state or `useMemo`.
+- ❌ Async mode with `groups`, or restoring `selected` from a URL without `selectedOptions` (rows show raw ids).
+- ❌ Controlling open state without passing both `open` and `onOpenChange` — partial control breaks invariants.

package/docs/components/OtpInput.md

@@ -0,0 +1,65 @@
+# `<OtpInput>` — one-time-code field
+
+```tsx
+const [code, setCode] = useState('');
+<OtpInput value={code} onChange={setCode} onComplete={verify} />;
+<OtpInput length={4} type="alphanumeric" aria-label="Invite code" />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `length` | `number` | no | How many boxes to render. Default `6`. |
+| `value` | `string` | no | Controlled code. Sanitized and truncated to `length` on render, so a consumer echoing back a dirty string sees it cleaned rather than mis-sliced. Pair with `onChange`. |
+| `defaultValue` | `string` | no | Uncontrolled seed. Ignored when `value` is supplied. |
+| `onChange` | `((value: string) => void)` | no | Fires on every edit with the whole code so far — always sanitized, never longer than `length`, and never with a gap in the middle. |
+| `onComplete` | `((value: string) => void)` | no | Fires whenever the code becomes full with a value different from the last one — not on every keystroke while it is full. Use it to submit. Correcting a wrong character inside an already-full code re-fires with the corrected value; retyping the same character does not, since nothing changed. |
+| `type` | `'numeric' \| 'alphanumeric'` | no | Character set. Default `'numeric'`. See `OtpInputType`. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | no | Cell size. Default `'md'`. - `'sm'` — 24px cells; dense admin screens. - `'md'` — 32px cells (default); most forms. - `'lg'` — 40px cells; a dedicated verification screen. - `'xl'` — 48px cells; a code field that IS the screen (IdP login challenge, touch-first). Six cells still fit a 360px phone. No `<Input>` counterpart at this height — don't line it up with fields. |
+| `invalid` | `boolean` | no | Error visual on every cell plus `aria-invalid="true"`. Pair with a visible message and point `aria-describedby` at it (or wrap in `<Field error>`). |
+| `disabled` | `boolean` | no | Disable every cell. |
+| `required` | `boolean` | no | Marks the field required. There is no single native input to attach the native `required` attribute to — a per-cell `required` would let the browser block submit on an empty first cell while accepting a 1-of-`length` code as complete, which is worse than no native gate at all. Sets `aria-required="true"` on every cell instead (the group's `role="group"` does not support `aria-required` per ARIA 1.2 — only `textbox` and a handful of other roles do), the same way `aria-invalid` and `aria-describedby` are already repeated on every cell. Validating completeness is the consumer's job (pair with `invalid` + `onComplete`). |
+| `autoFocus` | `boolean` | no | Focus the first cell on mount. |
+| `id` | `string` | no | Id for the first cell, so an external `<label htmlFor>` focuses the field. |
+| `aria-label` | `string` | no | Accessible name for the group. Defaults to the localized `otpInput.groupLabel` ("Verification code") when omitted OR empty — an empty string is not an explicit name — so a standalone OtpInput is never an unnamed group. |
+| `aria-labelledby` | `string` | no | Ids of elements naming the group. Injected by `<Field>`; wins over `aria-label`. |
+| `aria-describedby` | `string` | no | Ids of description / error elements. Set on EVERY cell — see the remarks. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Every box carries `autocomplete="one-time-code"` + `inputMode`, so iOS and Android offer the code from a just-arrived SMS/email above the keyboard. No WebOTP — it is Android-Chrome-only and needs an origin-bound SMS body.
+- Focus advances as characters are typed. Boxes select their content on focus, so typing over a filled box replaces it, and a delivery shorter than the full code (a keystroke, or a short paste) spreads from whichever box is focused. A delivery of EXACTLY the full length — SMS/email autofill dumping it into whichever box happens to be focused — replaces the whole value instead of splicing in at that position. A delivery LONGER than the full length (an over-long paste) still splices in at the focused box and truncates, the same as a short delivery. **Never cap a box at one character** — that truncates an autofilled code to its first digit.
+- Roving tabindex — the whole group is one Tab stop. Arrows / Home / End move between boxes; Backspace on an empty box steps back. Deleting mid-code clears from that box onward, keeping the value contiguous.
+- Never masks. For a secret the user must not see → `<PasswordInput>`.
+- Not a native form control — it renders no named field, so nothing reaches `FormData`. Read the code from `onChange` / `onComplete` and submit it yourself. `required` sets `aria-required` on every box, not the group (`role="group"` doesn't support `aria-required`; a per-cell native `required` would instead pass a 1-of-`length` code as valid); validating completeness is yours.
+
+Inside a `<Field>`, the label and error wiring are supplied:
+
+```tsx
+<Field label="Invite code" error={error}>
+  <OtpInput length={4} type="alphanumeric" invalid={!!error} />
+</Field>
+```
+
+**When NOT to use**
+
+- A code the user copies rather than reads — a plain `<Input>` pastes just as well and does not fight the caret.
+- Codes longer than about eight characters — the boxes stop being scannable; use `<Input>`.
+- A password or PIN you need masked — `<PasswordInput>`. A one-time code is read off a phone and typed once; hiding it only costs the user the ability to spot a typo.
+
+**Anti-patterns**
+
+- ❌ Setting `maxLength` on the cells via `className` hacks or a fork — a one-character cap truncates an autofilled code to its first character.
+- ❌ Validating inside `onChange` and rejecting characters. The component already sanitizes; your form layer owns whether the code is correct.
+- ❌ Reading the code out of the DOM. It arrives in `onChange` / `onComplete`.
+
+**Accessibility**
+
+- The wrapper is a `role="group"`, named by `aria-labelledby`, then `aria-label`, then the localized default ("Verification code"; an empty `aria-label` also falls back). Each cell is named by position ("Digit 3 of 6").
+- There is deliberately no live region: `invalid` is a durable property already carried by `aria-invalid`, so announcing the outcome of a code check is the consumer's job.
+- A paste or autofill that delivers the whole code fills every box in one update; a screen reader announces only the cell focus lands on ("Digit 6 of 6"). Announce the result yourself (e.g. off `onComplete`) if silent multi-box fills would confuse your users.

package/docs/components/Page.md

@@ -0,0 +1,35 @@
+# `<Page>` — page-root layout primitive
+
+```tsx
+// Canonical CRM page shape
+<Page>
+  <PageHeader>
+    <PageHeader.Title>Contacts</PageHeader.Title>
+  </PageHeader>
+  <Card>{filters}</Card>
+  <Table>{rows}</Table>
+</Page>
+
+// Per-page rhythm override (rare — only when 'lg' doesn't fit)
+<Page gap="md">
+  {denseDashboardSections}
+</Page>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `gap` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | no | Vertical rhythm between top-level page sections. - `xs` (4) / `sm` (8) / `md` (12) — tighter than canonical; rare. - `lg` (16, **default**) — the canonical CRM page rhythm; matches every shipped mockup. - `xl` (24) / `2xl` (32) — looser; for spacious overview / hero pages. |
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Page is the OUTER wrapper at the page root. Inside it, sections compose with `<PageHeader>`, `<Card>`, `<Table>`, etc.
+- **Use Page at the page root, not nested.** For sub-regions (inside a card, modal, drawer), use `<Stack>` instead — those contexts have their own padding contract.
+- Page does NOT add padding. The page container (AppShell content, modal body) provides outer padding; Page just provides inner section rhythm.
+- Page is intentionally thin — a renamed Stack with a page-level default. It exists so future page-level concerns (max-width, scroll restoration, container queries) have a natural home.

package/docs/components/PageHeader.md

@@ -0,0 +1,133 @@
+# `<PageHeader>` — top-of-page heading area
+
+```tsx
+<PageHeader>
+  <PageHeader.Breadcrumb>
+    <Breadcrumb items={[...]} />
+  </PageHeader.Breadcrumb>
+  <PageHeader.BackButton href="/contacts" aria-label="Back to contacts" />
+  <PageHeader.Aside>
+    <Avatar size="lg" name="Acme Corp" />
+  </PageHeader.Aside>
+  <PageHeader.Title>Acme Corporation</PageHeader.Title>
+  <PageHeader.Subtitle>Founded 2014 · 230 employees</PageHeader.Subtitle>
+  <PageHeader.Meta>
+    <Badge tone="success">Active</Badge>
+    <Text size="sm" tone="muted">Last contacted 2 days ago</Text>
+  </PageHeader.Meta>
+  <PageHeader.Actions>
+    <Button variant="secondary">Email</Button>
+    <Button>Edit</Button>
+  </PageHeader.Actions>
+</PageHeader>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `PageHeaderProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `borderBottom` | `boolean` | no | Render a 1px bottom border under the header. Default `true`. Set `false` when placing a `<Tabs>` component as a sibling below — Tabs has its own `border-bottom`, and you don't want the double line. |
+| …native | | | plus native `<div>` attributes |
+
+### `PageHeaderActionsProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<div>` attributes |
+
+### `PageHeaderAsideProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<div>` attributes |
+
+### `PageHeaderBackButtonProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `href` | `string` | no | If set, renders as `<a href={href}>`. Mutually exclusive with `onClick` — passing both renders as `<button>` (the onClick wins) and emits a dev-only warning. |
+| `onClick` | `(() => void)` | no | If set, renders as `<button type="button" onClick={onClick}>`. Mutually exclusive with `href`. |
+| `aria-label` | `string` | no | Accessible label. Defaults to the i18n value at `pageHeader.back` (`'Go back'` in English) when omitted OR empty — an empty string is not an explicit name, so it takes the default too. |
+| `icon` | `ReactNode` | no | Icon to render. Default `<ChevronLeft size={16}>` from lucide-react. |
+
+### `PageHeaderBreadcrumbProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<div>` attributes |
+
+### `PageHeaderMetaProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<div>` attributes |
+
+### `PageHeaderSubtitleProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<p>` attributes |
+
+### `PageHeaderTitleProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `order` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | Heading semantic level (1–6). Default `1`. Passes through to `<Title order={order}>` so the rendered element is `<h1>`–`<h6>`. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'` | no | Visual size override (decouples from semantic level). Pass-through to `<Title size>` — useful for "section-level page headers" where the h-level is 2 but you want it to LOOK like an h1. |
+| `truncate` | `boolean` | no | Keep the title on one line, ending in an ellipsis where the title column ends (at the actions on wide layouts) instead of wrapping. Pass-through to `<Title truncate>`. Defaults to `false`. Anything inline AFTER the text (e.g. a status badge) is clipped with it — put badges in `PageHeader.Meta`. Screen readers still get the full text (don't add `aria-label`); sighted users don't, so show the full title somewhere else too if it matters. |
+| `children` | `ReactNode` | yes |  |
+
+<!-- props:end -->
+
+- **Compound API.** Seven slots: `Breadcrumb`, `BackButton`, `Aside`, `Title`, `Subtitle`, `Meta`, `Actions`. Detected via `c.type === SubComponent` after one level of Fragment unwrap. Unrecognized children are silently dropped.
+- **All slots optional.** Missing slots collapse to zero-height rows; minimal usage is `<PageHeader><PageHeader.Title>…</PageHeader.Title></PageHeader>`.
+- **`<PageHeader.BackButton>`** renders as `<a href>` when `href` is provided, or `<button onClick>` when `onClick` is provided. Mutually exclusive — both → button wins with a dev warn; neither → disabled button with a dev warn. Default `aria-label="Go back"`; default icon `<ChevronLeft size={16}>`. Lives in the breadcrumb row, left of the breadcrumb itself.
+- **`<PageHeader.Aside>`** is a position-based slot (not named "Icon" / "Avatar") so it accepts whatever leading element you need. Vertically centered with the title block.
+- **`<PageHeader.Subtitle>`** is a `<p>` with muted color.
+- **`<PageHeader.Meta>`** is a flex row that wraps — good for badges + timestamps.
+- **`<PageHeader.Actions>`** is already a wrapping, right-aligned flex row — put `<Button>`s directly in it. A wrapping `<Cluster>` inside it needs `justify="end"`, or its wrapped rows go ragged-left. On viewports < 640px, Actions moves below the title block and stays right-aligned (primary action at the thumb-side edge).
+- **NOT a `<header>` landmark.** PageHeader renders a `<div>` to avoid conflicting with the AppShell's app-level `<header role="banner">`.
+- **Shrinks to narrow containers without overflowing.** On viewports ≥ 640px the actions column is sized to fit its buttons on one line, capped so the title keeps about `--page-header-title-min` (160px, `--measure-2xs`; with an `<Aside>`, the aside and title share that room). A wide header keeps all its actions on one line to the right; once they'd leave the title less than that, the buttons wrap onto extra lines. Wrapped rows stay right-aligned when the buttons are direct children of `<PageHeader.Actions>` (or inside a `<Cluster justify="end">`). If a single action item is wider than the space left, the title shrinks below that instead of the header overflowing (as long as that item itself — plus the aside and gaps — fits in the container). `<PageHeader.Breadcrumb>` wraps too. A title word wider than its column breaks mid-word (`overflow-wrap: anywhere`) rather than overflowing — e.g. "Acme Corporation" beside an `<Aside>` in a narrow container. Below a 640px viewport the actions move below, still right-aligned: the header becomes a single column, or two (aside + title) with an `<Aside>`, and the actions span the full width.
+- **Give it a stretched or definite width.** In a shrink-to-fit parent PageHeader is only as wide as its content, so the actions don't sit at the right edge. Fix it where the width comes from: as a non-growing flex item, give the PageHeader `flex: 1` (or `width: 100%`) via its `className`; inside an `inline-block` parent or an `auto` grid track that doesn't work (the percentage is cyclic, `flex` is ignored) — make the parent block-level, or use a `1fr` / `minmax(0, 1fr)` track.
+
+#### Hard rule
+
+- ❌ Nesting `<PageHeader>` inside another `<PageHeader>` — undefined behavior. Use one PageHeader per page.
+- ❌ Putting non-PageHeader children (a `<div>`, a `<Stack>`) inside `<PageHeader>` — they're silently dropped. Use one of the seven slots.
+- ❌ Wrapping a sub-component in an HOC or deep nesting. The `c.type ===` detection handles ONE level of Fragment unwrap only.
+- ❌ Putting an Avatar inside `<PageHeader.Title>` — muddles the `<h1>`'s text content for screen readers. Use `<PageHeader.Aside>` instead.
+- ❌ `position: sticky` directly on `<PageHeader>` — out of scope for v1. Wrap in your own sticky container if you need sticky behavior.
+- ❌ Passing both `href` and `onClick` to `<PageHeader.BackButton>` — onClick wins with a dev warn. Pick one.
+
+- **`<PageHeader.Title>` `size`** decouples visual size from semantic level: `<PageHeader.Title order={2} size="3xl">` renders an `<h2>` that looks like an h1; `order={2}` alone uses the default h2 size (`2xl`).
+- **`<PageHeader.BackButton>` as an anchor** relies on your router to intercept the click; use `onClick={() => router.back()}` for programmatic navigation.
+- **When NOT to use:** arbitrary section headers within a page that are not its primary heading — use `<Title order={2}>` directly; a sticky top bar — PageHeader is a regular block element.
+- ❌ Passing multiple `<PageHeader.Title>` (or any duplicate sub-component) — only the FIRST match is rendered; duplicates are silently dropped.
+
+```tsx
+// Next to Tabs — drop the bottom border:
+<PageHeader borderBottom={false}>
+  <PageHeader.Title>Reports</PageHeader.Title>
+</PageHeader>
+<Tabs value={tab} onChange={setTab}>...</Tabs>
+
+// Record detail — one line, ellipsis at the actions; badges go in Meta:
+<PageHeader.Title truncate>{task.key} {task.title}</PageHeader.Title>
+```

package/docs/components/Pagination.md

@@ -0,0 +1,44 @@
+# `<Pagination>` — numbered nav with windowing
+
+```tsx
+const [page, setPage] = useState(1);
+<Pagination currentPage={page} pageCount={20} onPageChange={setPage} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `currentPage` | `number` | yes | Current 1-indexed page. Values outside `[1, pageCount]` clamp at render time (defensive — same precedent as `clampHeading` in `<EmptyState>`). |
+| `pageCount` | `number` | yes | Total number of pages. Values `< 1` clamp to `1`. The component still renders when `pageCount === 1` (single enabled current-page button + both prev/next disabled) so consumers don't have to conditionally hide it. The `disabled` prop still disables all three controls. |
+| `onPageChange` | `(page: number) => void` | yes | Called with the new 1-indexed page when the user clicks prev, next, or a page number. Not fired when the user clicks the current page. |
+| `siblingCount` | `number` | no | How many page-number buttons to show on each side of `currentPage`. Default `1`. Set to `0` for the tightest possible display (sidebar / narrow column) or `2` for wider footers. Boundary is fixed at 1 — first and last pages are always shown. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Visual size — `'sm'` (24px), `'md'` (32px, default), `'lg'` (40px). Tracks the Button / Input scale so Pagination sits cleanly inside a `<Cluster>` next to those components. |
+| `disabled` | `boolean` | no | When `true`, all buttons (prev / next / numbers) are disabled. Use during page transitions (loading, saving) to prevent double-clicks. |
+| `aria-label` | `string` | no | Accessible name for the `<nav>` wrapper. Defaults to `'Pagination'` when omitted OR empty — an empty string is not an explicit name, so it takes the default too. Override when multiple paginations appear on the same page (e.g., `'Top pagination'` / `'Bottom pagination'`). |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- Controlled-only — consumer owns `currentPage`. No internal state.
+- Sibling windowing — `siblingCount` (default `1`) controls how many pages on each side of current. Boundary fixed at 1 (first + last always shown). Slot count stays constant once ellipses kick in (`siblingCount * 2 + 5`) — the row's width doesn't jump as the user clicks.
+- Current page stays focusable and carries `aria-current="page"`; activating it is a no-op. Keeping it enabled preserves keyboard focus when controlled `currentPage` updates after a page change.
+- Sizes: `'sm'` (24px) / `'md'` (32px, default) / `'lg'` (40px) — tracks the Button / Input scale so Pagination sits cleanly next to a `<Button>` in a Cluster.
+- Out-of-range `currentPage` / `pageCount` clamp at render time (defensive — same precedent as `<EmptyState>`'s `clampHeading`).
+- **Not bundled**: page-size selector, count caption ("Showing 11–20 of 240"). Compose those with `<Select>` and text — keeps Pagination focused on navigation. `<DataTable>` (coming) owns its own footer.
+- For streams without a total → use `<CursorPagination>`.
+- For "load more" → use `<Button>` directly. **`<Button>` has no `loading` prop** — this line used to show one. Use `aria-disabled` and guard the handler, keeping the label stable: `<Button onClick={() => !isLoading && loadMore()} aria-disabled={isLoading || undefined}>Load more</Button>`. Native `disabled` would drop the button out of the tab order mid-interaction, and swapping the label renames a control the user just activated — see [Transient state and screen readers](../transient-state.md).
+- `paginationRange(currentPage, pageCount, siblingCount)` is exported as a pure utility for advanced consumers that want to compute the same item list themselves (e.g., to render a custom layout with the same windowing).
+
+```tsx
+// Tight display for a sidebar / narrow column
+<Pagination currentPage={5} pageCount={100} onPageChange={setPage} siblingCount={0} size="sm" />
+
+// Loading lock while data refetches
+<Pagination currentPage={page} pageCount={pageCount} onPageChange={setPage} disabled={isFetching} />
+```
+
+**A11y:** the wrapper is `<nav aria-label="Pagination">` (override `aria-label` when several paginations share a page). Prev/next buttons carry `aria-label="Previous page"` / `"Next page"` with the chevron icons `aria-hidden`; ellipses are decorative `<span aria-hidden>`, not focusable.

package/docs/components/Palette.md

@@ -0,0 +1,32 @@
+# Palette — categorical color set
+
+```tsx
+import { paletteTokens, type PaletteColor } from '@eocrm/design-system';
+
+// Consumer-side mapping: domain → color
+const TEAM_COLOR: Record<string, PaletteColor> = {
+  marketing: 'violet',
+  engineering: 'teal',
+  sales: 'amber',
+  ops: 'slate',
+};
+
+// Custom consumer chip using the palette tokens
+function TeamChip({ team }: { team: string }) {
+  const { bg, fg } = paletteTokens(TEAM_COLOR[team] ?? 'stone');
+  return (
+    <span style={{ background: bg, color: fg, padding: '2px 8px', borderRadius: 4 }}>{team}</span>
+  );
+}
+
+// Color-tagged checkbox (library-level integration)
+<Checkbox color="violet" label="Marketing" />;
+```
+
+- 30 named colors with bg + fg pairs: `red` / `coral` / `orange` / `amber` / `gold` / `yellow` / `olive` / `lime` / `green` / `emerald` / `mint` / `teal` / `cyan` / `sky` / `blue` / `navy` / `indigo` / `violet` / `lavender` / `purple` / `plum` / `fuchsia` / `magenta` / `pink` / `rose` / `brown` / `taupe` / `slate` / `stone` / `charcoal`.
+- `PaletteColor` is the TypeScript union; `PALETTE_COLORS` is the ordered readonly array (use for pickers / demos).
+- `paletteTokens(color)` returns `{ bg, fg }` as `var(...)` strings — use to apply palette colors in consumer-built components.
+- **Categorical, not semantic.** For status, use `<Badge tone="success" />` etc. Palette colors carry no built-in meaning.
+- Consumers own the **domain → color mapping** (e.g., per-event-namespace, per-team, per-tag). The library provides only the colors and the type surface.
+- `<Checkbox color="violet">` is the one library component that accepts palette colors out-of-the-box — tints the checked / indeterminate fill. Others (Badge, FilterChip) keep their existing semantic-tone unions; consumers build custom chips when they want palette colors.
+- The generated token contract exposes `--color-palette-<name>-bg` and `--color-palette-<name>-fg`; contributors change their source definitions in `packages/design-tokens/src/tokens.json`.