@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/Sortable.md

@@ -0,0 +1,127 @@
+# `<Sortable>` — drag-to-reorder list (single column)
+
+For reorderable lists — todo priority, image gallery, settings ordering, queue management. Renders `<ol>`/`<li>`. Compound: `Sortable`, `Sortable.Item`, `Sortable.Handle`. Built on `@dnd-kit/sortable`; mouse / touch / pen via PointerSensor + keyboard via KeyboardSensor.
+
+```tsx
+import { arrayMove } from '@dnd-kit/sortable';
+
+const [items, setItems] = useState([
+  { id: 1, title: 'Onboarding email' },
+  { id: 2, title: 'Renewal reminder' },
+  { id: 3, title: 'Quarterly report' },
+]);
+
+<Sortable onReorder={({ from, to }) => setItems((curr) => arrayMove(curr, from, to))}>
+  {items.map((item) => (
+    <Sortable.Item key={item.id} id={item.id}>
+      <Card>
+        <Cluster gap="sm" align="center">
+          <Sortable.Handle aria-label={`Reorder ${item.title}`}>
+            <GripVertical size={14} />
+          </Sortable.Handle>
+          <Title order={3}>{item.title}</Title>
+        </Cluster>
+      </Card>
+    </Sortable.Item>
+  ))}
+</Sortable>;
+```
+
+<!-- props:start -->
+
+## Props
+
+### `SortableProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `onReorder` | `((event: SortableReorderEvent) => void)` | no | Fires after a drag or keyboard move with the new position. Consumer holds the items array and re-renders with the new order. Not fired if the drop position equals the source position (no-op). |
+| `restrictToContainer` | `boolean` | no | When `true` (default), the dragged item is clamped to the list's bounding box — it can't be dragged outside the `<ol>`. Set `false` for free-drag (the item can be dragged anywhere on the page). For a vertical list this constrains the drag vertically to the list's extent. |
+| `arrangement` | `'list' \| 'grid'` | no | Layout arrangement of the items. - `'list'` (default) — single vertical column; existing behavior unchanged. - `'grid'` — the `<ol>` becomes a `columns`-track CSS grid. Items carry column spans (`Sortable.Item span`), rows are equal-height, and siblings reflow in 2D during a drag. Reorder semantics stay order-based (a drop reorders the flow; nothing here persists an x/y position). |
+| `columns` | `number` | no | Number of equal-width grid tracks. Only applies when `arrangement="grid"` (ignored for a list). Default `12`, matching `Grid.Item`'s 12-column fraction spans (`'25%'`→3 … `'75%'`→9 tracks). Set another count for a simpler grid, but the named fraction spans then won't map to their fraction (documented, not validated — same as `Grid`). |
+| `collapseBelow` | `CollapseBreakpoint \| Partial<Record<CollapseBreakpoint, number>>` | no | Responsive collapse for the grid arrangement — mirrors `Grid`'s `collapseBelow` exactly (same breakpoints, same container-query mechanism). Ignored unless `arrangement="grid"`. - `'sm' \| 'md' \| 'lg'` — below the container-width threshold (480 / 640 / 768px of the LIST'S OWN width) every item spans the full row: a single visual column. - `{ lg?: n, md?: n, sm?: n }` — graduated: below each breakpoint the grid re-templates to that many columns and item spans clamp to fit (a span wider than the step becomes a full row). E.g. `{ md: 6, sm: 1 }`. ❌ Anti-pattern: a collapsible Sortable must get its width from its parent — `container-type: inline-size` zeroes the list's contribution to intrinsic sizing (same caveat as `Grid`'s `collapseBelow`). ⚠️ The map form (and ONLY the map form) wraps the `<ol>` in an extra `<div>` carrying `container-type: inline-size` — re-templating the `<ol>` requires querying an ancestor, not the `<ol>` itself. A `> child` selector aimed at the list from its parent hits that wrapper instead, and layout the parent applies via `className` lands on the `<ol>` inside it. `ref`, `className`, `style` and spread props all stay on the `<ol>`. |
+| …native | | | plus native `<ol>` attributes |
+
+### `SortableHandleProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | no | Decorative content — typically a grip icon (e.g. `<GripVertical size={14} />`). Rendered inside the Handle's `<button>` wrapped with `aria-hidden`. |
+| …native | | | plus native `<button>` attributes |
+
+### `SortableItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string \| number` | yes | Stable identifier for this item. Used by dnd-kit for tracking the item across reorders. String or number — typically the consumer's database id. |
+| `children` | `ReactNode` | yes | Item content — typically a `<Card>` or a row of text + icons. |
+| `span` | `GridItemSpan` | no | Column span, only meaningful under `<Sortable arrangement="grid">` (ignored in a list). Mirrors `Grid.Item`'s `span` exactly: - number — `span N` of the grid's `columns`. - `'25%' \| '33%' \| '50%' \| '67%' \| '75%'` — fractions of a 12-column grid. - `'100%'` / `'full'` — the entire row (`1 / -1`); safe with any `columns`. Omit for a single track (auto placement). |
+| …native | | | plus native `<li>` attributes |
+
+<!-- props:end -->
+
+Reorder with `arrayMove` from `@dnd-kit/sortable` (already a dependency) — import it from there; `Sortable.Item` ids must be stable (`string | number`). For `arrangement` / `columns` see **Grid arrangement** below.
+
+**Grid arrangement** (`arrangement="grid"`): re-lays the `<ol>` as a `columns`-track CSS grid (`columns?: number`, default 12) driven by dnd-kit's `rectSortingStrategy`, so siblings reflow in **2D** during a drag instead of shifting only vertically. Give each item a span via `<Sortable.Item span="50%">` (or `span={6}` / `span="100%"`) — **same values as `Grid.Item`** (`25%`→3 … `75%`→9 tracks of 12; `100%`/`full`→whole row). Rows are equal-height (`align-items: stretch`). Semantics stay order-based: a drop reorders the flow — nothing persists a grid x/y position. `restrictToContainer` still clamps the drag to the grid box. Default `arrangement="list"` is unchanged (single vertical column). Canonical use: a WYSIWYG dashboard customize view where edit mode mirrors view mode's 12-col widget grid.
+
+```tsx
+<Sortable arrangement="grid" columns={12} onReorder={handle}>
+  {widgets.map((w) => (
+    <Sortable.Item key={w.id} id={w.id} span={w.span}>
+      <Card style={{ height: '100%' }}>{w.title}</Card>
+    </Sortable.Item>
+  ))}
+</Sortable>
+```
+
+`collapseBelow` (grid arrangement only) mirrors Grid's `collapseBelow` exactly — `'sm' | 'md' | 'lg'` for a binary collapse to one column, or `{ md: 6, sm: 1 }` for a graduated step-down with item spans clamped per step. The map form wraps the `<ol>` in an extra size-container `<div>`, for the same reason and with the same consequences as Grid's map form (see `<Grid>` below); `ref`, `className`, `style` and spread props stay on the `<ol>`.
+
+**Drag origin** (hybrid): if `<Sortable.Handle>` is present in the Item subtree, only the Handle initiates drag. If no Handle is present, the entire Item is draggable + focusable. A 5px activation distance means short clicks-without-movement on internal buttons / links pass through.
+
+**Keyboard reorder**: Tab to focus the Handle (or the Item if no Handle), press **Space** to pick up, **ArrowUp** / **ArrowDown** to move, **Space** to drop, **Escape** to cancel. dnd-kit's KeyboardSensor ships built-in `aria-live` announcements describing each move. Inside a `Modal`/`Drawer`, an in-progress drag is an Escape-consuming mode: Escape cancels the drag and the host survives that press; the next Escape closes the host. Same for `DataTable` column reorder.
+
+**Drop visual / async-safe**: the dragged item renders in a dnd-kit `<DragOverlay>` (a portaled, fixed-position clone); the active list `<li>` is an invisible placeholder during drag. Because the overlay owns the drop animation, the in-list row never carries a stale drag transform — so `onReorder` may commit the new order **asynchronously / optimistically** (e.g. an optimistic TanStack mutation's `onMutate` that lands a tick late) without the dropped row glitching ("fly up then settle"). You no longer need to reorder synchronously. The drop animation respects `prefers-reduced-motion` (it's disabled under reduced motion).
+
+**Anti-patterns**
+
+- ❌ Mutating items in place inside `onReorder`. Always return a new array (`arrayMove(items, from, to)` from `@dnd-kit/sortable`) — React needs a fresh reference.
+- ❌ Using a non-stable `id` (e.g. array index). The id must persist across reorders for React reconciliation and for `onReorder`'s `id` field to be meaningful.
+- ❌ Wrapping non-`Sortable.Item` content inside `<Sortable>`. dnd-kit's `SortableContext` only tracks the ids you pass it; arbitrary children render but won't be reorderable.
+- ❌ Relying on whole-item drag (no Handle) for screen-reader-accessible lists. Without a Handle, dnd-kit puts `role="button"` on the `<li>` and the listitem semantics are lost — screen readers stop announcing "item N of M." For accessible lists, always include a `<Sortable.Handle>`.
+
+```tsx
+// Plain text list — no handle needed; the whole item is draggable.
+<Sortable onReorder={({ from, to }) => setItems((curr) => arrayMove(curr, from, to))}>
+  {items.map((item) => (
+    <Sortable.Item key={item.id} id={item.id}>{item.label}</Sortable.Item>
+  ))}
+</Sortable>
+
+// Card with an internal DropdownMenu — an explicit Handle keeps the menu clickable.
+<Sortable onReorder={handle}>
+  {cards.map((c) => (
+    <Sortable.Item key={c.id} id={c.id}>
+      <Card>
+        <Cluster justify="between">
+          <Sortable.Handle aria-label={`Reorder ${c.title}`}><GripVertical size={14} /></Sortable.Handle>
+          <Title order={3}>{c.title}</Title>
+          <DropdownMenu>...</DropdownMenu>
+        </Cluster>
+      </Card>
+    </Sortable.Item>
+  ))}
+</Sortable>
+```
+
+- `Sortable.Item` renders an `<li>`; `span` applies only under `arrangement="grid"` and is ignored in a list. Drag announcements name the item by its rendered text; pass `aria-label` to override it when the item renders a lot of chrome (badges, timestamps, avatars) and only part of it is the name.
+- `Sortable.Handle` is a `<button>` (keyboard-focusable); its children are decorative (`aria-hidden`), so give it an `aria-label`.
+- Place `<Sortable.Handle>` at the same JSX nesting level as the Item's other content. A Handle hidden inside your own wrapper component (e.g. a `<TaskRow>` that renders it internally) is not detected, and the Item falls back to whole-item drag.
+
+**When NOT to use**
+
+- Tabular data: use `<Table>` / `<DataTable>` (DataTable has its own column reorder).
+- Static lists that never reorder: use `<Stack>` or `<DefinitionList>`.
+- Cross-list drag: use `<SortableGroup>`.

package/docs/components/SortableGroup.md

@@ -0,0 +1,52 @@
+# `<SortableGroup>` — multi-container sortable (drag between lists)
+
+`<SortableGroup onMove>` + `<SortableGroup.Container id items>` under one shared `DndContext` — drag `<Sortable.Item>`s within a list AND between lists. Controlled + live: `onMove({ id, from:{container,index}, to:{container,index} })` fires on each cross-container handoff during the drag AND on drop; apply it with the exported pure `moveSortableItem(containers, event)` (immutable, generic over item type). For a single list, use `<Sortable>`.
+
+```tsx
+const [groups, setGroups] = useState<Record<string, Field[]>>(initial);
+<SortableGroup onMove={(e) => setGroups((g) => moveSortableItem(g, e))}>
+  {Object.entries(groups).map(([gid, fields]) => (
+    <SortableGroup.Container key={gid} id={gid} items={fields.map((f) => f.id)}>
+      {fields.map((f) => (
+        <Sortable.Item key={f.id} id={f.id}>
+          <Sortable.Handle>⋮⋮</Sortable.Handle>
+          {f.label}
+        </Sortable.Item>
+      ))}
+    </SortableGroup.Container>
+  ))}
+</SortableGroup>;
+```
+
+<!-- props:start -->
+
+## Props
+
+### `SortableGroupProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `onMove` | `((event: SortableMoveEvent) => void)` | no | Fires on every cross-container handoff (during the drag) AND on the final drop. Apply it to your controlled per-container state — see `moveSortableItem`. |
+| `children` | `ReactNode` | yes | The `<SortableGroup.Container>` lists. |
+
+### `SortableGroupContainerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | `Id` | yes | Stable container id (the `container` reported in `SortableMoveEvent`). |
+| `items` | `Id[]` | yes | Ordered item ids in THIS container — the controlled source of truth. |
+| `children` | `ReactNode` | yes | `<Sortable.Item>`s for the ids in `items`. |
+| …native | | | plus native `<ol>` attributes |
+
+<!-- props:end -->
+
+- Give each `Container` an `aria-label` (or `aria-labelledby`) — it names the `<ol>` for screen readers AND names the list in drag announcements ("…position 2 of 4 in In review").
+- Container ids and item ids share dnd-kit's one id namespace — keep them all unique.
+- Each `Container.items` must match its `<Sortable.Item>` child ids (it's the ordering source of truth).
+- Esc-cancel doesn't revert (moves are applied to your state optimistically) — snapshot before drag to undo.
+
+- The root renders no host DOM node, so it forwards no `ref`; attach refs to `<SortableGroup.Container>`, which forwards to its `<ol>`.
+- `Container` renders an `<ol>` registered as a droppable, so an empty list still accepts cross-container drops.
+- Mutating state inside `onMove` is wrong: return a NEW object (use `moveSortableItem`).

package/docs/components/Sparkline.md

@@ -0,0 +1,51 @@
+# `<Sparkline>` — compact trend graphic for KPI cards
+
+Static, axis-free line / area / bar trend with an intrinsic height (`--size-sparkline`, 40px) and full width. `role="img"` named "{label}: from {first} to {last}, low {min}, high {max}" (numbers through `formatValue`). `null` and non-finite values are gaps; area and bar anchor at zero for non-negative data. With negative data a line spans min..max, an area fills from the bottom (min), and bars hang from a zero line (all-negative series hang from the top). No hover, no tab stop, no animation.
+
+```tsx
+import { DashboardWidget, Sparkline, StatGroup, StatTile } from '@eocrm/design-system';
+
+// Standalone
+<Sparkline label="Contacts per day" values={dailyCounts} />
+<Sparkline label="Deals won per week" type="bar" values={weekly} formatValue={fmt} />
+
+// StatTile slot
+<StatGroup aria-label="Usage">
+  <StatTile
+    label="Contacts"
+    value="1,284"
+    sparkline={<Sparkline label="Contacts per day" type="area" values={dailyCounts} />}
+  />
+</StatGroup>
+
+// kpi DashboardWidget: pass it as children
+<DashboardWidget variant="kpi" title="Open deals" value="128">
+  <Sparkline label="Open deals per day" values={dailyCounts} />
+</DashboardWidget>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | yes | What the series is, e.g. "Contacts per day". Starts the accessible name. |
+| `values` | `readonly (number \| null)[]` | yes | Values oldest → newest. `null` (or a non-finite number) = no data for that slot: a gap in a line/area, no bar. |
+| `type` | `'line' \| 'area' \| 'bar'` | no | Mark type. Default `'line'`. - `'line'` — smoothed line with a dot on the latest value. Trends of a rate or level. - `'area'` — the line over a filled area anchored at zero. Volumes / counts over time. - `'bar'` — one bar per value. Discrete per-period counts (daily signups). |
+| `formatValue` | `((n: number) => string)` | no | Formats numbers in the accessible summary. Default: `Intl.NumberFormat` for the current locale. |
+| `endDot` | `boolean` | no | Dot on the latest value (`line` / `area`; `bar` never has one). Default `true`. Turn off where the dot reads as a stray marker rather than emphasis, e.g. a dense row of `StatTile` sparklines. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Name, not a table.** The summary (first, last, low, high) is folded into the accessible name; there is no data table. Empty or all-null `values` render nothing and are named "{label}: no data".
+- **Ignored attributes.** `role`, `aria-label` and `aria-labelledby` are ignored; the name is always derived from `label` and `values`.
+- **Marks.** `line` and `area` are smoothed and end in a dot on the last value (`endDot={false}` removes it, e.g. in a dense row of tiles); `bar` draws one bar per non-null value. A flat `line` is drawn mid-height (a flat positive area/bar fills from zero).
+
+#### When NOT to use
+
+- ❌ Values someone must read or compare exactly, axes or dates, several series, hover / keyboard inspection → `Chart`.
+- ❌ Wrapping it in `Constrain` or giving it a height: it brings its own.
+- ❌ Passing `role` / `aria-label` / `aria-labelledby` to rename it: they are ignored.

package/docs/components/Split.md

@@ -0,0 +1,76 @@
+# `<Split>` — master–detail two-pane layout
+
+Intrinsic-width `aside` pane beside a filling `main` pane (`children`), via CSS
+grid `auto 1fr`. Never wraps. Sibling to Stack/Cluster/Grid; for in-page
+master–detail (a vertical `Tabs` rail beside its detail panel, a filter column
+beside results).
+
+```tsx
+<Split
+  asideWidth="220px"
+  collapseBelow="sm"
+  aside={<Tabs orientation="auto" items={items} activeId={id} onChange={setId} />}
+  gap="lg"
+>
+  <SectionPanel id={id} />
+</Split>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `aside` | `ReactNode` | no | The narrow, intrinsic-width pane — a vertical `Tabs` rail, filter list, or nav column. `null` / `false` / `undefined` renders no aside cell at all (no empty track or gap), so content can be conditionally moved out of the aside; `main` then fills the split. |
+| `side` | `'start' \| 'end'` | no | Which side `aside` sits on. - `'start'` (default) — leading edge (left in LTR). - `'end'` — trailing edge (right in LTR). |
+| `asideWidth` | `string` | no | `aside` column width. - `'auto'` (default) — intrinsic; sizes to the pane's content. - a CSS length (e.g. `'240px'`) — pins the column so `main` doesn't reflow when `aside` content changes width. |
+| `gap` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | no | Gap between the two panes, in pixels: `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32). Same scale as Stack, Cluster, and Grid. |
+| `align` | `'start' \| 'stretch' \| 'center'` | no | Cross-axis (vertical) alignment of the panes. - `'start'` (default) — panes hug the top. - `'stretch'` — `aside` matches `main`'s height (full-height bordered rail). - `'center'` — panes vertically centered. |
+| `collapseBelow` | `'sm' \| 'md' \| 'lg'` | no | Stack the two panes vertically when the SPLIT'S OWN width (container query, not viewport) drops below the preset: `sm` 480px / `md` 640px / `lg` 768px. Same scale as `Grid`'s `collapseBelow`. Without it a pinned `asideWidth` rail squeezes `main` to nothing on narrow screens. A pinned `asideWidth` is preserved while the panes are side-by-side and space is available, but can shrink as the container narrows so the stacked panes stay within the split. Collapsed panes stack in **DOM order**, not always aside-first: with the default `side="start"` that's aside → main; with `side="end"` it's main → aside, because that's the order the panes are in the DOM. Forcing aside-first when collapsed would need CSS `order`, which desynchronizes visual order from tab order — an a11y defect. If you need the aside on top when stacked, use `side="start"`. A `<Sticky>` passed as the `aside` stops pinning (and drops its `scroll` height cap) while stacked, so it can't trap the page scroll on a phone. ❌ Anti-pattern: a `collapseBelow` split must get its width from its parent. `container-type: inline-size` zeroes the split's contribution to intrinsic sizing, so in an intrinsic-width context (another `Split`'s default `auto` aside track, a `Cluster` item, `width: max-content`) it renders at width 0 — give the parent a concrete width instead. The split also becomes the containing block for absolutely-positioned descendants (layout containment). Splits without the prop pay none of this. |
+| `onCollapsedChange` | `((collapsed: boolean) => void)` | no | Called with `true` when a `collapseBelow` split stacks and `false` when it goes back side by side — on mount with the initial state (twice under React StrictMode in development), then on every change. Ignored without `collapseBelow`. Use it to move content you own between placements so DOM order matches visual order in both states, instead of CSS `order` — e.g. render a comment thread at the end of `main` while side by side and after the `<Split>` once stacked, or a status switcher at the top of the aside vs. above the split. It measures the SPLIT'S OWN content width against the same inclusive threshold its container query uses (a `ResizeObserver`, read synchronously on mount so the first paint is already right), so it agrees with the CSS where `useBelowBreakpoint` — which measures the viewport — would not beside an app sidebar. The same state is on the root as `data-collapsed="true" \| "false"`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- `children` is the filling main pane (`min-width: 0` — long content shrinks/scrolls instead of overflowing).
+- An empty `aside` (`null` / `false` / `undefined`) renders no aside track even with `asideWidth`. To keep the track reserved (e.g. while data loads), pass an empty fragment (`<></>`) or a placeholder.
+
+```tsx
+// Settings screen: a 220px rail that becomes a horizontal strip when it stacks.
+<Split aside={<Tabs orientation="auto" ... />} asideWidth="220px" collapseBelow="sm">
+  <SettingsPanel />
+</Split>
+```
+
+- Collapsed panes stack in **DOM order**: aside → main for `side="start"` (default), main → aside for `side="end"`. No CSS `order` flip — visual order stays in sync with tab order. Need the aside on top when stacked? Use `side="start"`.
+- A pinned `<Sticky>` aside needs `align="stretch"`: the default `align="start"` makes the aside cell only as tall as its content, leaving nothing to pin within.
+- A `<Sticky>` passed as `aside` becomes a plain block while collapsed (no pin, no `scroll` cap) — don't shim it.
+- `onCollapsedChange(collapsed)` — fires on mount with the initial state (twice under StrictMode in dev), then on every change; the root also carries `data-collapsed`. It measures the split's own content width against the same inclusive threshold as the container query, so it agrees with the CSS (`useBelowBreakpoint` measures the viewport and does not, beside an app sidebar). Use it to move content YOU own so DOM order = visual order in both states — never CSS `order`:
+
+```tsx
+// Comments last on the page, side by side or stacked:
+const [stacked, setStacked] = useState(false);
+<>
+  <Split aside={<Sidebar />} side="end" collapseBelow="lg" onCollapsedChange={setStacked}>
+    <RecordData />
+    {!stacked && <Comments />}
+  </Split>
+  {stacked && <Comments />}
+</>;
+```
+
+- ❌ A `collapseBelow` split in an intrinsic-width context (another `Split`'s default `auto` aside track, a `Cluster` item, `width: max-content`). `container-type: inline-size` makes it contribute zero intrinsic width, so it renders at width 0 — give the parent a concrete width instead. It also becomes the containing block for absolutely-positioned descendants (layout containment). Splits without the prop pay neither cost.
+
+When NOT to use: equal columns → `<Grid columns={2}>`; wrapping peer row → `<Cluster>`; app shell sidebar → `<AppLayout>`/`<Rail>`.
+
+```tsx
+// Pinned rail width, aside on the right:
+<Split aside={<Filters />} side="end" asideWidth="260px" gap="lg">
+  <Results />
+</Split>
+```
+
+- Split owns only its internal grid (like `AppLayout` / `Page` / `Screen`, a documented exception to "components don't own layout"). Unlike `Cluster` it never wraps the panel below the rail; unlike `Grid columns={2}` the rail keeps its natural width instead of taking half.
+- ❌ Primary page navigation in `aside`: that belongs in the app shell (`<Rail>` / `<AppLayout sidebar>`); Split's aside is intra-page.

package/docs/components/Stack.md

@@ -0,0 +1,59 @@
+# `<Stack>` — vertical layout
+
+```tsx
+<Stack gap="md">
+  <Input ... />
+  <Input ... />
+  <Cluster justify="end" gap="sm">
+    <Button variant="secondary">Cancel</Button>
+    <Button type="submit">Save</Button>
+  </Cluster>
+</Stack>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `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). |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch'` | no | Cross-axis alignment. - `stretch` (default) — children fill the stack's horizontal width. - `start` / `center` / `end` — left, center, right alignment. |
+| `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. Only bites when the Stack is itself an item of a **row** flex container (or a grid item) that clips — what decides is the PARENT's main axis, not the Stack's own direction. That is the two-line label beside a fixed badge, or a detail column in a squeezed toolbar. Without it the flex default (`min-width: auto`) floors the Stack at its widest line and the ellipsis never appears. That floor applies because a Stack 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`. It is a **no-op** when the Stack sits in another `Stack` (the automatic minimum size applies only on the flex MAIN axis, so there is no horizontal floor), or in a plain block or table cell (that minimum 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`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- `minWidth0`: `false` (default). Sets `min-width: 0` so the Stack can shrink below its content's intrinsic width, letting a `<Text truncate>` inside ellipsize instead of being hard-cut. Only bites when the Stack is itself an item of a **row** flex container (or a grid item) that clips — what decides is the PARENT's main axis, not the Stack's own direction: a two-line label beside a fixed badge, a detail column in a squeezed toolbar. **No-op** inside another `Stack`, a plain block, or a table cell — and note 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 (that is what `<Table.Cell truncate>` does), not this prop. **Opt-in on purpose:** a container that can shrink also _volunteers_ for shrink, so setting it where the content is NOT truncatable (buttons, badges, icons) lets that content be clipped instead.
+
+Pairs with `<Cluster>` (horizontal); together they cover most CRM layout. Use it instead of ad-hoc `display: flex; flex-direction: column` divs.
+
+```tsx
+// Page sections with a larger gap:
+<Stack gap="xl">
+  <header>...</header>
+  <section>...</section>
+  <section>...</section>
+</Stack>
+
+// minWidth0 — a Stack inside a squeezing flex row, so truncating children can ellipsize:
+<Cluster wrap={false} gap="sm">
+  <Stack gap="xs" minWidth0>
+    <Text weight="medium" truncate>{deal.name}</Text>
+    <Text size="xs" tone="muted" truncate>{deal.accountPath}</Text>
+  </Stack>
+  <Badge tone="success">{deal.stage}</Badge>
+</Cluster>
+```
+
+**When NOT to use**
+
+- Tabular data: use a real `<table>` or `<Grid>`.
+- A list of clickable items: semantics matter, use `<ul><li>` with appropriate styling.
+
+**Anti-patterns**
+
+- `minWidth0` on a Stack holding buttons or badges: the container shrinks and non-truncatable content is clipped. Use it on the container whose TEXT should give way.
+- Nested Stacks with different gaps just to bend spacing locally. Sometimes legitimate (page sections at `xl` containing field stacks at `md`), but it usually signals unclear hierarchy.
+- A Stack with one or two children (`<Stack><Button /></Stack>`) is noise; inline the child.

package/docs/components/StagePath.md

@@ -0,0 +1,66 @@
+# `<StagePath>` — chevron row of record stages
+
+A record's ordered stages as interlocking chevrons: done (tinted), current (solid), upcoming (neutral). Read-only by default; pass `onValueChange` to make every non-current stage a button. `tone` recolours done + current once the record reaches an outcome.
+
+```tsx
+import { Button, Cluster, StagePath } from '@eocrm/design-system';
+
+<Cluster wrap={false}>
+  <StagePath
+    aria-label="Deal stage"
+    stages={[
+      { id: 'lead', label: 'Lead' },
+      { id: 'qualified', label: 'Qualified' },
+      { id: 'proposal', label: 'Proposal' },
+      { id: 'negotiation', label: 'Negotiation' },
+    ]}
+    value={deal.stage}
+    tone={deal.outcome === 'won' ? 'success' : deal.outcome === 'lost' ? 'danger' : 'default'}
+    onValueChange={(id) => moveDeal(deal.id, id)}
+  />
+  <Button variant="success">Won</Button>
+  <Button variant="danger-outline">Lost</Button>
+</Cluster>;
+
+// Read-only (list rows, previews, no permission)
+<StagePath aria-label="Project stage" stages={projectStages} value={project.stage} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `stages` | `StagePathStage[]` | yes | Ordered stages, first to last. |
+| `value` | `string` | yes | Id of the current stage. Stages before it render as done, after it as upcoming. An id not in `stages` renders every stage as upcoming (and warns in development) rather than throwing. |
+| `tone` | `'default' \| 'success' \| 'danger'` | no | Outcome colour for done + current stages. See `StagePathTone`. Default: `'default'`. |
+| `onValueChange` | `((id: string) => void)` | no | Makes the path interactive: every non-current stage renders as a button that calls this with its id. The current stage is never a button. Omit for a read-only path. Whether a move is allowed (e.g. backwards) is the consumer's rule — confirm or ignore inside the handler. |
+| …native | | | plus native `<ol>` attributes |
+
+<!-- props:end -->
+
+- **Always controlled.** `value` is required; there is no internal state. `onValueChange` is a request — update `value` when the move succeeds (after a confirmation or server call if needed).
+- **Stage semantics.** `<ol>` with `aria-current="step"` on the current stage's chevron (the element focus returns to after a keyboard move); done/upcoming stages carry visually hidden, localised "completed" / "upcoming" text, so state is never colour alone.
+- **Fills its container.** `width: 100%`, equal-width stages, labels ellipsize with a tooltip only when clipped. Beside other controls, use `<Cluster wrap={false}>` so the path takes the remaining width instead of wrapping onto its own line.
+- **Every non-current stage is clickable** when `onValueChange` is passed, including going backwards. Enforce business rules in the handler.
+- **Stage ids must be unique** (they are React keys). An empty `stages` array renders an empty list (and warns, since no stage matches `value`).
+- One size (32px, matches `Button` `md`).
+- **RTL follows the nearest `dir` attribute** (an ancestor's or the path's own). `dir="auto"` is ignored (the nearest explicit `dir` wins), and RTL re-nested inside an LTR island inside an RTL page renders LTR chevrons.
+- **No pending state.** Nothing changes while `onValueChange`'s work resolves, and a double click calls it twice. Guard in the handler, or render the path read-only (omit `onValueChange`) while saving.
+- **Geometry tokens are tuned together.** The chevron-shaped focus ring is computed for the default `--stage-path-arrow` / `--stage-path-height`; overriding either skews the ring's slanted edges.
+
+#### When NOT to use
+
+- ❌ Navigation between pages → `<Breadcrumb>` / `<Tabs>`.
+- ❌ A multi-step form wizard. StagePath reflects a record's state; it doesn't drive a form flow.
+- ❌ A history of what happened and when → `<Timeline>`.
+- ❌ Percentage progress → `<Progress>`.
+
+#### Anti-patterns
+
+- ❌ Encoding the outcome as an extra stage ("Closed Lost") instead of `tone="danger"`.
+- ❌ `tone="success"` to celebrate reaching the last stage. Tone is for an outcome (won/lost), not for being on the final step.
+- ❌ More than ~7 stages: labels truncate to uselessness. Group stages or show a summary.
+- ❌ Wrapping StagePath in a wrapping `Cluster`: at `width: 100%` it drops onto its own line.

package/docs/components/StatGroup.md

@@ -0,0 +1,61 @@
+# `<StatGroup>` — responsive grid of KPI tiles
+
+```tsx
+<DashboardWidget title="Key metrics">
+  <StatGroup aria-label="Key metrics" loading={isLoading}>
+    <StatTile
+      label="Pipeline value"
+      value={formatCurrency(pipeline)}
+      trend={{ label: '12.4% vs previous period', direction: 'up' }}
+      footnote="2 deals in other currencies not included"
+      icon={<IconTile icon={<Euro size={14} />} color="blue" size="sm" />}
+    />
+    <StatTile label="Win rate" value={winRate ?? null} />
+    <StatTile
+      label="Overdue tasks"
+      value="17"
+      trend={{ label: '4 vs previous period', direction: 'up', sentiment: 'negative' }}
+    />
+  </StatGroup>
+</DashboardWidget>
+```
+
+TL;DR: a `<ul>` grid of 1–8 [`StatTile`](StatTile.md)s for a dashboard widget that shows several numbers at once. Tiles reflow by available width (`minColumnWidth`, auto-fit). In a cell narrower than one column a single tile shrinks instead of overflowing, and very narrow tiles drop the icon and shrink the value. Put it in `DashboardWidget` `variant="stats"` (compact padding, leaves slack in a 3-row cell; `standard` also works): its body scrolls if the tiles overflow the cell.
+
+**Surface:** `variant="filled"` (default) is a muted tile with no border — right inside a `Card` / `DashboardWidget`. `variant="card"` gives every tile the card background, border and shadow, for a group sitting directly on the page background next to other `Card`s. Don't use `card` inside a Card (card-in-card). The `Progress` track and skeletons stay visible on both surfaces.
+
+**Loading:** `loading` keeps labels and icons and replaces each value and trend with a skeleton, so the placeholder has the real layout. Each tile's value slot carries visually hidden "Loading…" (read when browsing the tiles); no `aria-busy`: the per-tile hidden text already carries the state. There is deliberately no live region: a dashboard loads many widgets at once, and per-widget announcements would flood screen readers. Announce "dashboard loaded" once at page level if needed. Footnotes hide while loading (they describe data that is not there yet).
+
+**Accessibility:** give the group a name (`aria-label`, or `aria-labelledby` pointing at the widget title). Screen readers read each tile in DOM order: label, value, trend ("Increase 12.4% vs previous period"), footnote.
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `minColumnWidth` | `string` | no | Minimum tile width before the grid drops a column (auto-fit). Any CSS length. Clamped to the group's width, so in a cell narrower than one column a single tile shrinks instead of overflowing. Default `'11rem'`. |
+| `gap` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | no | Gap between tiles. `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32). |
+| `loading` | `boolean` | no | Loading state for every tile: labels and icons stay; each value and trend becomes a skeleton with visually hidden "Loading…" in the value slot, and footnotes hide. Deliberately NO live region: a dashboard loads many widgets at once, so announcements would flood screen readers. No `aria-busy`: the per-tile hidden text already carries the state. Default `false`. |
+| `variant` | `'filled' \| 'card'` | no | Surface of every tile, so a group stays consistent. Default `'filled'`. - `'filled'` — muted fill, no border. Use inside a `Card` / `DashboardWidget`. - `'card'` — card background, border and shadow, matching `Card`s on a page background; avoid inside a Card (card-in-card). |
+| `children` | `ReactNode` | no | `StatTile` elements. |
+| …native | | | plus native `<ul>` attributes |
+
+<!-- props:end -->
+
+**When NOT to use:**
+
+- One number per card: use `DashboardWidget variant="kpi"`.
+- Key/value facts that are not metrics (owner, stage, created date): use `DefinitionList`.
+- A chart or a list of records: use `DashboardWidget variant="chart"` / `"list"`.
+
+#### Anti-patterns
+
+- ❌ Hand-composing `Grid` + `IconTile` + `Text` tiles. You lose the trend semantics, the "no data" text and the loading state.
+- ❌ `<StatTile>` outside a `StatGroup`. It renders an `<li>` and reads `loading` from the group.
+- ❌ `value="—"` for missing data. Pass `value={null}` so screen readers hear "No data" instead of silence or "em dash".
+- ❌ Unformatted values (`value={1240000}`). Format before passing, using compact notation for large amounts: `Intl.NumberFormat(locale, { style: 'currency', currency, notation: 'compact', maximumSignificantDigits: 3 })` gives `€1.24M`, not `€1,240,000`.
+- ❌ Colouring a "bad" increase with `direction: 'down'`. Keep `direction` truthful and set `sentiment: 'negative'`.
+- ❌ More than about 8 tiles in one widget. Split into two widgets.
+- ❌ Putting a `StatGroup` in a parent that sizes to its content (a `Cluster` item, `width: max-content`, an `auto` `Split` aside). Each tile is a size container, so it contributes no intrinsic width and the tiles collapse. Give the parent a concrete width; a `DashboardWidget` cell already has one.

package/docs/components/StatTile.md

@@ -0,0 +1,58 @@
+# `<StatTile>` — one KPI tile inside a StatGroup
+
+```tsx
+<StatGroup aria-label="Sales performance">
+  <StatTile
+    label="Revenue"
+    value="€86,400"
+    trend={{ label: '3.1% vs previous period', direction: 'down' }}
+  />
+</StatGroup>
+```
+
+TL;DR: label, large value, optional trend, footnote and icon, on a filled tile (or a card surface, via `StatGroup`'s `variant`). Only valid as a child of [`StatGroup`](StatGroup.md), which owns the grid, the `<ul>` and the loading state. See `StatGroup.md` for loading and accessibility.
+
+- `value={null}` / `undefined` shows "—" with visually hidden "No data". `0` is data and renders as `0`.
+- `trend` is the same shape as `DashboardWidgetTrend`. `sentiment` defaults from `direction` (up → positive, down → negative, flat → neutral); override it when up is bad.
+- `icon` is decorative and rendered as-is before the label; pass an `IconTile` (`size="sm"`). It hides in very narrow tiles.
+- `sparkline` takes a [`Sparkline`](Sparkline.md) (or any node) and renders it under the trend, above the footnote. While the group is loading it becomes a sparkline-height skeleton. In `DashboardWidget variant="kpi"`, pass the `Sparkline` as `children` instead.
+- `progress={{ value, max, tone? }}` adds a quota meter under the value/trend (before the sparkline): a small `Progress` named by the tile `label` (no `aria-label` needed), with a progress-height skeleton while loading. Put the readable "used / limit" in `value`; use `tone` for near/over-limit:
+
+  ```tsx
+  <StatTile
+    label="Storage"
+    value="1.2 GB / 5 GB"
+    progress={{ value: 1.2, max: 5, tone: 1.2 / 5 > 0.9 ? 'warning' : 'default' }}
+  />
+  ```
+
+  Over the limit the bar shows full (the `value` text carries the overage); no meter renders when `max` isn't positive or a number isn't finite (unlimited plan, limit still loading). This is the supported quota meter — don't put a `Progress` in the `sparkline` slot.
+
+- The tile surface (`filled` or `card`) is set once for the whole group by `StatGroup`'s `variant`.
+- Format large values compactly (`€1.24M`, not `€1,240,000`): the value is `3xl` in a tile at least 11rem wide by default (`minColumnWidth`), and long numbers wrap. Use `Intl.NumberFormat(locale, { style: 'currency', currency, notation: 'compact', maximumSignificantDigits: 3 })`.
+- The hidden trend words ("Increase / Decrease / No change") come from the `dashboardWidget.trendUp` / `trendDown` / `trendFlat` i18n keys, shared with `DashboardWidget`; override with `<I18nProvider overrides={{ dashboardWidget: { trendUp: '…' } }}>`, which also changes `DashboardWidget`'s KPI trend.
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | yes | What the number is, e.g. "Pipeline value". Read first by screen readers. |
+| `value` | `ReactNode` | yes | The pre-formatted value: an integer, currency or percentage (`"€1.24M"`, `"38%"`). Required so "no data" is explicit: pass `null` (or `undefined`) and the tile shows "—" with visually hidden "No data". `0` is data and renders as `0`. |
+| `trend` | `DashboardWidgetTrend` | no | Delta under the value, e.g. `{ label: '12.4% vs previous period', direction: 'up' }`. Arrow + hidden "Increase / Decrease / No change"; colour from `sentiment`, which defaults from `direction` (up → positive). Override when up is bad (overdue tasks). |
+| `footnote` | `ReactNode` | no | Small muted note under the trend, e.g. "2 deals in other currencies not included". Hidden while loading. |
+| `icon` | `ReactNode` | no | Decorative icon before the label, typically `<IconTile size="sm" … />`. Hidden in very narrow tiles. |
+| `sparkline` | `ReactNode` | no | Trend graphic under the value/trend, typically `<Sparkline label=… values=… />`. Replaced by a sparkline-height skeleton while the group is loading. |
+| `progress` | `StatProgress` | no | Quota meter under the value/trend: "used / limit" tiles, e.g. `value="1.2 GB / 5 GB" progress={{ value: 1.2, max: 5 }}`. Renders a small `Progress` named by the tile `label` (no `aria-label` needed); progress-height skeleton while the group is loading. Put the readable "used / limit" text in `value`. Over the limit, the bar shows full (ARIA value clamped to `max`); the text in `value` carries the overage. No meter renders when `max` is not positive or a number is not finite (an unlimited plan, a limit still loading). |
+| …native | | | plus native `<li>` attributes |
+
+<!-- props:end -->
+
+**When NOT to use:** a single KPI card (`DashboardWidget variant="kpi"`), or a standalone tile outside a group.
+
+#### Anti-patterns
+
+- ❌ Wrapping `StatTile` in another element inside `StatGroup`: the `<li>` must be a direct child of the `<ul>`.
+- ❌ Putting interactive controls in a tile. Tiles are read-only; link out from the widget's actions instead.