@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/ChatLauncher.md

@@ -0,0 +1,97 @@
+# `<ChatLauncher>` — floating launcher + non-modal chat panel
+
+A fixed bottom-end icon button that toggles a chat panel above it. The panel is a `role="dialog"` **without** `aria-modal`: no focus trap, backdrop or scroll lock, so the page stays usable while chatting. It is portaled to `document.body` and layered on `--z-chat-launcher` (above app chrome, below dropdowns, popovers and modals). Controlled only: `open` + `onOpenChange`.
+
+```tsx
+import { useRef, useState } from 'react';
+import { Sparkles, Send } from 'lucide-react';
+import {
+  Button,
+  ChatBubble,
+  ChatLauncher,
+  Cluster,
+  Constrain,
+  Textarea,
+} from '@eocrm/design-system';
+
+const [open, setOpen] = useState(false);
+const composerRef = useRef<HTMLTextAreaElement>(null);
+
+<ChatLauncher
+  label="Ask Scout"
+  title="Scout"
+  icon={<Sparkles size={20} aria-hidden="true" />}
+  open={open}
+  onOpenChange={setOpen}
+  initialFocusRef={composerRef}
+  footer={
+    // One row: the Textarea grows (autoGrow, up to 4 rows), the send button keeps its size.
+    <Cluster wrap={false} gap="sm" align="end">
+      <Constrain flex="grow">
+        <Textarea
+          ref={composerRef}
+          aria-label="Message"
+          minRows={1}
+          maxRows={4}
+          onKeyDown={(e) => {
+            // Enter sends, Shift+Enter is a newline; never send mid-IME-composition.
+            if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
+              e.preventDefault(); // no stray newline after the draft is cleared
+              send(e);
+            }
+          }}
+        />
+      </Constrain>
+      <Button variant="primary" iconOnly aria-label="Send" onClick={send}>
+        <Send size={16} aria-hidden="true" />
+      </Button>
+    </Cluster>
+  }
+>
+  <ChatBubble.List aria-label="Conversation with Scout">
+    {messages.map((m) => (
+      <ChatBubble key={m.id} from={m.from}>
+        {m.text}
+      </ChatBubble>
+    ))}
+    {waiting && <ChatBubble from="assistant" pending />}
+  </ChatBubble.List>
+</ChatLauncher>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | yes | Accessible name of the launcher button — names the assistant ("Ask Scout"). |
+| `open` | `boolean` | yes | Whether the panel is open. Controlled only: pair with `onOpenChange`. |
+| `onOpenChange` | `(open: boolean) => void` | yes | Called with the requested state: launcher toggle, close button, Escape. |
+| `icon` | `ReactNode` | yes | Launcher glyph (e.g. a lucide icon with `aria-hidden`). |
+| `title` | `ReactNode` | yes | Panel header text; also the dialog's accessible name. |
+| `children` | `ReactNode` | yes | Scrolling body — usually a `<ChatBubble.List>`. Stays mounted while closed. |
+| `footer` | `ReactNode` | no | Pinned area below the body — the composer (`Textarea` + send `Button`). |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | no | Element focused when the panel opens (point it at the composer). Default: the panel itself. Focus already inside the panel is not moved. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Stays mounted when closed.** The panel gets `hidden`; children are not unmounted, so an uncontrolled draft and the scroll position survive close/reopen.
+- **Sticks to the bottom.** While open, the body follows new content if the user was already at (within 24px of) the bottom; a user scrolled up to read is not moved. Reopening scrolls to the bottom if it was at the bottom when closed (replies that arrived meanwhile are in view), otherwise restores the saved position.
+- **Focus.** Opening moves focus to `initialFocusRef` (point it at the composer), else to the panel; focus already inside is left alone. Escape (inside the panel or on the launcher) and the close button close it and return focus to the launcher. A programmatic close returns focus only if it was inside the chat. An Escape a child already handled (`event.preventDefault()`, e.g. a menu closing itself) is ignored.
+- The close button's name is the `chatLauncher.close` i18n key (no label prop). `label` names your assistant and is the launcher's accessible name.
+- `ref`, `className`, `id` and other native attributes go to the panel; `role`, `hidden`, `aria-labelledby` and `tabIndex` always win.
+- **Closed means silent.** While closed, the `role="log"` sits in a `hidden` subtree, so replies that arrive then are not announced (and there is no unread badge). On reopen they are in view at the bottom if the chat was left scrolled to the bottom; otherwise the saved scroll position is restored. If a reply must reach the user while the chat is closed, announce it yourself (e.g. a `toast` — with the viewport at a top position, see below).
+- **Toasts share the corner.** `ToastViewport` defaults to `bottom-right`, above the launcher's layer, so toasts would cover the launcher and the open panel's composer. On a page with a ChatLauncher, use `<ToastViewport position="top-right" />` (or another top position).
+- Size: `--chat-launcher-panel-width` (380px) × `--chat-launcher-panel-height` (560px), capped to the viewport minus `--chat-launcher-inset`.
+
+**When NOT to use:** page-level dialogs or forms that must block the page (use `Modal` / `Drawer`); content anchored to a trigger in the page (use `Popover`); notifications (use `toast`); more than one launcher per page.
+
+**Anti-patterns**
+
+- Unmounting `<ChatLauncher>` when closed: you lose the draft and scroll position the component keeps for you.
+- Positioning it yourself (wrapping it in a fixed container, adding `className` with `position`/`bottom`): it already owns the viewport corner.
+- Putting the composer in `children`: it would scroll away. Use `footer`.
+- Bubbles without `ChatBubble.List`: new replies won't be announced.

package/docs/components/Checkbox.md

@@ -0,0 +1,55 @@
+# `<Checkbox>` — checkbox with native input + custom paint
+
+```tsx
+<Checkbox label="I agree" />
+<Checkbox checked={agreed} onChange={setAgreed} label="Subscribe" />
+<Checkbox indeterminate checked={allSelected} onChange={selectAll} aria-label="Select all" />
+
+// "Select all" pattern
+<Checkbox
+  checked={allSelected}
+  indeterminate={someSelected && !allSelected}
+  onChange={(next) => (next ? selectAll() : selectNone())}
+  aria-label="Select all rows"
+/>
+
+// Icon-only (no visible label)
+<Checkbox aria-label="Select row" checked={isSelected} onChange={setIsSelected} />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Box diameter + label type scale. Defaults to `'md'`. - `'sm'` — 14px box, font-size-sm label. Dense tables, inline filters. - `'md'` — 16px box, font-size-md label. Default. - `'lg'` — 20px box, font-size-lg label. Hero forms, mobile-friendly. Note: shadows the native HTML `<input size>` attribute (which on checkboxes is meaningless anyway). |
+| `checked` | `boolean` | no | Controlled checked state. Pair with `onChange`. Omit (with optional `defaultChecked`) for uncontrolled use. |
+| `defaultChecked` | `boolean` | no | Initial checked state for uncontrolled use. Defaults to `false`. |
+| `indeterminate` | `boolean` | no | Indeterminate (mixed) visual + a11y state. Independent of `checked` — the box paints with a dash icon and `input.indeterminate = true` so AT announces "mixed". Consumer drives this based on partial selection (e.g., a "select all" header where some-but-not-all rows are selected). When the user clicks an indeterminate checkbox, the native change event fires with the next `checked` value (`true` if it was `false`). The consumer typically responds by clearing `indeterminate`. |
+| `label` | `ReactNode` | no | Optional label rendered next to the box. The whole `<label>` is the click target. Omit for icon-only checkboxes (e.g., a DataTable row selector) — pass `aria-label` instead. |
+| `invalid` | `boolean` | no | Toggles the error visual + sets `aria-invalid="true"`. Pair with a visible error message and `aria-describedby`. |
+| `color` | `PaletteColor` | no | Optional palette color for the checked / indeterminate fill. When set, the filled state uses the palette color's fg token instead of `--color-accent`. Use to color-tag checkbox groups (per-team, per-status, per-category). Default unchanged (accent blue). The focus ring, hover border, and unchecked state remain accent-colored regardless of `color` — only the checked / indeterminate fill is affected. |
+| `onChange` | `((checked: boolean, event: ChangeEvent<HTMLInputElement, Element>) => void)` | no | Fires on every change. Receives the next checked state AND the native event so consumers can do `event.preventDefault()`, read modifier keys, etc. |
+| …native | | | plus native `<input>` attributes |
+
+<!-- props:end -->
+
+- Native `<input type='checkbox'>` is visually hidden but stays in tab order + AT tree — keyboard, screen reader, form submission, RHF/Zod, autofill all work for free.
+- Native HTML attrs flow through (`name`, `value`, `required`, `form`, `autoFocus`, etc.). `FormData.getAll(name)` returns the array of checked values for same-`name` checkboxes.
+- forwardRef points at the native `<input>` so consumers can `.focus()` or programmatically set `.indeterminate`.
+
+- The native input owns all a11y (keyboard, screen reader, form submission); the custom paint owns the look. States: checked / unchecked / indeterminate / disabled / invalid. `aria-disabled="true"` gets the disabled look and ignores clicks/Space but stays focusable — use it for a busy state (a write in flight) where real `disabled` would drop keyboard focus.
+
+#### When NOT to use
+
+- ❌ A single binary on/off setting that applies immediately → `Switch`.
+- ❌ One-of-many choice from a fixed set → `Radio`.
+- ❌ Multi-select from a long list → `<Select multi>`.
+
+#### Anti-patterns
+
+- ❌ Treating `indeterminate` as a third value. It is a display flag; `checked` is still the underlying boolean.
+- ❌ Wrapping the checkbox in your own `<label>`. It is already wrapped; an outer `<label>` nests two and breaks the click contract.
+- ❌ Omitting `label` AND `aria-label`. Screen readers announce just "checkbox" with no context.

package/docs/components/CircularProgress.md

@@ -0,0 +1,53 @@
+# `<CircularProgress>` — circular progress / spinner
+
+```tsx
+<CircularProgress value={45} />                    // donut, 32px default
+<CircularProgress value={75} label />              // centered "75%"
+<CircularProgress />                               // indeterminate spinner (the "Loader" use case)
+<CircularProgress size="sm" />                     // 16px inline spinner next to a button
+<CircularProgress tone="success" value={100} />    // green full circle
+<CircularProgress size="lg" value={80} tone="success" label />  // stat-card-style donut
+<CircularProgress value={3} max={10} label={`3 / 10`} />        // custom label ("n of N", a status word)
+
+// Canonical inline loader next to a button
+<Cluster gap="sm">
+  <Button>Save</Button>
+  <CircularProgress size="sm" aria-label="Saving" />
+</Cluster>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `number` | no | Current progress value. Omit (or pass `undefined`) to render the indeterminate spinning animation. Two-channel behavior for out-of-range and degenerate values: - **Visual arc** is clamped to [0%, 100%]. Values outside [0, max] render at the nearest valid bound. - **ARIA `aria-valuenow`** reports the raw number so consumer bugs (a value drifting past max) surface in audits and SR announcements. Degenerate inputs fall back to the indeterminate spinner: `NaN`, `Infinity`, `-Infinity`, and the case where `max <= 0`. This is the common file-upload race condition (`bytes_uploaded / total_bytes` before `total_bytes` is known produces NaN). |
+| `max` | `number` | no | Upper bound. Defaults to `100`. Consumers using fraction values (0.0–1.0) pass `max={1}`. Consumers tracking a count ("3 of 10") pass `max={10}`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Diameter + stroke pairing. - `sm` — 16px diameter, 2px stroke (inline next to a button — also the shape to use for "Saving…" loading affordances; pass no `value` for the indeterminate spinner.) - `md` — 32px diameter, 3px stroke (default — near a heading) - `lg` — 56px diameter, 4px stroke (page-level loader) |
+| `tone` | `'default' \| 'success' \| 'warning' \| 'danger'` | no | Stroke color tone. Defaults to `'default'` (accent blue). Same vocab as `<Progress>`. Indeterminate ignores tone — always accent. |
+| `label` | `CircularProgressLabel` | no | Optional centered label. - `false` (default) — no label - `true` — render `{Math.round(percent)}%` centered. Auto-suppressed at `size='sm'` (16px circle has no room for text) AND when indeterminate. - `ReactNode` — render the node centered in BOTH modes. Still auto-suppressed at `size='sm'` regardless — the geometry doesn't change. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Same prop vocabulary as `<Progress>` — `value?`, `max?`, `size`, `tone`, `label`.
+- Same NaN/Infinity/max<=0 indeterminate fallback as `<Progress>`.
+- Built as inline `<svg viewBox="0 0 36 36">` with two `<circle>` elements (track + fill). Determinate arc is driven by `stroke-dashoffset`; indeterminate is a CSS `rotate` animation on a partial arc.
+- Centered `label` auto-suppressed at `size="sm"` (no room for text) AND when `label=true` on indeterminate. ReactNode labels still suppress at `size="sm"` regardless.
+- `prefers-reduced-motion` disables the spin animation and shows a static accent ring.
+
+- `role="progressbar"` is locked (can't be overridden via the `role` prop) and is announced to screen readers. Tracks known progress like `<Progress>` in a circular geometry, better for inline loading indicators and tight spaces; indeterminate mode is the canonical spinner.
+
+#### When NOT to use
+
+- ❌ Horizontal progress next to row content → `<Progress>` linear.
+- ❌ Replacing `<Skeleton>` for loading placeholders. Skeleton implies "structure on its way"; CircularProgress implies "I'm working on it."
+- ❌ A decorative icon: the `progressbar` role is announced.
+
+#### Anti-patterns
+
+- ❌ Hand-rolled spinning `<svg>` per page. `<CircularProgress />` indeterminate is the same visual, accessible and reduced-motion-aware.
+- ❌ `<CircularProgress value={0}>` to render an empty circle. `value={0}` is determinate (0% done); the intent is usually indeterminate, so omit `value`.
+- ❌ `<CircularProgress size="sm" label>` expecting centered text in a 16px circle. The label is auto-suppressed at `sm` by design; use `md` or `lg`.

package/docs/components/Cluster.md

@@ -0,0 +1,96 @@
+# `<Cluster>` — horizontal layout that wraps
+
+```tsx
+// Form footer:
+<Cluster justify="end" gap="sm">
+  <Button variant="secondary">Cancel</Button>
+  <Button type="submit">Save</Button>
+</Cluster>
+
+// Toolbar (title left, actions right):
+<Cluster justify="between" gap="md">
+  <h1>Users</h1>
+  <Cluster gap="sm">
+    <Button variant="secondary">Filter</Button>
+    <Button>Add user</Button>
+  </Cluster>
+</Cluster>
+
+// Tag list: wraps to multiple lines when narrow
+<Cluster gap="xs">
+  {tags.map((t) => <Badge key={t.id} tone={t.tone}>{t.label}</Badge>)}
+</Cluster>
+
+// Pill left + two buttons right while they fit; buttons drop under the pill
+// at full width (equal columns) when they don't — no breakpoint to guess:
+<Cluster stretchWrapped gap="sm">
+  <Badge tone="info">In review</Badge>
+  <Grid columns={2} gap="sm">
+    <Button variant="secondary">Reject</Button>
+    <Button>Approve</Button>
+  </Grid>
+</Cluster>
+
+// Inline, inside a <button>/<a>/<label> where a <div> is invalid HTML —
+// as="span" renders inline-flex (e.g. icon + label in a ButtonGroup.Item):
+<ButtonGroup.Item value="list">
+  <Cluster as="span" gap="xs" align="center" wrap={false}>
+    <List size={14} aria-hidden />
+    List
+  </Cluster>
+</ButtonGroup.Item>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `as` | `'div' \| 'span' \| 'section' \| 'aside'` | no | Element to render. Defaults to `'div'`. - `div` (default) — block-level flex container; right for nearly all uses. - `span` — renders `display: inline-flex`, for phrasing-content contexts where a block element is invalid HTML: inside `<button>` (e.g. a `ButtonGroup.Item` icon + label), `<a>`, or `<label>`. - `section` — only for a genuinely standalone, nameable region; pair with `aria-label`/`aria-labelledby` (an unnamed section is just a div to AT). - `aside` — exposes a `complementary` landmark to screen readers; label it, and never use it for mere visual grouping. `span` is the ONLY value valid inside `<button>`/`<a>`/`<label>` — `section` and `aside` are flow content and remain invalid HTML there. |
+| `gap` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | no | Gap between children, in pixels: `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32). |
+| `justify` | `'start' \| 'center' \| 'end' \| 'between'` | no | Horizontal distribution. - `start` (default) — items at the start. - `center` — items centered. - `end` — items at the end. Canonical form-footer pattern. - `between` — first item at start, last at end, gap between. Canonical toolbar pattern (title left, actions right). |
+| `align` | `'start' \| 'center' \| 'end' \| 'baseline'` | no | Vertical alignment. - `start` / `center` (default) / `end` / `baseline`. |
+| `minWidth0` | `boolean` | no | Lets the container shrink below its content's intrinsic width (`min-width: 0`), so a `<Text truncate>` inside can ellipsize instead of being hard-cut by a clipping ancestor. Reach for it when this Cluster is an item of a **row** flex container (or a grid item) that clips — a `Calendar` `renderEvent` chip, a `Card.Header` row. Without it the flex default (`min-width: auto`) floors the container at its content's min-content width and the ellipsis never appears. That floor applies because a Cluster sets no `overflow` — per CSS Flexbox §4.5 a flex item keeps its automatic minimum size while its computed `overflow` is non-scrollable (`visible` or `clip`); the scrollable values (`hidden`/`auto`/`scroll`) drop it to `0`. That is why a `<Text truncate>` (overflow hidden) never needs this and a Cluster around it does. It is a **no-op** inside a column `Stack` (the automatic minimum size applies only on the flex MAIN axis, so there is no horizontal floor), and inside a plain block or a table cell (the automatic minimum size applies to flex and grid ITEMS only, so `min-width: auto` is just `0` there). A table cell is a no-op for a different reason than it looks: auto table layout floors the cell at its content's min-content width regardless, so what makes text truncate there is `table-layout: fixed` or a `max-width` on the cell — not this prop. Opt-in rather than the default on purpose: a container that CAN shrink also VOLUNTEERS for shrink, so turning it on where the content is NOT truncatable (buttons, badges, icons) lets that content be clipped instead. Set it on the container whose text should give way, not on one holding controls. Related: `<Constrain flex="grow">` applies the same `min-width: 0` but also forces `flex: 1 1 0`, and renders a `<div>` — reach for this prop when you want only the shrink permission, or when you are inside a `<button>`/`<a>`/`<label>` where a `<div>` is invalid HTML. Default: `false`. |
+| `maxWidthFull` | `boolean` | no | Caps the cluster at its container's width (`max-width: 100%`). Meant for `as="span"` inside running text: an inline cluster otherwise sizes to its content, so a `<Text as="span" truncate>` child with a long title makes the cluster overflow the paragraph instead of ellipsizing at the line edge. Combine with `wrap={false}` + a truncating child. The chip is one inline box: if the text before it leaves too little room on the line, the whole chip wraps to the next line, then ellipsizes at the full paragraph width. Phrasing-safe (still a span) — unlike `<Constrain maxWidth>`, which renders a `<div>` that is invalid inside `<p>`. For an entity link row (icon, KEY, title, status, adornments) prefer `<EntityChip truncate trailing={…}>`, which does exactly this. Default: `false`. |
+| `stretchWrapped` | `boolean` | no | Content-driven switch between one row and stacked. While the children fit on one line they stay content-sized and the free space collects between the first child and the rest (the rest sit at the end). When they no longer fit, every child that wraps onto its own line stretches to fill that line. Canonical case: a status pill plus a `<Grid columns={2}>` of two buttons — pill left and buttons right while there is room, buttons dropping under the pill at full width (equal columns) when there is not. No breakpoint to guess, unlike `Grid collapseBelow`. How: an invisible `::before` spacer soaks up a shared line's slack, so the children there get a negligible share (at most 1px per 1000px of slack); a non-first child alone on a wrapped line takes the whole line. Children wrapped together share it. The spacer cancels its own gap, so it adds no width: the switch happens exactly when the content stops fitting, also with a single child or `as="span"`. Limits: `justify` is inert while this is on (the spacer owns the slack); `wrap={false}` makes it moot (nothing wraps); a consumer `order` on children breaks it — don't. A child's own `flex` (via its `className`) overrides the stretch for that child. "First child" means the first ELEMENT: a leading bare text node is not it — wrap text in an element (e.g. `<Text>`). Default: `false`. |
+| `wrap` | `boolean` | no | Whether children wrap to additional lines when the container is narrow. - `true` (default) — natural for toolbars and tag lists. - `false` — use sparingly, when overflow is preferable to wrapping (e.g. inside a narrow table cell with fixed-width action buttons). |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+```tsx
+// Custom Calendar chip content that ellipsizes instead of hard-clipping.
+// The chip is a <button> with overflow: hidden, so the Cluster is a flex item:
+// as="span" for valid HTML, minWidth0 so it can actually shrink.
+<Calendar
+  events={events}
+  renderEvent={(event) => (
+    <Cluster as="span" gap="xs" align="center" wrap={false} minWidth0>
+      <Dot color="violet" />
+      <Text as="span" size="inherit" truncate>
+        {event.title}
+      </Text>
+    </Cluster>
+  )}
+/>
+```
+
+Use it for button rows, toolbars, tag lists and breadcrumbs: anywhere you would otherwise write `display: flex; gap: ...; flex-wrap: wrap`.
+
+#### When NOT to use
+
+- ❌ Aligned columns of equal width → `<Grid>`. Cluster wraps unpredictably at narrow widths and isn't a column system.
+- ❌ Content that must never wrap: `wrap={false}` if you must, but reconsider whether that's truly required on narrow viewports.
+
+#### Anti-patterns
+
+- ❌ Cluster as a 2-column layout. Use `<Grid columns={2}>` for "two columns, always".
+- ❌ `style={{ marginLeft: 'auto' }}` on a child to push it right. Use `justify="between"` (with a sibling on the left) or split into two Clusters in the parent.
+- ❌ `minWidth0` on a Cluster holding buttons or badges: it lets the container shrink, so non-truncatable content gets clipped. Use it on the container whose TEXT should give way.
+- ❌ `Grid collapseBelow` with a guessed pixel threshold to stack a pill + buttons row. The right width depends on content and locale; use `stretchWrapped` and let the content decide.
+- ❌ `stretchWrapped` with `justify`, `wrap={false}` or a child `order`: `justify` is inert, `wrap={false}` never wraps so nothing switches, `order` breaks the spacer.
+- ❌ `stretchWrapped` with a leading bare text node: the first child is the first ELEMENT, so the text is not treated as it. Wrap the text in an element (e.g. `<Text>`).
+- A child's own `flex` (via its `className`) overrides `stretchWrapped` for that child; that child no longer stretches when it wraps.
+- ❌ `as="span"` as a general styling hook. Reach for it only when block content is invalid HTML (inside `<button>`, `<a>`, `<label>`); in normal flow the default block `div` is what you want.

package/docs/components/Code.md

@@ -0,0 +1,35 @@
+# `<Code>` — inline `<code>` chip
+
+```tsx
+<Text>Use <Code>npm install</Code> to add deps.</Text>
+<Code tone="danger">--no-verify</Code>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `tone` | `'default' \| 'muted' \| 'accent' \| 'danger'` | no | Color tone for the code text. The chip background stays the same; only the text color changes. - `default` — `--color-fg` - `muted` — `--color-fg-muted` - `accent` — `--color-accent` - `danger` — `--color-danger` |
+| `children` | `ReactNode` | yes | Code content. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- **Inline only.** Multi-line or syntax-highlighted code belongs in [`CodeBlock`](CodeBlock.md).
+
+- The chip background is intentionally `--color-bg-muted` so it subordinates to body text.
+
+#### When NOT to use
+
+- ❌ Block-level code with multiple lines or syntax highlighting.
+- ❌ Action triggers that LOOK like code (`<Button variant="ghost">`).
+- ❌ A substitute for `<kbd>` (keyboard input rendering; not yet shipped).
+
+#### Anti-patterns
+
+- ❌ `<Code>multi-line\nblock</Code>`: Code is inline only; the chip background doesn't extend across newlines. Use `CodeBlock`, or `<pre><Code>...</Code></pre>` for a static block inside the library.
+- ❌ `<Code style={{ background: '#xxx' }}>`: a different background is a token-vocabulary conversation.
+- ❌ Wrapping a `<Button>` or `<Link>` in `<Code>` to style it code-like. Code is for content semantics (it IS code), not visual styling.

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`.