@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/Sticky.md

@@ -0,0 +1,69 @@
+# `<Sticky>` — sticky-positioning primitive
+
+Pins its box to the top of the scroll container while the page scrolls past — for a record/detail-page sidebar (owner, tags, linked records) that stays in view while the wide main column scrolls. Sets `align-self: start` so it also works as a grid/flex item. Positions its OWN box only (put a `Stack`/`Cluster` inside to arrange the pinned content).
+
+```tsx
+// Detail page: main column scrolls, sidebar pins. align="stretch" gives the
+// aside track full height so the Sticky has a tall containing block to pin within.
+<Split
+  side="end"
+  asideWidth="320px"
+  align="stretch"
+  aside={
+    <Sticky top="md">
+      <Stack gap="md">{sidebarCards}</Stack>
+    </Sticky>
+  }
+>
+  <Stack gap="lg">{fields}</Stack>
+</Split>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `top` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'topbar'` | no | Offset from the top of the scroll container at which the content pins. Defaults to `'none'` (`top: 0`, flush). Use `'topbar'` inside an AppLayout with pinned TopBar; spacing steps add breathing room without chrome clearance. |
+| `scroll` | `boolean` | no | Cap the pinned box at the viewport height and scroll its content internally, so a column TALLER than the screen stays fully reachable (the overflow scrolls within the box instead of below the fold). Sets `max-height` to `calc(100dvh - top offset - bottom gap)`, `overflow-y: auto`, and `overscroll-behavior: contain` (page scroll doesn't chain from the box). The bottom gap defaults to the selected rhythm offset; `top="topbar"` instead defaults it to the standard content gap so chrome height is not subtracted twice. Set `--sticky-bottom-gap` on this element to override either default. Default `false`. Pair with a non-`none` `top` to leave breathing room. The cap is viewport-relative (`dvh`), so this assumes the page (or a viewport-tall ancestor) is the scroll context — not a short fixed-height scroll container. |
+| `layer` | `boolean` | no | Raise the pinned box above positioned/stacked page content (e.g. DashboardCanvas cells) so a page-level sticky bar is not painted over or click-blocked by them. Sets `z-index` just below the TopBar. Default `false`. Caveat: `z-index` on a sticky box creates a stacking context, so don't use it on a Split aside that hosts inline (non-portaled) popovers, which would be trapped inside it. |
+| `surface` | `boolean` | no | Paint the box with the page background always; while pinned, also a bottom divider and a strip over the gap above it (the `top` offset), so content scrolling underneath doesn't show through. Pinned state is tracked with an IntersectionObserver (`data-pinned`). For page-level bars. Default `false`. |
+| `children` | `ReactNode` | yes | The content to pin. Required — a `Sticky` with nothing inside pins nothing. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Sticky defaults are emitted by the global token entry, so a consumer `:root` override loaded after `@eocrm/design-system/styles/tokens.scss` wins predictably. Override `--sticky-top-topbar` to match custom application chrome.
+- Inside a `<Split>` aside, pair with `align="stretch"` (else the content-height aside track gives nowhere to pin).
+- As a `<Split collapseBelow>` aside, it automatically becomes a plain block (no pin, no `scroll` cap/inner scroll) while the Split is stacked — no consumer shim needed. Applies only when the `Sticky` is the `aside` itself.
+
+When NOT to use: arranging children → `<Stack>`/`<Cluster>`; a fixed overlay above content → `position: fixed` chrome (`Popover`/`Modal`/app bar); the split itself → `<Split>`. Note: `position: sticky` breaks if a clipping ancestor (`overflow: hidden/auto`) isn't the intended scroll container.
+
+```tsx
+// A standalone sticky filter rail next to a long list:
+<Sticky top="lg">
+  <FilterPanel />
+</Sticky>
+
+// Clear AppLayout's pinned TopBar with the standard content gap:
+<Sticky top="topbar" scroll>
+  <FilterPanel />
+</Sticky>
+
+// A page-level edit toolbar that stays above positioned content (DashboardCanvas cells):
+<Sticky top="topbar" layer surface>
+  <EditToolbar />
+</Sticky>
+
+// A tall pinned sidebar that scrolls within itself when it exceeds the screen:
+<Sticky top="lg" scroll>
+  <Stack gap="md">{manyCards}</Stack>
+</Sticky>
+```
+
+- `position: sticky` pins to the nearest scrolling ancestor, so an `overflow: hidden/auto` ancestor that isn't the intended scroll container breaks it.
+- ❌ `margin` / `padding` on it for spacing: it carries sticky position only; spacing comes from the parent layout primitive.
+- ℹ️ `surface` is for page-level bars: it always paints the page background; once pinned (`data-pinned`, via IntersectionObserver) it also shows the bottom divider and covers the gap above the bar when `top` is set.
+- ❌ `layer` on a `Split` aside that hosts inline (non-portaled) popovers: `z-index` on a sticky box creates a stacking context that traps them. `layer` and `surface` are both opt-in (default `false`).

package/docs/components/Switch.md

@@ -0,0 +1,89 @@
+# `<Switch>` — binary toggle
+
+Hand-rolled track + thumb on a native `<input type="checkbox" role="switch">`. The dumb on/off toggle for settings, feature flags, and async persisted state.
+
+```tsx
+import { Switch } from '@eocrm/design-system';
+
+// Default — uncontrolled, accent tone.
+<Switch>Enable notifications</Switch>
+
+// Controlled, success tone.
+<Switch tone="success" checked={enabled} onChange={(next) => setEnabled(next)}>
+  Daily digest
+</Switch>
+
+// Async (server-persisted) toggle.
+<Switch
+  checked={enabled}
+  loading={saving}
+  onChange={async (next) => {
+    setSaving(true);
+    setEnabled(next);            // optimistic
+    try { await api.save(next); }
+    catch { setEnabled(!next); } // rollback
+    finally { setSaving(false); }
+  }}
+>
+  Two-factor auth
+</Switch>
+
+// Icon-only.
+<Switch aria-label="Mute notifications" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Visual scale. Defaults to `'md'`. - `'sm'` — 28×16 track, 12px thumb, `--font-size-sm` label. - `'md'` — 36×20 track, 16px thumb, `--font-size-md` label (default). - `'lg'` — 44×24 track, 20px thumb, `--font-size-lg` label. Note: shadows the native HTML `<input size>` attribute (meaningless on checkboxes). |
+| `tone` | `'accent' \| 'success' \| 'danger'` | no | Track color when checked (the unchecked track is always neutral muted). Defaults to `'accent'`. - `'accent'` — blue (default). - `'success'` — green. Use for affirmative toggles ("Enable notifications"). - `'danger'` — red. Use for destructive toggles ("Allow root access"). |
+| `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`. |
+| `onChange` | `((checked: boolean, e: ChangeEvent<HTMLInputElement, Element>) => void)` | no | Fires when the user toggles the switch. The first arg is the next boolean (convenience); the original change event is the second arg. Matches `<Checkbox>`'s signature. |
+| `invalid` | `boolean` | no | Toggles `aria-invalid="true"` and adds a danger-tone border to the track. Use when the switch's state has caused a validation error. |
+| `loading` | `boolean` | no | Shows a spinner inside the thumb and suppresses changes while a toggle persists to a server, keeping the native input focusable so keyboard users retain their place in the form. Announced from a polite live region the Switch owns. `aria-busy` is set too, but nothing reads it — no mainstream screen reader conveys `busy` on a non-live element. The region sits OUTSIDE the `<label>` so it does not join the input's accessible name: the name stays stable while loading, and `getByRole('switch', { name })` keeps matching. The consumer is responsible for managing the optimistic-update flow: (example below) |
+| `children` | `ReactNode` | no | Label rendered next to the track. The whole `<label>` is the click target — clicking anywhere toggles. Omit for icon-only switches + pair with `aria-label`. |
+| …native | | | plus native `<input>` attributes |
+
+**`loading`** example:
+
+<!-- prettier-ignore -->
+```tsx
+const [enabled, setEnabled] = useState(initial);
+const [saving, setSaving] = useState(false);
+
+const handleToggle = async (next: boolean) => {
+  setSaving(true);
+  setEnabled(next);            // optimistic
+  try { await api.save(next); }
+  catch { setEnabled(!next); } // rollback
+  finally { setSaving(false); }
+};
+
+<Switch checked={enabled} loading={saving} onChange={handleToggle} />
+```
+
+<!-- props:end -->
+
+- **Native `<input type="checkbox" role="switch">`**. Form submission works; AT announces as switch. `ref` and native attributes (`name`, `value`, `disabled`, `aria-label`) reach the input.
+
+#### Hard rule
+
+A switch whose toggle triggers an **immediate action** — persisting to a server or firing any side effect — MUST use the async optimistic-update flow: flip the state optimistically, set `loading` while the request is in flight, and roll back on failure (see the async toggle example above). Never fire-and-forget a side-effecting toggle — the user needs the in-flight (`loading`) and rollback feedback. A switch over pure local UI state (no side effect) may toggle synchronously.
+
+#### When NOT to use
+
+- ❌ Selecting one option from a list of mutually-exclusive choices → `<Radio>` / `<RadioGroup>`.
+- ❌ Selecting multiple from a list → `<Checkbox>`.
+- ❌ A mixed / indeterminate state ("some-but-not-all enabled") → use Checkbox's `indeterminate`.
+- ❌ Triggering an action immediately on click (no state) → `<Button>`.
+
+#### Anti-patterns
+
+- ❌ Using `placeholder`-style hints inside the track ("OFF" / "ON" text). Use a real label.
+- ❌ Toggle without an external optimistic-update flow when `loading` is set. Without it, the user clicks the switch, the spinner appears, and the visual state never changes — confusing.
+- ❌ `tone="success"` for "Mark as failed". Tone communicates the meaning of "on", not just decoration.

package/docs/components/Table.md

@@ -0,0 +1,184 @@
+# `<Table>` — tabular data primitive
+
+```tsx
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>Name</Table.HeaderCell>
+      <Table.HeaderCell align="end">Amount</Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    {rows.map((r) => (
+      <Table.Row key={r.id}>
+        <Table.Cell>{r.name}</Table.Cell>
+        <Table.Cell align="end">{r.amount}</Table.Cell>
+      </Table.Row>
+    ))}
+  </Table.Body>
+</Table>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `TableProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `density` | `'comfortable' \| 'dense'` | no | Row height + cell padding scale. Defaults to `'comfortable'`. - `'comfortable'` — 32px row, 12px horiz padding, font-size-md. - `'dense'` — 24px row, 8px horiz padding, font-size-sm. |
+| `striped` | `boolean` | no | Zebra-striped body rows (even rows tinted). Defaults to `false`. |
+| `bordered` | `boolean` | no | Full-grid borders — outer border + vertical borders between every cell on top of the existing horizontal row dividers. Defaults to `false` (Atlassian-style minimal: header underline + row dividers only). |
+| `hover` | `boolean` | no | Hover highlight on body rows. Defaults to `false` — turn on when the table represents a list of clickable / selectable items (a row a user is likely to act on). Leave off for read-only data displays where the hover affordance would suggest interactivity that isn't there. |
+| `stickyHeader` | `boolean` | no | `position: sticky` on the header so it stays visible while body scrolls. Requires a scrollable ancestor — the default `scroll` wrapper provides one. Defaults to `false`. |
+| `scroll` | `boolean` | no | When `true` (default), the `<table>` is wrapped in a `<div>` with `overflow-x: auto` so wide tables scroll horizontally inside their container. Set to `false` to render a bare `<table>` — the consumer manages their own scroll context. |
+| `layout` | `'auto' \| 'fixed'` | no | Column-layout algorithm. Defaults to `'auto'`. - `'auto'` — columns size to their content (native default). - `'fixed'` — `table-layout: fixed`: widths come from a native `<colgroup><col style={{ width }} /></colgroup>` (or the first row), and unsized columns split the rest equally. Use for grids of equal-width number columns. |
+| `children` | `ReactNode` | no | Compound-subcomponent children. |
+| …native | | | plus native `<table>` attributes |
+
+### `TableCaptionProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<caption>` attributes |
+
+### `TableCellLinkProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | no |  |
+| `as` | `ElementType` | no | Element or component to render. Defaults to `'a'`; use for router links. |
+| …native | | | plus native attributes of the `as` element (default `<a>`) |
+
+### `TableCellProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | no | Text alignment. Defaults to `'start'`. |
+| `truncate` | `boolean` | no | Suppress wrapping and ellipsize on overflow. Requires a constrained cell width (column-level CSS or `style={{ maxWidth: … }}`). |
+| `tone` | `'danger' \| 'accent'` | no | Tints the cell background and colours its text. Exposed as `data-tone`. Default: none. Set it on every cell of the column (header included). - `'danger'` — overdue / at-risk column. - `'accent'` — the current / highlighted column (e.g. "Today"). |
+| `children` | `ReactNode` | no |  |
+| …native | | | plus native `<td>` attributes |
+
+### `TableHeaderCellProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | no | Text alignment. Defaults to `'start'`. |
+| `scope` | `'row' \| 'rowgroup' \| 'col' \| 'colgroup'` | no | Native HTML `<th scope>` attribute. Defaults to `'col'` (the cell labels its column). Use `'row'` for the leftmost cell that labels its row when rendering row-headers inside `<Table.Body>`. `'colgroup'` / `'rowgroup'` are valid HTML but rarely needed in practice. |
+| `sortDirection` | `'asc' \| 'desc' \| 'none'` | no | When set, the cell renders a sort indicator (up/down/unsorted chevron) and sets `aria-sort`. The consumer drives interactivity via `onClick`; this primitive only paints the indicator. Sortable headers also become keyboard-reachable (`tabIndex={0}` + Enter/Space → `onClick`). - `'asc'` → up chevron + `aria-sort="ascending"`. - `'desc'` → down chevron + `aria-sort="descending"`. - `'none'` → muted up/down chevron + `aria-sort="none"`. Omit to render a non-sortable header (no chevron, no `aria-sort`). |
+| `tone` | `'danger' \| 'accent'` | no | Tints the header cell (top corners rounded, square under `bordered`) so a toned column reads as one band with its toned body cells. Exposed as `data-tone`. Default: none. - `'danger'` — overdue / at-risk column. - `'accent'` — the current / highlighted column (e.g. "Today"). |
+| `children` | `ReactNode` | no |  |
+| …native | | | plus native `<th>` attributes |
+
+### `TableRowProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `selected` | `boolean` | no | Visual selected state. Pair with the consumer's own selection logic. Adds `aria-selected="true"` and a subtle accent tint that wins over hover/striped. |
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<tr>` attributes |
+
+### `TableSectionProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<tbody>` attributes |
+
+<!-- props:end -->
+
+- Compound subcomponents: `Table`, `Table.Caption`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.HeaderCell`, `Table.Cell`, `Table.CellLink`. Renders native `<table>` / `<thead>` / `<tbody>` / `<tr>` / `<th>` / `<td>` / `<tfoot>` / `<caption>` — no ARIA-on-divs.
+- Visual modifiers on root: `density` (`'comfortable'` (default, 32px row) / `'dense'` (24px)), `hover` (default off — opt in for clickable / selectable row lists), `striped`, `bordered` (full-grid borders; default off — Atlassian-minimal style is just row dividers + header underline), `stickyHeader`, `scroll` (default `true` — wraps in `overflow-x: auto`).
+- `<Table.Row selected>` paints a tinted bg + `aria-selected="true"`. Selection state itself is the consumer's job.
+- `<Table.HeaderCell sortDirection>` is a visual hook: renders an up / down / unsorted chevron + sets `aria-sort`. Wire `onClick` to your own sort state. (`<DataTable>` does not use this prop: it sets `aria-sort` and draws its own chevron.)
+- `<Table.Cell align>` / `<Table.HeaderCell align>`: `'start' | 'center' | 'end'` (CSS logical, RTL-friendly). Right-aligned headers auto-flip the sort chevron to the start side.
+- `<Table.Cell truncate>` ellipses overflow text on one line. Requires a constrained cell width (`style={{ maxWidth }}` or `<col>`).
+- **`colSpan` / `rowSpan`** flow through to the native `<th>` / `<td>` via spread. Use for multi-row grouped headers (`rowSpan` on a corner cell + `colSpan` on group cells over a second `<Table.Row>`), category-grouped body rows (`rowSpan` on a leftmost cell), and footer total rows (`<Table.Cell colSpan={n}>Total</Table.Cell>`). Use `<Table.HeaderCell scope="row">` (instead of `<Table.Cell>`) for the leftmost cell when it labels its row to AT.
+- The native HTML `align` attribute on `<th>` / `<td>` is shadowed by the component-level `align` prop (logical) — `Omit<…, 'align'>` on both `*Props`.
+- `layout="fixed"` sets `table-layout: fixed` (default `'auto'`). Column widths come from a native `<colgroup><col style={{ width }} /></colgroup>`; unsized columns split the remainder equally. Use it for grids of equal-width number columns.
+- `tone="danger" | "accent"` on `<Table.Cell>` / `<Table.HeaderCell>` tints the cell and colours its text (exposed as `data-tone`). Set it on every cell of the column, header included: a toned header gets rounded top corners so the column reads as one band (square under `bordered`, where they would break the grid lines). There is no column-level tone prop.
+  - A toned cell's tint and colour win over the row's hover / selected tint, so the column stays one band across every row.
+- `<Table.CellLink>` is a full-bleed link placed as the direct child of `<Table.Cell>` (not `<Table.HeaderCell>`, which wraps its children). The cell drops its padding and the link takes it over (respecting `density`), so the whole cell is the hit area. It inherits the cell's alignment and colour and renders semibold (`--table-cell-link-font-weight`) so link cells read as actionable; hover darkens the cell (no underline — the cell-wide overlay is the hover signal), keyboard focus draws an inset ring. On hover, `tone="muted"` (and deprecated `tone="subtle"`) `<Text>` inside the link takes the link's own colour, because muted text on the hover overlay falls under AA; on a toned cell that colour is the tone's hover colour. Polymorphic `as` (default `'a'`) for router links, like `<Link>`. You supply the accessible name: when the visible text is just a number, give it an `aria-label` that says what it counts (`"Deals, overdue: 3"`). A zero shown as a dash is labelled `"…: none"` because a dash has no spoken meaning — `"Deals, today: none"`.
+- **Use `<DataTable>` instead** when you need sorting / filtering / pagination state. Table is the paint primitive; `DataTable` is the opinionated wrapper.
+
+```tsx
+// Caption and a sortable column — you own the sort state; the primitive paints the indicator and sets aria-sort:
+<Table>
+  <Table.Caption>Recent activity</Table.Caption>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell
+        sortDirection={sortKey === 'amount' ? sortDir : 'none'}
+        onClick={() => toggleSort('amount')}
+      >
+        Amount
+      </Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  ...
+</Table>
+```
+
+```tsx
+// Count grid: fixed equal-width columns, toned columns, every cell a link.
+<Table layout="fixed">
+  <colgroup>
+    <col style={{ width: '23%' }} />
+    <col />
+    <col />
+  </colgroup>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>Type</Table.HeaderCell>
+      <Table.HeaderCell tone="danger" align="end">
+        Overdue
+      </Table.HeaderCell>
+      <Table.HeaderCell tone="accent" align="end">
+        Today
+      </Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.HeaderCell scope="row">Deals</Table.HeaderCell>
+      <Table.Cell tone="danger" align="end">
+        <Table.CellLink href="/deals?due=overdue" aria-label="Deals, overdue: 3">
+          3
+        </Table.CellLink>
+      </Table.Cell>
+      <Table.Cell tone="accent" align="end">
+        <Table.CellLink href="/deals?due=today" aria-label="Deals, today: none">
+          <Text as="span" size="inherit" tone="muted">
+            –
+          </Text>
+        </Table.CellLink>
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+```
+
+**Sizing:** the `<table>` is `min-width: 100%` (not `width: 100%`), so it fills the wrap for narrow content but grows past it when cell content or explicit `<col>` widths sum wider; the default `scroll` wrapper then scrolls horizontally.
+
+**When NOT to use**
+
+- Non-tabular content (cards, lists): use `<Stack>` / `<Cluster>` / `<Card>`.
+- Editable cells: no inline editing ships; add inputs inside cells yourself.
+
+**Anti-patterns**
+
+- `<Table>` without `<Table.Body>` for data rows: native semantics require `<tbody>`.
+- A `<Link>` inside a cell when the whole cell should be clickable: only the text is the hit area and the hover/focus treatment doesn't fill the cell. Use `<Table.CellLink>`.
+- Wrapping `<Table.CellLink>` in another element inside the cell: it must be the cell's direct child, or the cell keeps its padding and the link stops being full-bleed.
+- A `<Table.CellLink>` whose only content is a number with no `aria-label`: a screen reader hears "3, link" with no row or column context.
+- `scope` on `<Table.Cell>`: it renders a `<td>`, where `scope="row"` is invalid. Use `<Table.HeaderCell scope="row">` for a row-header column.

package/docs/components/TableOfContents.md

@@ -0,0 +1,76 @@
+# `<TableOfContents>` — "On this page" navigation
+
+Lists a long page's h2/h3 headings as in-page links, highlights the one being read (scroll-spy), and scrolls to a heading on click clear of the pinned TopBar. It does not make itself sticky — wrap it in `<Sticky top="topbar">`.
+
+```tsx
+import { useState } from 'react';
+import { Split, Sticky, TableOfContents } from '@eocrm/design-system';
+
+const toc = [
+  { id: 'overview', label: 'Overview', level: 2 },
+  { id: 'install', label: 'Install', level: 3 },
+  { id: 'usage', label: 'Usage', level: 2 },
+] as const;
+
+function GuidePage() {
+  const [narrow, setNarrow] = useState(false);
+  return (
+    // Exactly one TOC at a time: a pinned rail while wide; once Split stacks, the
+    // aside is dropped (null renders no cell) and a collapsed TOC leads the main pane.
+    // align="stretch" is required for the pin: Split defaults to align="start", so the aside
+    // cell would be only as tall as the TOC and Sticky would have nothing to pin within.
+    <Split
+      side="end"
+      asideWidth="240px"
+      align="stretch"
+      collapseBelow="md"
+      onCollapsedChange={setNarrow}
+      aside={
+        narrow ? null : (
+          <Sticky top="topbar">
+            <TableOfContents items={toc} />
+          </Sticky>
+        )
+      }
+    >
+      {narrow && <TableOfContents items={toc} collapsed />}
+      <article>
+        <h2 id="overview">Overview</h2>
+        <h3 id="install">Install</h3>
+        <h2 id="usage">Usage</h2>
+      </article>
+    </Split>
+  );
+}
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `items` | `readonly TableOfContentsItem[]` | yes | Entries in document order. An empty list renders nothing. |
+| `collapsed` | `boolean` | no | Render a `<details>` disclosure (summary "On this page · <active>") instead of the heading + list. Use where there is no room for a side rail, e.g. on narrow viewports above the content. Default `false`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- `items` are explicit `{ id, label, level: 2 | 3 }`; every `id` must match a heading's `id` on the page. Level 3 is indented under the preceding level 2.
+- Exactly one `<nav>` named "On this page", in both modes. Override with `aria-label` when two TOCs share a page.
+- The active link gets `aria-current="location"`; there are no live announcements. The server render has no active item.
+- Only the **window** scrolls: scroll-spy and click-scroll ignore inner scroll containers.
+- Click scrolls smoothly (instantly under `prefers-reduced-motion`) to the heading's top minus `--sticky-top-topbar`, updates the URL hash (`pushState`, or `replaceState` when the hash is unchanged) and focuses the heading. A heading that isn't focusable gets `tabindex="-1"` added, and keeps it.
+- Modifier clicks (cmd/ctrl/shift/alt, non-primary button) and ids with no matching element fall through to native link behaviour.
+- Scrolled to the bottom of the page, the last item is active (short final sections can't otherwise reach the top). A page too short to scroll counts as scrolled to the bottom, so its last item is active.
+- The hash update uses `history.pushState` / `replaceState`, which fire no `hashchange`: router or `hashchange` listeners don't see the jump.
+- `collapsed` renders a `<details>` disclosure (summary "On this page · active heading"); choosing an entry closes it.
+- Empty `items` renders nothing.
+- For `#hash` links opened directly (not via a click) to clear the bar, add `html { scroll-padding-top: var(--sticky-top-topbar); }` to the app's global CSS.
+
+When NOT to use: app or page-level navigation → `Rail` / `Tabs`; short pages with a few headings need no TOC; headings inside an inner scroll container (only the window is tracked).
+
+- ❌ Omitting the `<Sticky top="topbar">` wrapper and expecting the rail to pin: the component is not sticky.
+- ❌ `items` ids that don't match heading ids: the entry renders but never becomes active, and clicking falls back to native jump (no TopBar offset).
+- ❌ Rendering the rail TOC and the collapsed TOC together: that yields two "On this page" navs. Render one at a time (`narrow ? null : rail`, `narrow && collapsed`).

package/docs/components/Tabs.md

@@ -0,0 +1,94 @@
+# `<Tabs>` — tab strip (horizontal or vertical)
+
+```tsx
+const [tab, setTab] = useState('overview');
+
+<Tabs
+  items={[
+    { id: 'overview', label: 'Overview', icon: <Eye size={14} /> },
+    { id: 'activity', label: 'Activity', icon: <Activity size={14} />, count: 12 },
+  ]}
+  activeId={tab}
+  onChange={setTab}
+/>;
+{
+  tab === 'overview' && <OverviewPanel />;
+}
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `items` | `TabItem[]` | yes | The tabs to render. Each item must have a unique `id`. |
+| `activeId` | `string` | yes | The id of the currently-active tab. If it doesn't match any item, the strip still stays keyboard-reachable (first tab gets tabindex=0). |
+| `onChange` | `(id: string) => void` | yes | Called with the tab id when the user activates a different tab. Won't fire when re-clicking the already-active tab. |
+| `panelIdPrefix` | `string` | no | Optional id prefix for controlled tabpanels. When set, the ACTIVE tab gets `aria-controls="${panelIdPrefix}-${itemId}-panel"` — the consumer must render the matching panel with that id. When omitted, NO tab carries `aria-controls` at all — the internal id (sanitized React `useId`) named below is the tab's own id, not a panel's, and pointing at it would be the dangling IDREF that was removed. Only the active tab carries it, because consumers render only the active panel; stamping every tab would point N-1 of them at elements that do not exist. Inactive tabs keep their own `id` for the panel's `aria-labelledby` to reference. |
+| `activationMode` | `'auto' \| 'manual'` | no | `'auto'` (default): arrow keys move focus AND fire onChange — the visible panel changes with each keystroke. Best for cheap, eager-rendered panels. `'manual'`: arrow keys only move focus; Enter/Space (the native button activation keys) then commits via onChange. Use this when panels are expensive (lazy-load, network) so the user can scan tab labels without triggering loads. |
+| `orientation` | `'horizontal' \| 'vertical' \| 'auto'` | no | `'horizontal'` (default) — a horizontal strip with a sliding underline. `'vertical'` — a stacked master–detail rail: full-width rows, a left accent bar + tinted background on the active row, and ArrowUp/ArrowDown navigation. `'auto'` — measures available Tabs/tab-strip width: vertical below `autoOrientationBreakpoint` and horizontal at or above it. It starts vertical during SSR and whenever `ResizeObserver` is unavailable. Use it with a collapsing `Split`: the fixed-width aside remains a vertical rail, then the full-width stacked tablist becomes horizontal. `aria-orientation`, keyboard navigation, and presentation always follow the effective orientation. |
+| `autoOrientationBreakpoint` | `number` | no | Available tab-strip width in px where `orientation="auto"` switches from vertical to horizontal. Defaults to `320`. Set this per Tabs instance to align automatic orientation with the surrounding layout's threshold. |
+| `action` | `TabsAction` | no | A trailing action rendered after the tab items, inside the same strip (e.g. `{ label: 'New deal', icon: <Plus/>, onClick: addDeal }`). Styled tab-like but visibly muted, never becomes the selected tab, and is skipped by arrow-key roving — reachable via the Tab key instead. For controls that apply to the whole bar but aren't shaped like a tab (a filter toggle), use `endContent`. For a control on a single tab, use `TabItem.actions`. |
+| `endContent` | `ReactNode` | no | Controls for the whole tab bar (e.g. an "add tab" button, a filter toggle), rendered at the end of the strip OUTSIDE the tablist so it never scrolls with the tabs and is not part of tab keyboard navigation. For a control attached to a single tab, use `TabItem.actions` instead. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+```tsx
+// Responsive master–detail rail:
+<Split
+  asideWidth="220px"
+  collapseBelow="sm"
+  aside={
+    <Tabs
+      orientation="auto"
+      items={[
+        { id: 'general', label: 'General' },
+        { id: 'security', label: 'Security', trailing: <Badge tone="warning">Unsaved</Badge> },
+        { id: 'billing', label: 'Billing', count: 3 },
+      ]}
+      activeId={section}
+      onChange={setSection}
+    />
+  }
+>
+  <SectionPanel id={section} />
+</Split>
+```
+
+- `items: { id, label, icon?, count?, leading?, trailing?, actions? }[]` — `id` must be unique. `icon` is a decorative leading glyph; `count` renders as a chip after the label. `leading`/`trailing` are free-form ReactNode adornments (status dot, unsaved-changes `Badge`); they are NOT `aria-hidden`, so give meaningful ones accessible text. In vertical orientation `trailing` pins to the row's right edge.
+- `actions` on a `TabItem` renders **interactive** control(s) (a `Switch`, a close button, a `⋯` menu) OUTSIDE that tab's `role="tab"` button — use it for anything focusable/clickable (a `Badge` or a static status dot stays in `leading`/`trailing`, which render _inside_ the button). `endContent` (a `TabsProps` slot) renders controls for the whole bar (an "add tab" button, a filter toggle) at the end of the strip, outside the tablist, so they never scroll with the tabs and aren't part of arrow-key tab navigation. Keyboard: arrows rove tabs only; `Tab` reaches a tab's `actions`, then `endContent`. Each per-tab `actions` adds a Tab stop, so they're cleanest on the active tab or a handful of tabs.
+- `attrs` on a `TabItem` (``Record<`data-${string}`, string>``) spreads onto that tab's `role="tab"` button, before the component's own attributes (a key can't override the `id`/`role`/`aria-*`/handlers Tabs owns). Use it to target one tab from a `Tour` or to add a test/analytics id: `{ id: 'sec', label: 'Security', attrs: { 'data-tour': 'security-tab' } }`, then `<Tour steps={[{ target: 'security-tab', title: '...' }]} />`.
+- The active-tab underline slides between tabs when `activeId` changes. Respects `prefers-reduced-motion: reduce`.
+- `action?: { label, icon?, onClick, disabled? }` renders a `+ New entity`-style button-like pseudo-tab after the tab items, inside the same strip — tab-shaped but visibly muted, NOT `role="tab"`, never selected, skipped by arrow-key roving (reachable via `Tab` instead), and the sliding indicator never targets it. It only fires `onClick`; if the click should change `activeId`, do that yourself in the handler (e.g. append + select a new tab). Known, accepted a11y tradeoff: like the `TabItem.actions` button, this leaves one non-`"tab"` child in the `role="tablist"` container (an `aria-required-children` deviation) — a real `<button>` still announces correctly to assistive tech regardless of its parent's role.
+
+```tsx
+// Lazy-loaded panels — manual mode, so arrows scan without loading:
+<Tabs items={items} activeId={tab} onChange={setTab} activationMode="manual" />
+
+// Trailing action — a button-like pseudo-tab that never becomes selected:
+<Tabs
+  items={items}
+  activeId={tab}
+  onChange={setTab}
+  action={{ label: '+ New entity', icon: <Plus size={14} />, onClick: createEntity }}
+/>
+```
+
+Implements the WAI-ARIA Tabs pattern: roving `tabIndex`, arrow keys (Left/Right horizontal, Up/Down vertical) plus Home/End, `aria-controls`, `aria-orientation`, per-tab/per-panel ids. Controlled: pass `activeId` and `onChange`.
+
+**When NOT to use**
+
+- Navigation between pages: use the sidebar or breadcrumbs. Tabs switch views within a page.
+- 5+ tabs: usually the entity is doing too much; split the page or rethink the IA.
+- When the user may want two views at once: use side-by-side panels.
+
+**Anti-patterns**
+
+- Lazy-loading tab content but losing form state on switch: preserve state or warn before data is lost.
+- The page's primary action inside a tab: it belongs in the page header.
+- `orientation="vertical"` as a page sidebar / primary navigation: it is for intra-page section switching, not route changes.
+- `orientation="auto"` combined with app-owned viewport measurement: auto measures the available strip width, so let it react to the `Split`'s layout instead of duplicating breakpoint state.
+- `action` to switch views: it never sets `activeId`; if the click should select a tab, add a `TabItem`.

package/docs/components/Text.md

@@ -0,0 +1,63 @@
+# `<Text>` — body / inline text
+
+```tsx
+<Text>Default body — block <p>, md, regular.</Text>
+<Text as="span" size="sm" tone="muted">12m ago</Text>
+<Text as="label" htmlFor="email" weight="medium">Email</Text>
+<Text lineClamp={2}>A long description that wraps and ellipses after two lines.</Text>
+<Text size="sm" tone="danger">Email is required.</Text>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `htmlFor` | `string` | no | Associates a `<label>` with its form control. Only meaningful when `as="label"` — passes through as the native `for` attribute. |
+| `as` | `'p' \| 'span' \| 'div' \| 'label'` | no | Rendered element. Defaults to `'p'` (block, default body text). Use `'span'` for inline runs, `'div'` for block containers that can't be a `<p>` (e.g. when the body needs nested block-level elements that React would warn about inside `<p>`), `'label'` for form labels (pair with `htmlFor`). |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'inherit'` | no | Visual size. Defaults to `'md'` (body text). - `xs` — 11px, dense metadata / captions - `sm` — 12px, small body / labels - `md` — 14px, body text (default) - `lg` — 16px, large body / lead text - `xl` — 20px, very large body (rare) - `inherit` — no fixed size; font-size AND line-height inherit from the parent. For inline runs inside a heading (`as="span"` inside a `<Title>` / `<PageHeader.Title>`) that must keep the heading's size — e.g. a muted task-key prefix. Tone / weight still apply — font-weight stays Text's own (default `regular`), it does NOT inherit; pass `weight` to match the heading if needed. |
+| `tone` | `'default' \| 'muted' \| 'subtle' \| 'accent' \| 'danger' \| 'success' \| 'warning'` | no | Color tone. Defaults to `'default'`. - `default` — `--color-fg` - `muted` — `--color-fg-muted` (for secondary copy) - `subtle` — **@deprecated: resolves to `muted`. Use `muted`.** In LIGHT theme the two neutrals were indistinguishable: OKLab ΔE 0.0261 when the deprecation was filed, 0.0365 after `--color-fg-muted` was retuned, against the 0.065 floor this library's perceptual gates use. In DARK they were 0.0707 apart — a real step — so **this deprecation changes dark-theme appearance**: `subtle` text in dark gets lighter, moving from `--color-fg-subtle` to `--color-fg-muted`. That is the accepted trade (a tier that exists in one theme only is not a tier), but it is a visual change, not the removal of a duplicate. `--text-fg-subtle` now aliases `--text-fg-muted`, so nothing breaks at the type or build level; if you need the old dark value back, override `--text-fg-subtle`. - `accent` — `--color-accent` - `danger` / `success` / `warning` — state-coded text |
+| `weight` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` | no | Font weight. Defaults to `'regular'`. |
+| `align` | `'left' \| 'center' \| 'right'` | no | Text alignment. Defaults to `'left'`. |
+| `truncate` | `boolean` | no | Truncate to a single line with ellipsis. Defaults to `false`. Use inside narrow containers (table cells, card list rows). Mutually exclusive with `lineClamp` — if both are set, `lineClamp` wins. |
+| `lineClamp` | `number` | no | Clamp to N lines with ellipsis (uses `-webkit-line-clamp`). Defaults to `undefined`. Overrides `truncate` when set. Example: `lineClamp={2}` for a 2-line description that ellipses on the third. If you also pass `style.WebkitLineClamp`, the `lineClamp` prop takes precedence — the component merges the dynamic line-clamp value into `style` AFTER spreading your `style`, so the prop wins. |
+| `children` | `ReactNode` | yes | Text content. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- `as: 'p' | 'span' | 'div' | 'label'` (default `'p'`). Constrained string union — no polymorphic generic.
+- `size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'inherit'` (default `'md'`).
+- **Use `<Text>` for every non-heading run.** No more `<span style={{ fontSize: 'var(--font-size-sm)', color: 'var(--color-fg-muted)' }}>`.
+- **`size="inherit"`** — for a muted/toned inline run INSIDE a heading (e.g. `<Text as="span" size="inherit" tone="muted">ENG-5</Text>` at the start of a `<Title order={1}>` task name) that must keep the heading's size instead of shrinking to `md`. Font-size AND line-height both inherit from the parent.
+
+```tsx
+// Muted inline run inside a heading — keeps the heading's font size:
+<Title order={1}>
+  <Text as="span" size="inherit" tone="muted">ENG-5</Text> Fix login
+</Title>
+
+// Body copy under a heading, spaced with Stack — the canonical CRM-page shape:
+<Stack gap="xs">
+  <Title order={2}>Pipeline</Title>
+  <Text tone="muted">Active deals for Q3.</Text>
+</Stack>
+```
+
+If you need a size or tone the primitive doesn't expose, that is a token-vocabulary conversation, not a reason to skip the component.
+
+**When NOT to use**
+
+- Heading text: use `<Title order={N}>`.
+- Inline code: use `<Code>`.
+- Clickable text / action triggers: use `<Button>` or `<Link>`.
+- Pure layout containers: use `<Stack>` / `<Cluster>` / `<Grid>`.
+
+**Anti-patterns**
+
+- `<Text style={{ color: '#someHex' }}>`: pick a tone from the whitelist; the whitelist is the contract.
+- `<Text as="h2">`: Text doesn't accept heading tags; use `<Title order={2}>`.
+- Wrapping a `<Title>` in `<Text>` for tone/weight tweaks: pass tone/weight to the `<Title>`. `size="inherit"` is for runs INSIDE a heading, not for wrapping it.
+- Nesting `<Text>` in another `<Text>` with the default `as="p"`: the inner `<p>` inside the outer `<p>` is invalid HTML and triggers React's DOM nesting warning. Use `<Text as="span" tone="...">` for an inline override inside a paragraph.