@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/CodeBlock.md

@@ -0,0 +1,67 @@
+# `<CodeBlock>` — highlighted, copyable code sample
+
+```tsx
+<CodeBlock language="json" code={'{ "id": 42 }'} />;
+
+// Persist the choice: ONE shared state for every block of the group (see below).
+const [lang, setLang] = usePersistedSample('api-lang');
+
+<CodeBlock samples={samples} activeSampleId={lang} onSampleChange={setLang} />;
+```
+
+```tsx
+// Call once at page/layout level and pass the same pair to every block.
+function usePersistedSample(storageKey: string) {
+  const [id, setId] = useState<string>();
+  // Client-only read in an effect so server and client render the same first frame.
+  useEffect(() => {
+    try {
+      setId(localStorage.getItem(storageKey) ?? undefined);
+    } catch {} // storage blocked
+  }, [storageKey]);
+  const set = (next: string) => {
+    setId(next);
+    try {
+      localStorage.setItem(storageKey, next);
+    } catch {} // storage blocked
+  };
+  return [id, set] as const;
+}
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `code` | `string` | no | Single-sample mode: the source. Ignored when `samples` is set. |
+| `language` | `(string & {}) \| CodeBlockLanguage` | no | Single-sample mode: grammar for highlighting — `'json'`, `'bash'`, `'javascript'`, `'typescript'`, `'python'`, `'go'`, `'kotlin'`, `'java'`, `'csharp'` or `'rust'` (aliases `sh`, `shell`, `js`, `ts`, `py`, `golang`, `kt`, `kts`, `cs`, `c#`, `rs`). Anything else renders as plain text. |
+| `title` | `string` | no | Header label in single-sample mode. Defaults to a one-item `samples` entry's `label`, else the language name (`JSON`, `Bash`…), else "Plain text". Also names the body (single-sample) or the sample tabs (multi-sample). |
+| `samples` | `readonly CodeBlockSample[]` | no | Multi-sample mode: 2+ samples render as tabs. Wins over `code`/`language`. |
+| `activeSampleId` | `string` | no | Controlled active sample id. Wins over `syncKey` and the user's own pick. |
+| `defaultSampleId` | `string` | no | Initial sample id when uncontrolled and nothing is synced. Defaults to the first sample. |
+| `onSampleChange` | `((id: string) => void)` | no | Called with the new id when the user picks a tab in THIS block (not when a synced block changes it). |
+| `syncKey` | `string` | no | Blocks sharing a `syncKey` switch together: picking `py` in one selects `py` in every block with the same key that has a `py` sample. In-memory, per page load; for uncontrolled blocks (controlled blocks sharing one state don't need it). |
+| `highlightLines` | `CodeBlockHighlightLines` | no | Lines to emphasise (visual only — explain the emphasis in prose). |
+| `maxHeight` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | no | Caps the body height; the body scrolls inside it (it is always a focusable, named region). `xs` 200px · `sm` 320px · `md` 448px · `lg` 640px · `xl` 800px. Default: no cap. |
+| `defaultWrap` | `boolean` | no | Initial state of the wrap-lines toggle. Default `false` (long lines scroll horizontally). |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Languages:** `json`, `bash`, `javascript`, `typescript`, `python`, `go`, `kotlin`, `java`, `csharp`, `rust` (aliases `sh`, `shell`, `js`, `ts`, `py`, `golang`, `kt`, `kts`, `cs`, `c#`, `rs`). Unknown languages render as plain text.
+- **Header label** is `title`, then the label of a one-item `samples` array, then the language name, then "Plain text".
+- **Accessibility:** the code body is always keyboard-focusable. Single mode is a `role="group"` named by the header label (`title`, else the one-item sample label, else the language name, else "Plain text"); multi mode is a tabpanel labelled by its tab, and `title` names the tablist.
+- **`highlightLines` is visual only.** Explain the emphasis in the surrounding prose.
+- **`syncKey` is in-memory** (per page load) and is for UNCONTROLLED blocks. The library never touches storage. To persist, own the choice as ONE piece of state shared by every block of the group (the `usePersistedSample` hook above, called once at page/layout level, or React context) and give every block `activeSampleId={lang}` + `onSampleChange={setLang}`. Controlled blocks don't need `syncKey`: the shared state keeps them in step. Do NOT give each block its own `useState` plus `syncKey`: the controlled `activeSampleId` wins over `syncKey`, so return visits would leave blocks out of sync. `defaultSampleId` is only the static initial choice.
+- **Sample ids** are used in DOM ids: don't put spaces in them.
+- **Active sample precedence:** controlled `activeSampleId`, then `syncKey`, then the user's own pick, then `defaultSampleId`, then the first sample. An `activeSampleId` that matches no sample id falls through to the next rule.
+- Renders identically on the server (SSR-safe).
+
+#### When NOT to use
+
+- ❌ Inline code inside a sentence: use `Code`.
+- ❌ Editable code: use `LiquidEditor` / `RichTextEditor`.
+- ❌ A language outside the list above and you expect colours: it renders as plain text.

package/docs/components/ColorPicker.md

@@ -0,0 +1,115 @@
+# `<ColorPicker>` — controlled HEX color picker (popover + inline)
+
+```tsx
+const [hex, setHex] = useState('#4F46E5');
+
+// Default popover with the built-in trigger swatch:
+<Field label="Brand color">
+  <ColorPicker value={hex} onChange={setHex} />
+</Field>
+
+// Custom trigger:
+<Field label="Brand color" description="Used for campaign accents">
+  <ColorPicker value={hex} onChange={setHex}>
+    <ColorPicker.Trigger asChild>
+      <Button variant="secondary">Pick a color</Button>
+    </ColorPicker.Trigger>
+  </ColorPicker>
+</Field>
+
+// Inline (always-visible panel — for theme builders, settings rows):
+<ColorPicker.Panel value={hex} onChange={setHex} />
+
+// With consumer-supplied preset swatches:
+<ColorPicker.Panel value={hex} onChange={setHex} presets={['#4F46E5', '#10B981', '#F59E0B', '#EF4444']} />
+```
+
+<!-- props:start -->
+
+## Props
+
+### `ColorPickerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | Current color as `#RRGGBB`. Controlled — required. |
+| `onChange` | `(hex: string) => void` | yes | Fires per drag tick + on input change + on preset click. High frequency during drags. |
+| `onChangeEnd` | `((hex: string) => void)` | no | Fires on the trailing edge of an interaction. Use for commit-style logic. |
+| `presets` | `string[]` | no | Optional preset color swatches. If provided, rendered as a grid below the hue slider in the panel. |
+| `disabled` | `boolean` | no | Disable interaction. Trigger doesn't open; panel is non-interactive. |
+| `invalid` | `boolean` | no | Marks the focusable trigger invalid for Field composition. Default: `false`. |
+| `required` | `boolean` | no | Consumed for Field composition so Field can render its visible required marker. Native buttons do not support `aria-required`, so this does not add required semantics to the trigger. Default: `false`. |
+| `aria-label` | `string` | no | Accessible name for the focusable trigger. Forwarded to the default or custom trigger, not the root wrapper. On the default trigger the current value is appended (`aria-label="Accent colour"` → "Accent colour, current value #3366FF"); the popover dialog is named by the bare `aria-label`. Ignored when `aria-labelledby` is provided. An explicit name on a custom trigger child takes precedence — but an EMPTY one on that child does not, since an empty string names nothing. |
+| `triggerLabel` | `string` | no | Accessible label for the default trigger. Defaults to the i18n value at `colorPicker.triggerLabel` (`'Pick a color'` in English) when omitted OR empty — an empty string is not an explicit name, so it takes the default too. Ignored when a custom trigger is provided via `<ColorPicker.Trigger>`. |
+| `aria-labelledby` | `string` | no | Id(s) of element(s) that label the trigger button. Forwarded onto the focusable trigger (not the root wrapper) and takes precedence over the generated `aria-label`. Set automatically when wrapped in `<Field label>`. On the default trigger a visually hidden span holding the current HEX is appended, so the name reads e.g. "Accent colour #0052CC". The popover dialog is named by these ids alone (purpose, no value). |
+| `aria-describedby` | `string` | no | Id(s) of element(s) that describe the trigger button (e.g. a Field error or helper text). Forwarded onto the focusable trigger, not the root wrapper. |
+| `popoverPlacement` | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end'` | no | Popover placement (split internally into side + align). Default `'bottom-start'`. |
+| `panelFooter` | `ReactNode` | no | Optional content rendered inside the popover, below the panel (and below its presets grid, if any) — for live feedback about the color being picked, e.g. a contrast-ratio readout that updates as the user drags. Not available on the standalone `<ColorPicker.Panel>`, which has no popover to render it inside. Not an `aria-live` region by default — announcing every drag tick would be disruptive. If the footer's text should be announced as it settles, wire that up yourself (e.g. wrap it in your own `role="status"` span); that tradeoff is the consumer's call, not the picker's default. The footer is wired as the popover dialog's `aria-describedby`, so its text is read when the dialog opens. Keep it short — it is read in full. |
+| `children` | `ReactNode` | no | Optional `<ColorPicker.Trigger asChild>` override for custom triggers. |
+| …native | | | plus native `<div>` attributes |
+
+### `ColorPickerPanelProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | Current color as `#RRGGBB`. Controlled — required. |
+| `onChange` | `(hex: string) => void` | yes | Fires per drag tick + on input change + on preset click. High frequency during drags. |
+| `onChangeEnd` | `((hex: string) => void)` | no | Fires on the trailing edge of an interaction — pointer release on the SV pad / hue slider, blur on the HEX input, preset click. Use for commit-style logic (network calls, history snapshots). |
+| `presets` | `string[]` | no | Optional preset color swatches. If provided, rendered as a grid below the hue slider. Clicking a swatch commits the color (fires both onChange and onChangeEnd). Invalid entries are silently dropped. |
+| `disabled` | `boolean` | no | Disable interaction. |
+| `framed` | `boolean` | no | Whether the panel draws its own chrome (border, shadow, padding, background, radius). Default `true` — the standalone `<ColorPicker.Panel>` needs that chrome to read as a discrete surface on a page. Set `false` when nesting the panel inside a container that already draws a frame — a `Popover.Content`, a `Card`, or your own bordered surface — so the two frames don't nest. `<ColorPicker>` renders its popover panel this way internally, for exactly this reason. |
+| …native | | | plus native `<div>` attributes |
+
+### `ColorPickerTriggerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `asChild` | `boolean` | no | Currently always behaves as `true` (the child is merged with trigger semantics via `<Popover.Trigger>`'s cloneElement). Reserved for a future Slot-style variant where `false` would wrap the child instead of merging. Documented for API stability. |
+| `children` | `ReactNode` | yes | The element to render as the trigger. Must accept `ref`, `onClick`, `id`, and ARIA attributes so ColorPicker can connect it to Field. Explicit child ARIA naming, description, and invalid state win over the parent values; ColorPicker's public `id` still owns the label association. |
+
+<!-- props:end -->
+
+- **Controlled-only.** `value: string` in `#RRGGBB` form. Loose input accepted on the HEX text field (`#FFF`, `FFF`, `#ffffff`); the component always emits the canonical `#RRGGBB` (uppercase, with `#`).
+- **The SV pad** is `role="application"` with an `aria-valuetext` describing the state (a 2D control has no standard ARIA pattern). Keyboard adjusts S/V by 1% per arrow, 10% with Shift. Use `<ColorPicker>` (not the Panel) when you need a compact trigger.
+- **Two distribution shapes via the compound API.** `<ColorPicker>` is the popover-wrapped form-field-ready widget. `<ColorPicker.Panel>` is the same picker without the popover wrapping — drop it directly into a settings page or theme builder.
+- **Default trigger** is an input-field-shaped button with a 16×16 swatch + uppercase HEX text. Override via `<ColorPicker.Trigger asChild>{customNode}</ColorPicker.Trigger>` (the child must `forwardRef` and accept `onClick` because `<Popover.Trigger>` clones it). `<ColorPicker.Trigger>` renders nothing itself; it is a marker child that `<ColorPicker>` reads from its `children`, so it only has meaning inside `<ColorPicker>`.
+- **Field-ready.** `<Field label>` connects `id`, naming, description, and invalid state to either the default or custom trigger rather than the role-less picker wrapper. `required` remains a visible Field marker; native trigger buttons do not expose `aria-required` because that state is unsupported for buttons.
+- **`onChange` fires per drag/zoom tick (high frequency).** Use `onChangeEnd` for commit-style logic (network calls, history snapshots) — it fires on pointer release, slider release, HEX input blur, and preset click.
+- **Presets via `presets?: string[]`.** Invalid entries are dropped silently. The library doesn't ship a default palette — pass your own brand colors. Selected swatch gets an inset ring + check overlay.
+- **Color math is exported.** `hexToHsv(hex)`, `hsvToHex({h,s,v})`, `normalizeHex(loose)` are usable directly for downstream theme builders, contrast calculators, etc.
+- **Keyboard (SV pad)**: arrows ±1% S/V, Shift+arrow ±10%, Home/End for S=0/100, PageUp/Down for V=100/0.
+- **Keyboard (hue slider)**: inherits Slider's keyboard — arrows ±1°, PgUp/Dn ±10°, Home/End for 0°/360°.
+- **Popover placement** via `popoverPlacement?: 'bottom-start' | 'bottom' | 'top-start' | ...`. Default `'bottom-start'`.
+- **Disabled** dims the panel, sets `aria-disabled` on the SV pad, disables the slider + input, makes presets non-interactive. Trigger doesn't open.
+- **`panelFooter?: ReactNode`** — rendered inside the popover below the panel (and below presets). For live feedback about the color being picked, e.g. a contrast-ratio readout that updates as the user drags. Not available on the standalone `<ColorPicker.Panel>` (no popover to render it inside). Not an `aria-live` region by default — if the text should be announced as it changes, wrap it in your own `role="status"` span; announcing every drag tick would be disruptive by default. It IS the popover dialog's `aria-describedby`, so it's read once when the dialog opens.
+- **Accessible names.** Under `<Field label>` / `aria-labelledby` the default trigger's name is the label plus the current value ("Accent colour #0052CC"). An explicit `aria-label` on the default trigger also gets the value appended ("Accent colour, current value #0052CC"). The popover dialog is named by the trigger's purpose (Field label / `aria-label` / `triggerLabel`), no value — don't add your own `Popover.Heading` via `panelFooter` to name it.
+- **`<ColorPickerPanel>` (`<ColorPicker.Panel>`) takes `framed?: boolean`, default `true`.** `framed={false}` drops the panel's own chrome (border, shadow, padding, background, radius) — use it when nesting the panel inside something that already draws a frame (your own `Popover.Content`, a `Card`). `<ColorPicker>` renders its popover panel with `framed={false}` internally so the popover shows exactly one frame; a standalone `<ColorPicker.Panel>` keeps its frame by default.
+- **`invalid` now paints the default trigger's border AND its focus ring**, not just `aria-invalid` — `.trigger[aria-invalid=true]` uses the same danger primitive as `Input invalid` for both: the border (`--color-picker-trigger-border-color-invalid`, same primitive as `--input-border-color-invalid`, and it survives `:hover`) and the `:focus-visible` ring (`--color-picker-trigger-ring-invalid`, same primitive as `--input-ring-invalid`, both `var(--ring-danger)`) — each reached through ColorPicker's own component token, never a direct `--input-*` read.
+
+#### Color math API
+
+```ts
+import { hexToHsv, hsvToHex, normalizeHex } from '@eocrm/design-system';
+
+normalizeHex('#fff'); // '#FFFFFF'
+normalizeHex('orange'); // null
+
+hexToHsv('#FF0000'); // { h: 0, s: 100, v: 100 }
+hexToHsv('not a color'); // null
+
+hsvToHex({ h: 240, s: 100, v: 100 }); // '#0000FF'
+```
+
+#### Hard rule
+
+- ❌ Passing non-HEX `value` — named colors, `rgb()`, `hsl()`, alpha hex (`#RRGGBBAA`). Convert in the consumer or use the exported `normalizeHex` first. Invalid input falls back to `#000000` with a dev-only warning.
+- ❌ Using `<ColorPicker.Trigger>` outside `<ColorPicker>`.
+- ❌ Reaching into the picker's internal HSV state. Consumer contract is HEX-only.
+- ❌ Hand-rolling a color picker per page. Use this.
+- ❌ Bundling a default palette inside the consumer. Pass via `presets`.
+- ❌ Calling expensive work in `onChange`. Use `onChangeEnd` (one fire per gesture).
+- ❌ Wrapping a non-`forwardRef` component in `<ColorPicker.Trigger asChild>`. `<Popover.Trigger>` clones the child to inject the ref; non-forwardRef silently drops it.
+- ❌ Forgetting to wire `disabled` into the consumer's custom trigger element. The picker dims its wrapper and blocks pointer events (`pointer-events: none`), but the trigger button's own disabled visuals are the consumer's responsibility.

package/docs/components/ConfirmationPopover.md

@@ -0,0 +1,70 @@
+# `<ConfirmationPopover>` — opinionated "Are you sure?" preset
+
+```tsx
+<ConfirmationPopover
+  title="Delete record?"
+  description="This action cannot be undone."
+  confirmLabel="Delete"
+  variant="danger"
+  onConfirm={async () => {
+    await api.deleteRecord(id);
+  }}
+>
+  <Button variant="danger">Delete</Button>
+</ConfirmationPopover>
+
+// Default variant: lighter-weight (archive, publish, etc.)
+<ConfirmationPopover
+  title="Archive this contact?"
+  description="You can unarchive later from the archive view."
+  onConfirm={() => archive(id)}
+>
+  <Button variant="secondary">Archive</Button>
+</ConfirmationPopover>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | The trigger element. Same forwardRef-required contract as `<Popover.Trigger>` — `<Button>` qualifies; a custom component without `forwardRef` does not. |
+| `title` | `string` | yes | Heading text. Renders inside `<Popover.Heading>` (an `<h3>`) and wires `aria-labelledby` on the dialog automatically. |
+| `description` | `ReactNode` | no | Optional body text below the title. When provided, wires `aria-describedby` so screen readers announce it. |
+| `confirmLabel` | `string` | no | Confirm button label. Defaults to the i18n value at `confirmationPopover.confirm` (`'Confirm'` in English). An EMPTY string counts as unset, not as an explicit blank: this label is the confirm button's only name source (the pending spinner beside it is `aria-hidden`), so an empty one would leave the button anonymous. |
+| `variant` | `'default' \| 'danger'` | no | `'danger'` makes Confirm a danger-variant button. Defaults to `'default'` (primary). |
+| `onConfirm` | `() => void \| Promise<void>` | yes | Async-aware confirm handler. May return a Promise; while pending, both buttons disable, the Confirm button shows a small spinner, and Escape / click-outside dismissal is blocked. - Resolve → popover closes. - Reject → popover stays open, buttons re-enable. `onCancel` is NOT fired (the user neither confirmed nor cancelled — it's an error state owned by the consumer). The consumer is expected to surface error feedback externally (toast, inline message, etc.). ConfirmationPopover does NOT render errors. |
+| `onCancel` | `(() => void)` | no | Optional. Fires on Cancel click, Escape, or click-outside dismissal. NOT fired if `onConfirm` rejects. |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | no | Direct initial focus into the panel's content instead of the default Cancel button — e.g. an `<Input>` rendered in `description` for a rename flow. When provided and its `.current` is non-null on open, the component focuses this element after the panel mounts (skipping the Cancel-focus). Tip: add `onFocus={(e) => e.currentTarget.select()}` to a text input to select its contents so the user can type/replace immediately. |
+| `returnFocusRef` | `RefObject<HTMLElement \| null>` | no | Where focus goes when the popover closes. Default: back to the trigger. That default breaks whenever the trigger is gone by close time — the confirmed action deleted the row that owned it — and focus lands on `<body>`, so 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 left the document, focus falls back to the trigger (when it still exists). It applies when the popover closes via Confirm, Cancel or Escape. An outside click never restores focus — focus stays wherever the click put it (on a control, or `<body>` for an inert area). A ref that is set statically (not only inside `onConfirm`) ALSO fires when the user closes by clicking the trigger again, pulling focus off the trigger. To return to the trigger on Cancel / toggle and only move elsewhere after a confirm, aim the ref inside `onConfirm` and clear it in `onOpenChange(true)`. If focus is already on some other live element when the popover closes, it is left alone. The target is scrolled into view with `{ block: 'nearest' }` (a no-op when it is already visible) — it may be far from where the user was. |
+| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` | no | Preferred side. Default `'top'` — confirmations anchor above the trigger by convention. |
+| `align` | `'start' \| 'end' \| 'center'` | no | Edge alignment. Default `'center'`. |
+| `sideOffset` | `number` | no | Gap in px between trigger and panel. Default `10`. |
+| `open` | `boolean` | no | Controlled open state. Pair with `onOpenChange`. |
+| `onOpenChange` | `((open: boolean) => void)` | no | Open-change callback. Required when `open` is provided. |
+| `defaultOpen` | `boolean` | no | Default open state for uncontrolled usage. Defaults to `false`. |
+
+<!-- props:end -->
+
+- Built on top of `<Popover>`. Declarative: `title` / `description` / `confirmLabel` / `cancelLabel` / `variant` / `onConfirm` / `onCancel`.
+- **Initial focus on Cancel** for both variants — keyboard Enter never accidentally confirms. Tab once to Confirm.
+- **`initialFocusRef`** (`RefObject<HTMLElement | null>`) overrides the Cancel default: directs initial focus into the `description` content instead — e.g. an `<Input>` rendered there for a rename flow. The component focuses `initialFocusRef.current` after the panel mounts (mirrors `<Modal>`'s `initialFocusRef`). Tip: add `onFocus={(e) => e.currentTarget.select()}` to a text input so its contents are selected on open and the user can type a replacement immediately.
+- **Async-aware** `onConfirm`. May return a Promise. While pending, both buttons take `aria-disabled` (NOT the native `disabled`, which would drop them from the tab order and blow away focus mid-operation), their handlers no-op, Confirm shows a spinner, the pending state is announced, and Escape / click-outside are blocked.
+- **Failure mode**: on reject, popover stays open and buttons re-enable. Consumer surfaces the error externally — ConfirmationPopover does NOT render inline errors.
+- **Return focus** (`returnFocusRef`): on Confirm, Cancel and Escape focus returns to `returnFocusRef` when it is connected, otherwise to the trigger. Unlike `<Modal>`, an outside click never restores focus — it stays wherever the user clicked. `returnFocusRef` is read at CLOSE time. A statically-set ref also fires when the user closes by clicking the trigger again; to apply it only after a successful confirm, set it in `onConfirm` and clear it in `onOpenChange(true)`. A named target is scrolled into view with `{ block: 'nearest' }`.
+- Anchors above the trigger by default (`side="top"`).
+- **From a DropdownMenu item (kebab Delete pattern).** Wrap a `<DropdownMenu.Item closeOnSelect={false}>` as the trigger — clicking anywhere on the row opens the confirmation. The menu stays open until the user dismisses it (Escape or click outside). To close the menu after the action resolves, drive `DropdownMenu`'s `open` state externally and call `setMenuOpen(false)` inside `onConfirm` — and pass `returnFocusRef={kebabTriggerRef}` (the menu's trigger), because closing the menu unmounts the item that is the popover's trigger, so focus would otherwise drop to `<body>`.
+
+#### When NOT to use
+
+- ❌ A multi-step flow ("type the name to confirm") → `Modal`. This is for one-tap confirmations.
+- ❌ A non-blocking heads-up that needs no yes/no answer → a Toast or inline UI.
+
+#### Anti-patterns
+
+- ❌ A hanging-forever `onConfirm` Promise. There is no timeout; the popover stays pending indefinitely, so add a timeout / abort inside your `onConfirm` if the operation may stall.
+- ❌ Expecting the rejection to render inside the popover body. Surface errors via toast or page-level UI.
+- ❌ Controlled `open` while relying on pending-blocks-close. With `open` / `onOpenChange` you can force-close from outside while pending; coordinate `pending` in your own code if that matters.
+- ❌ Letting a confirmed delete remove the trigger with no `returnFocusRef`: focus drops to `<body>`. Aim the ref at the next row's trigger (or the empty state) inside `onConfirm`.

package/docs/components/Constrain.md

@@ -0,0 +1,39 @@
+# `<Constrain>` — size / flex constraint
+
+```tsx
+<Constrain maxWidth="sm"><Input placeholder="Search…" /></Constrain>
+
+<Constrain height="viewport-70" maxHeight="lg"><FlowCanvas /></Constrain>
+
+<Cluster wrap={false} gap="sm">
+  <Constrain flex="grow"><Progress value={x} max={y} /></Constrain>
+  <Button>Upgrade plan</Button>
+</Cluster>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `width` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | no | Fixed width — a named step (`xs` 200 / `sm` 320 / `md` 448 / `lg` 640 / `xl` 800px, via `--measure-*` tokens) or `'full'` (100%). |
+| `minWidth` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | no | Minimum width floor — a named step or `'full'` (100%). |
+| `maxWidth` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | no | Maximum width cap — the common case (e.g. a search input at `'sm'`). |
+| `height` | `'viewport' \| 'viewport-70' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xs' \| 'full'` | no | Fixed height — a named measure (same scale as the widths), `'full'` (100%), `'viewport'` (100dvh), or `'viewport-70'` (70dvh). `height="viewport-70"` with `maxHeight="lg"` makes a viewport-relative panel that never exceeds 640px. |
+| `minHeight` | `'viewport' \| 'viewport-70' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xs' \| 'full'` | no | Minimum height floor — a named measure, `'full'`, `'viewport'`, or `'viewport-70'`. |
+| `maxHeight` | `'viewport' \| 'viewport-70' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xs' \| 'full'` | no | Maximum height cap — a named measure, `'full'`, `'viewport'`, or `'viewport-70'`. |
+| `flex` | `'grow' \| 'shrink' \| 'auto' \| 'none'` | no | Flex behavior as a child of a flex row/column. - `'grow'` — fill remaining space (`flex: 1 1 0`) and shrink below content width (`min-width: 0`) so a truncating child (`<Text truncate>`) can clip. To opt a `Stack`/`Cluster` into that truncating chain WITHOUT also making it fill the row, use their `minWidth0` prop instead — and note Constrain renders a `<div>`, so it is invalid inside a `<button>`/`<a>`/`<label>`, where `<Cluster as="span" minWidth0>` is the only option. - `'auto'` — size to content, may grow/shrink (`flex: 1 1 auto`). - `'shrink'` — don't grow, may shrink (`flex: 0 1 auto`, the flex default). - `'none'` — fixed, never grow/shrink (`flex: 0 0 auto`). Omit for no flex class: the element behaves as its flex container dictates. |
+| `children` | `ReactNode` | yes | The content to size. Required — a Constrain with nothing inside has nothing to constrain. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- The one place width/height/flex sizing lives — `Stack`/`Cluster`/`Grid` are spacing-only (Rule 4). Constrain sizes its **own** box; it does not arrange children (put a `Cluster`/`Stack` inside).
+- No padding/border/background — for those use `<Card>`; for a full-bleed shell use `<Screen>`.
+
+#### Anti-patterns
+
+- ❌ Reaching for Constrain to add `margin` / `padding`. It carries size/flex only; spacing comes from the parent layout primitive.
+- ❌ Spacing or arranging children: use `<Stack>` / `<Cluster>` / `<Grid>`.

package/docs/components/CurrencySelect.md

@@ -0,0 +1,57 @@
+# `<CurrencySelect>`
+
+Currency picker over the DS `Select`: you pass the ISO 4217 `currencies` to offer (required, in display order); it renders `CODE — Name` rows with localized names (`Intl.DisplayNames`). Single mode is controlled on `value: string | null` / `onChange(code | null)`; `multiple` switches to `string[]` (with `triggerDisplay` `"chips"` / `"summary"`). `currencyDisplay` sets how the SELECTED currency shows in the trigger: `"code"` (default, `EUR`), `"symbol"` (`€`) or `"both"` (`EUR €`). Search turns on automatically above 7 currencies (`searchable` overrides) and matches code, name and symbol. Invalid codes are dropped with a dev warning. `size`/`invalid`/`disabled`/`clearable`/`name` etc. pass through to `Select`.
+
+```tsx
+const [cur, setCur] = useState<string | null>('EUR');
+<CurrencySelect
+  currencies={['EUR', 'USD', 'GBP']}
+  value={cur}
+  onChange={setCur}
+  aria-label="Currency"
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `currencies` | `string[]` | yes | ISO 4217 codes to offer, in display order (e.g. `['USD', 'EUR']`). Required; there is no "all currencies" default. Invalid codes are dropped with a dev warning. |
+| `currencyDisplay` | `'code' \| 'symbol' \| 'both'` | no | How the SELECTED currency renders in the trigger. Default `"code"`. - `"code"` — `EUR`. - `"symbol"` — `€`. - `"both"` — `EUR €`. Dropdown rows always read `CODE — Name` so they stay identifiable and searchable. |
+| `locale` | `string` | no | BCP-47 locale for currency names and symbols. Defaults to the active i18n locale (`useLocale()`). |
+| `searchable` | `boolean` | no | Show a search input. Default: on when more than 7 currencies are offered. |
+| `multiple` | `false \| true` | no | Single mode (default). |
+| `value` | `string \| null \| string[]` | yes | Controlled ISO code; `null` = nothing selected. |
+| `onChange` | `(code: string \| null) => void \| (codes: string[]) => void` | yes | Fires with the picked code, or `null` when cleared. |
+| `triggerDisplay` | `'summary' \| 'chips'` | no | How selections render in the trigger: `"chips"` (default) or `"summary"`. |
+| `id` | `string` | no | Placed on the combobox trigger (the `<button>` / `<input>`), not the wrapper div, so a `<label for>` — Field / SettingRow wire one — focuses the control when clicked. Default: a generated id. Target the wrapper by `className` or a `data-*` attribute, not `#id`. |
+| `selectOnOpen` | `boolean` | no | When the searchable combobox opens, select the current text so the user can immediately type to replace it (type-to-search). Default `false`. Only affects the single searchable trigger. |
+| `open` | `boolean` | no | Controlled open state. Pair with `onOpenChange`. Omit both to let Select own its open state (the common case). |
+| `defaultOpen` | `boolean` | no | Initial open state for uncontrolled usage. Defaults to `false`. |
+| `onOpenChange` | `((open: boolean) => void)` | no | Fires whenever Select wants to change open state. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Trigger height + type scale. See `SelectSize`. Defaults to `'md'`. |
+| `invalid` | `boolean` | no | Marks the trigger as invalid — applies the error border + sets `aria-invalid="true"`. Pair with an external error message linked via `aria-describedby`. |
+| `placeholder` | `string` | no | Placeholder shown when nothing is selected. In searchable mode, also the input's `placeholder` until the user types. |
+| `clearable` | `boolean` | no | Shows a `✕` button in the trigger that clears the selection. Opt-in: defaults to `false`. Always forced `false` when `disabled` or `readOnly`. "Clear" means "reset to the empty value" (`''` / `[]`), so the button only appears when the current value differs from that. A Select whose selected option IS `value: ''` is already at the cleared value and shows no ✕; a value matching no option (a stale id) does show one. |
+| `disabled` | `boolean` | no | Disables the trigger entirely — non-interactive, dimmed, focusable only via assistive tech. Hidden form inputs are also disabled. |
+| `readOnly` | `boolean` | no | Read-only — trigger is focusable but cannot open or change the selection. Useful for displaying a value inside a form that's not yet editable. |
+| `name` | `string` | no | Name attribute for native form submission. In multi mode, one hidden `<input>` per selected value is emitted (so `FormData.getAll(name)` returns the array). |
+| `required` | `boolean` | no | Marks the field as required. The trigger exposes `aria-required="true"` to assistive technology. Hidden inputs still serialize named values, but they do not participate in native constraint validation; validate the selection in your form layer. |
+| `form` | `string` | no | `form` attribute forwarded to the hidden `<input>` elements. |
+| `aria-label` | `string` | no | Accessible name for the trigger. Use this when a visible `<label>` is not present. Mutually exclusive with `aria-labelledby`. |
+| `aria-labelledby` | `string` | no | ID of an element that labels the trigger. Use when the label is a sibling node (e.g. a `<Field>` label). |
+| `aria-describedby` | `string` | no | ID of an element that describes the trigger — e.g. an error message or helper hint paired with `invalid`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+**When NOT to use:** an amount plus its currency — use `MoneyInput`. A generic option list — use `Select`.
+
+**Anti-patterns**
+
+- ❌ Passing `options`, `renderOption` or `creatable` — options are derived from `currencies`.
+- ❌ Expecting an "all currencies" default — `currencies` is required; an empty list renders an empty picker.
+- ❌ Passing lowercase or made-up codes — they are dropped (dev warning).

package/docs/components/CursorPagination.md

@@ -0,0 +1,43 @@
+# `<CursorPagination>` — prev / next for streams without total
+
+```tsx
+<CursorPagination hasPrevious={hasPrev} hasNext={hasNext} onPrevious={loadPrev} onNext={loadNext} />
+
+// Activity feed with reversed direction labels
+<CursorPagination
+  hasPrevious={hasNewer}
+  hasNext={hasOlder}
+  onPrevious={loadNewer}
+  onNext={loadOlder}
+  previousLabel="Newer"
+  nextLabel="Older"
+/>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `hasPrevious` | `boolean` | yes | Whether a previous page exists. When `false`, the previous button is rendered as `disabled` (layout stays stable; consumer doesn't have to conditionally hide it). |
+| `hasNext` | `boolean` | yes | Whether a next page exists. |
+| `onPrevious` | `() => void` | yes | Called when the user clicks previous (not fired when disabled). |
+| `onNext` | `() => void` | yes | Called when the user clicks next (not fired when disabled). |
+| `previousLabel` | `ReactNode` | no | Label for the previous button. Defaults to the i18n value at `pagination.previous` (`'Previous'` in English). Override for domain phrasing (`'Newer'` in a reverse-chronological feed). An EMPTY string counts as unset, not as an explicit blank: this label is the button's only name source (the chevron is `aria-hidden`), so an empty one would leave the button anonymous rather than merely unlabelled. |
+| `nextLabel` | `ReactNode` | no | Label for the next button. Defaults to the i18n value at `pagination.next` (`'Next'` in English). An EMPTY string counts as unset, for the same reason as `previousLabel`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Visual size — `'sm'` / `'md'` (default) / `'lg'`. Shares the `<Pagination>` size scale so the two components match when used alongside each other. |
+| `disabled` | `boolean` | no | When `true`, both buttons are disabled regardless of has-prev/-next. |
+| `aria-label` | `string` | no | Accessible name for the wrapper `<nav>`. Defaults to the i18n value at `pagination.ariaLabel` (`'Pagination'` in English) when omitted OR empty — an empty string is not an explicit name, so it takes the default too. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- Two-button prev / next nav for keyset-paginated streams (activity feeds, infinite scroll, cursor-based APIs). Controlled — consumer owns the cursor + `has-prev` / `has-next` flags.
+- Buttons render as native `<button disabled>` when `hasPrevious` / `hasNext` is false — no layout shift; consumer doesn't have to conditionally hide them.
+- Shares the `<Pagination>` size scale (`sm` / `md` / `lg`).
+- Use `<Pagination>` (numbered) when you have a known total page count. CursorPagination is for streams.
+
+- A11y: the wrapper is `<nav aria-label="Pagination">` (overridable for disambiguation). Disabled buttons are native, so screen readers announce "dimmed" and skip them in Tab order.
+- Use `<Pagination>` (numbered, with jump-to-page and progress indication) when you have a total page count.

package/docs/components/DashboardCanvas.md

@@ -0,0 +1,79 @@
+# `<DashboardCanvas>` — 2D snap-grid dashboard
+
+Datadog-style 2D snap-grid dashboard. `value` is `{ items: DashboardPlacement[], sections: DashboardSection[] }` — top-level items plus an ordered array of full-width collapsible sections, each with its own sub-grid on the same column count (`columns` prop, default 24 — pass `columns={12}` for layouts saved against a 12-column schema like the eocrm layout-v2 spec; placements are NOT converted between column counts). Always controlled, no uncontrolled mode: `onChange(next)` fires once per completed gesture (a drop, a resize end, a collapse toggle, a band reorder, a cross-container move) with the whole engine-computed next value; omit it for a static layout — drags still preview live but nothing persists past pointerup. `renderItem(id)` renders every item's body — including items inside a COLLAPSED section, whose body stays mounted and `inert` rather than unmounting, so a widget that fetches on mount pays that cost even while collapsed — called once more for the drag ghost mid-gesture, so keep it pure. **The grid cell is chrome-less** (no background/border/radius/shadow, no minimum height beyond its `h` row-span) — wrap the return in `<Card>` for the boxed widget look, and size the content to the cell or accept bare (dotted, in edit mode) space showing below a shorter widget. `renderSectionHeader(id)` adds small extras (a title editor, a `DropdownMenu` trigger) to the right of a section's title, in the same `Accordion.Trigger` `actions` slot as the section's own band-reorder grip handle — neither ever starts a collapse toggle or a drag. `highlightedSectionId` highlights a section's band with a ring and outward waves (scrolls it into view first, works on collapsed bands, never moves focus) — set it to the id of a section you just added and clear it in `onSectionHighlightDone`; setting the same id again after that re-triggers. `constraints` — a `Record<id, { minW?, minH?, maxH? }>` or a `(id) => constraints | undefined` function — clamps resize gestures per item; unlisted items default to `minW: 1`, `minH: 1`, no `maxH`. Section bands compose the DS `Accordion` (`type="multiple"`) for their header/chevron/panel look; edit mode (not `readOnly`, not below `stackBelow`) also shows a snap-grid of dots on each container so a drag/resize's destination cell is visible before you commit.
+
+Gestures: drag-to-move with push-down collision + live compaction preview (dropping on the upper/lower half of another widget inserts before/after it, so stacked widgets reorder without gaps; during a move-drag each container gains trailing drop space the height of the dragged item, and the drag ghost stays inside the canvas), E/S/SE resize handles, cross-container drag (top level ↔ any expanded section), and vertical band reorder by dragging a section header. Full keyboard: Tab to an item, Enter/Space picks it up, arrows move it (crossing a container's edge moves it into the next band), Shift+arrows resize, Enter/Space drops, Escape cancels; Shift+arrows on a focused section header reorders bands.
+
+```tsx
+const [value, setValue] = useState<DashboardCanvasValue>(initialLayout);
+
+<DashboardCanvas
+  value={value}
+  onChange={setValue}
+  renderItem={(id) => <Card>{widgets[id].title}</Card>}
+  constraints={{ kpi: { minW: 2, maxH: 4 } }}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `DashboardCanvasValue` | yes | The controlled layout: top-level items plus an ordered array of collapsible sections. `DashboardCanvas` never mutates this value — every change flows out through `onChange`. |
+| `onChange` | `((next: DashboardCanvasValue) => void)` | no | Fires once per completed gesture — a drop, a resize end, a collapse toggle, a section reorder, or a cross-container move — with the whole next `value`. Omit for a read-only or fully static canvas; without it, drags preview live but nothing persists on drop. |
+| `renderItem` | `(id: string \| number) => ReactNode` | yes | Renders the body of an item by id. Called for every item on every render — including items inside a COLLAPSED section (its body stays mounted and `inert`, not unmounted, so Accordion's own collapse animation has real content to animate) — and once more for the dragged item mid-gesture (the cursor-following ghost). Keep it pure; a widget that fetches on mount pays that cost even while its section is collapsed. The cell itself is a bare positioned box with no background/border/radius/shadow of its own and no minimum height beyond its `h` row-span — that chrome belongs here, in whatever this returns (typically a `<Card>`); size the content to the cell, or accept that a shorter widget in a taller cell shows bare (dotted, in edit mode) space below it. |
+| `renderSectionHeader` | `((id: string \| number) => ReactNode)` | no | Optional extra controls in a section's header (a title editor, a `DropdownMenu` trigger) rendered by section id, to the right of the title. Keep it small — the header row is not a general-purpose toolbar. Pointer presses inside the slot never start a band-reorder drag. |
+| `highlightedSectionId` | `string \| number` | no | Id of a section whose band to highlight (scrolls into view, then a ring with outward waves, same as `Highlight`) — e.g. a section the user just added. Collapsed bands highlight too. Does not move focus. Clear it in `onSectionHighlightDone`; setting the same id again after that re-triggers. |
+| `onSectionHighlightDone` | `(() => void)` | no | Fires once the highlight run on `highlightedSectionId` has finished. |
+| `constraints` | `DashboardCanvasConstraintsProp` | no | Per-item size constraints, consulted when clamping resize gestures. |
+| `columns` | `number` | no | Column count of every container grid (top level and each section's sub-grid). All placement/resize bounds clamp against it. Minimum 1; fractional or sub-1 values are the consumer's bug, not validated. Layouts are NOT converted between column counts — a `value` saved at one `columns` renders at half width when the count doubles. Schemas written for the earlier 12-column grid (e.g. the eocrm layout-v2 spec) either pass `columns={12}` to match, or migrate their saved placements to 24. Default: `24`. |
+| `stackBelow` | `'sm' \| 'md' \| 'lg'` | no | Container width at (inclusive) and below which every container grid re-templates to one column and pointer + keyboard editing turns off: `sm` 480px / `md` 640px / `lg` 768px, measured against the canvas's OWN width (container query), not the viewport. Section collapse toggles keep working at any width. Default: `'md'`. |
+| `readOnly` | `boolean` | no | View-only mode: identical geometry, but no drag/resize wiring, no resize handles, and no keyboard editing — the canvas renders `value` and lets section collapse toggles keep working. The canvas also disables editing on its own, without this prop, once its own width drops to or below the `stackBelow` breakpoint (single-column stack) — `readOnly` is for a consumer-chosen view mode, the width gate is automatic. Default: `false`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+**Cells are SQUARE by default**: the row unit derives from the canvas's own width (`(width - (columns - 1) * gap) / columns`), so cell height == cell width at every size and the whole layout scales fluidly — override `--dashboard-canvas-row` with a fixed length for fixed-height rows (`--dashboard-canvas-row-stacked`, default 48px, is the row unit of the single-column stack, where the square unit would be uselessly tiny).
+
+`readOnly` turns off all editing (no handles, no keyboard editing) while section collapse toggles keep working — collapse is navigation, not editing. Independent of `readOnly`, at and below the `stackBelow` breakpoint (`'sm'` 480px / `'md'` 640px, the default / `'lg'` 768px) of the canvas's OWN width (a CSS container query, not the viewport) every container automatically re-templates to one column and editing turns off the same way — a `ResizeObserver` mirrors the breakpoint so a gesture can never half-start below it.
+
+When NOT to use: a single ordered list (priority queue, simple reordering) — use `Sortable`; fixed kanban-style columns — use `Kanban`; a free-form node/edge graph — use `FlowCanvas`. The canvas is ALWAYS a size container (named `dashboard-canvas`, unconditionally) — give it a parent with a concrete width; an intrinsic-width context (a `Cluster` item, `width: max-content`) renders it at width 0, same caveat as Grid's `collapseBelow`.
+
+A collapsed section's band is NOT a drop target — expand it first (no hover-to-expand). Escape or a pointer cancel mid-gesture restores the current `value` without firing `onChange`.
+
+#### Anti-patterns
+
+- ❌ Treating `value` as uncontrolled — passing it once with no `onChange`. Drags and resizes still preview live, but nothing persists past pointerup; the next render snaps the item back to the stale `value`.
+- ❌ Nesting a `DashboardCanvas` inside another one's `renderItem`: a nested canvas fights its parent for pointer capture and Escape handling.
+- ❌ Expecting the grid cell to draw a card-like surface. It is chrome-less by design so widgets with transparent bodies (charts, images) don't sit inside a redundant box — wrap `renderItem`'s output in `<Card>` for the boxed look.
+- ❌ Using it for a simple ordered list — see "When NOT to use" above.
+- ❌ Placing it in an intrinsic-width parent (a `Split` aside's default `auto` track, a `Cluster` item): the canvas is always a size container and renders at width 0. At and below `stackBelow` pointer + keyboard editing turns off (handles hidden, items not editing-focusable).
+
+#### More examples
+
+```tsx
+// Persist every completed gesture: keep the canvas controlled AND save.
+// Debounce / fire-and-forget is the caller's job.
+const handleChange = (next: DashboardCanvasValue) => {
+  setValue(next);
+  saveDashboardLayout(dashboardId, next);
+};
+
+// Read-only record view — same value shape, no editing affordances.
+<DashboardCanvas
+  value={savedLayout}
+  renderItem={(id) => <Card>{widgets[id].title}</Card>}
+  readOnly
+/>
+
+// Constraints computed from data, e.g. locking size for chart widgets.
+<DashboardCanvas
+  value={value}
+  onChange={setValue}
+  renderItem={(id) => <Card>{widgets[id].title}</Card>}
+  constraints={(id) => (widgets[id]?.kind === 'chart' ? { minW: 4, minH: 3, maxH: 6 } : undefined)}
+/>
+```