@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/TopBar.md

@@ -0,0 +1,214 @@
+# `<TopBar>` — sticky application top bar
+
+Horizontal app-chrome bar pinned to the top of the viewport. Compound API: `<TopBar.Start>` + `<TopBar.End>` for the two horizontal clusters, plus `<TopBar.Search>` (styled `<input type="search">` with a leading icon and an optional `<kbd>` hotkey hint) and `<TopBar.IconButton>` (icon-only ghost button with an optional notification-dot indicator).
+
+```tsx
+import { Avatar, TopBar } from '@eocrm/design-system';
+import { Bell, Plus } from 'lucide-react';
+
+<TopBar>
+  <TopBar.Start>
+    <TopBar.Search placeholder="Search contacts, deals…" hotkey="⌘K" />
+  </TopBar.Start>
+  <TopBar.End>
+    <TopBar.IconButton aria-label="Create new">
+      <Plus size={16} />
+    </TopBar.IconButton>
+    <TopBar.IconButton aria-label="Notifications, 3 unread" indicator>
+      <Bell size={16} />
+    </TopBar.IconButton>
+    <Avatar name="Alex Rivera" size="sm" />
+  </TopBar.End>
+</TopBar>;
+```
+
+<!-- props:start -->
+
+## Props
+
+### `TopBarProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `as` | `'header' \| 'div'` | no | Element to render. Defaults to `'header'`. Pick `'div'` when the bar is nested inside another content area where a second `<header>` landmark would conflict with page semantics. |
+| `aria-label` | `string` | no | Accessible label for the bar's landmark. Defaults to `t('topBar.label')` when omitted OR empty — an empty string is not an explicit name — so screen readers always announce a name for the region. Override when a page has multiple bars to disambiguate them. |
+| `children` | `ReactNode` | no | Children of the bar — typically `<TopBar.Start>` + `<TopBar.End>`. The children area is open so consumers can render a single cluster, a single trailing element, or any other arrangement they need. |
+| …native | | | plus native HTML attributes |
+
+### `TopBarEndProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| …native | | | plus native `<div>` attributes |
+
+### `TopBarIconButtonProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Icon to render inside the button. Typically a single lucide icon (e.g. `<Bell size={16} />`). The wrapping button supplies the accessible name via `aria-label` — the icon itself is decorative. |
+| `indicator` | `boolean` | no | Show a small dot in the upper-right corner of the button. Useful for "unread notifications", "pending updates", etc. The dot is purely visual (`aria-hidden`); the consumer is responsible for surfacing count / status text to assistive tech, typically via the button's `aria-label` or a hidden span. |
+| `indicatorTone` | `'danger' \| 'warning' \| 'info' \| 'accent'` | no | Dot color. Defaults to `'danger'` (red). See `TopBarIndicatorTone` for the full option set. |
+| `aria-label` | `string` | yes | **Required.** Accessible name for the icon-only button — without it, screen readers announce nothing. Phrase as an action (`'Notifications'`, `'Create new'`). Include count info here when the indicator is on (e.g. `'Notifications, 3 unread'`). |
+| …native | | | plus native `<button>` attributes |
+
+### `TopBarSearchProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `hotkey` | `string \| string[]` | no | Optional hotkey hint shown after the input. Rendered internally via `<Kbd size="sm">`. Pass an **array** of key labels for a multi-key combo (`['⌘', 'K']` → two chips joined with `+`) or a single string for a one-chip hint (`'Esc'` → one chip). Note: `'⌘K'` is treated as a single chip — use the array form for multi-key combos. The hint is **visual only**; the library does not bind any keyboard shortcut to it. Omit for no hint. |
+| `className` | `string` | no | `className` for the wrapping `<div>` (the search surface itself). The input's own className lives on the underlying `<input>` via the spread input-props (use the standard `inputClassName` pattern if you need to target the inner element specifically — not exposed in v1). |
+| `results` | `TopBarSearchGroup[]` | no | Turns on combobox mode: the input gets `role="combobox"` and a results panel opens under it. Presence switches the mode — pass `[]` (not `undefined`) while there are no results yet. You filter or fetch; the library owns keyboard, focus, dismissal, positioning and announcements. The first row is highlighted whenever the set of ids changes, so Enter opens the top hit. |
+| `open` | `boolean` | no | Controlled panel visibility. Omit for uncontrolled. |
+| `defaultOpen` | `boolean` | no | Uncontrolled initial visibility. Default `false`. |
+| `onOpenChange` | `((open: boolean) => void)` | no | Called when the panel wants to open (focus, typing, ↓) or close (Esc, blur, selection). |
+| `onSelect` | `((item: TopBarSearchItem, groupIndex: number) => void)` | no | Called on Enter or click on a result. The input text is left as is — clear it here if wanted. |
+| `loading` | `boolean` | no | Shows a loading row and sets `aria-busy`; existing results stay visible and the live region keeps announcing their count. |
+| `emptyMessage` | `ReactNode` | no | Row shown for a non-empty query with no results. Default `t('topBar.searchEmpty')` (also used when this is an empty string). A non-string node is rendered but the live region still announces the default text — pass a string to have it announced. |
+| `footerAction` | `TopBarSearchFooterAction` | no | Trailing row in the ↑/↓ cycle (e.g. "View all results"). Rendered whenever the panel is shown (results, loading row, or empty row), as the last row. |
+| …native | | | plus native `<input>` attributes |
+
+### `TopBarStartProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Compound API** — `TopBar.Start` / `TopBar.End` / `TopBar.Search` / `TopBar.IconButton`.
+- **Layout-owning primitive (Hard rule 4 exception)** — like `<Modal>`, `<Drawer>`, `<Page>`, `<Rail>`, the bar owns its own height (56px), sticky positioning, padding, background, and bottom border because that IS its job as a top-bar chrome.
+- **`<TopBar.Start>`** — flex-grows (`flex: 1`) so a sibling `<TopBar.End>` is pushed to the right edge with no spacer needed.
+- **`<TopBar.End>`** — shrinks to its content. Use for trailing actions + avatar.
+- **`<TopBar.Search>`** — a real `<input type="search">` (browsers expose `role="searchbox"`). `placeholder` is consumer-controlled. `aria-label` defaults to the placeholder, then to `t('topBar.search')`. The `hotkey` prop renders a trailing `<kbd>` hint — purely **visual**; binding ⌘K to focus is the consumer's responsibility. Spread `value` / `onChange` through normally — they reach the underlying input. The component sets `autoComplete="off"` plus `data-1p-ignore` / `data-lpignore` / `data-form-type="other"` so password managers and browser autofill skip it.
+- **i18n**: `topBar.label` (default `<header>` aria-label), `topBar.search` (default `<input>` aria-label fallback), `topBar.searchEmpty` (default empty-results row), `topBar.searchLoading` (loading row + announcement), `topBar.searchResults` (result-count announcement).
+- **Type note**: `TopBarSearchProps` omits the native `onSelect` (text-selection event) and the legacy `results` input attribute in favour of the combobox props below.
+
+### Combobox mode (`results`)
+
+Passing `results` (even `[]`) turns the pill into an ARIA combobox with a results panel. You filter or fetch; the library owns keyboard, focus, dismissal, positioning and announcements.
+
+```tsx
+const [q, setQ] = useState('');
+const { data, isFetching } = useSearch(q); // your fetch; returns TopBarSearchGroup[]
+// If you debounce, set `loading` synchronously in onChange (see below) instead of waiting for isFetching.
+
+<TopBar.Search
+  placeholder="Search contacts, deals…"
+  hotkey={['⌘', 'K']}
+  value={q}
+  onChange={(e) => setQ(e.target.value)}
+  results={data ?? []}
+  loading={isFetching}
+  onSelect={(item) => navigate(item.href ?? `/records/${item.id}`)}
+  footerAction={
+    q
+      ? {
+          label: `View all results for “${q}”`,
+          onSelect: () => navigate(`/search?q=${encodeURIComponent(q)}`),
+        }
+      : undefined
+  }
+/>;
+// data: [{ label: 'Contacts', items: [{ id: 'c1', label: 'Ada Lovelace', meta: 'Contact', href: '/contacts/c1' }] }]
+```
+
+- The first row is highlighted every time the set of ids changes (so Enter opens the top hit); rebuilding `results` inline with the same ids keeps the highlight.
+- ↑ / ↓ move the highlight and wrap, including the `footerAction` row.
+- Enter or click calls `onSelect(item, groupIndex)`, closes the panel and keeps the input text (clear it in `onSelect` if wanted). A `footerAction` row calls its own `onSelect`.
+- Esc closes the panel (innermost overlay first) and does not clear the input; blur closes it.
+- Rows with `href` render as links: Cmd/Ctrl/Shift/middle-click and "copy link" work natively; a plain click or Enter still calls `onSelect` (the library prevents the default navigation).
+- The panel is at least as wide as the pill, height-capped, and scrolls itself — do not wrap results in `<ScrollArea>`.
+- The panel shows only for a non-empty query, a loading state, or when there are results. `loading` keeps existing results visible and sets `aria-busy`.
+- Result count, loading and empty states are announced via a live region. If `emptyMessage` is a non-string node, the live region announces the default `topBar.searchEmpty` instead — pass a string to have it announced. An empty-string `emptyMessage` falls back to the default.
+- Groups with no items are not rendered, so you may pass them as-is.
+- **Debounced fetch**: set `loading` to `true` synchronously in your `onChange`, independent of the debounced request. Otherwise the panel shows and announces "No results" for the new query until the fetch actually starts.
+- Enter or click while `loading` acts on the currently shown (previous) results.
+- In uncontrolled mode the "empty query" check follows typing (`onChange`). After a form reset or an imperative `.value =` write, use a controlled `value`.
+- `open` / `defaultOpen` / `onOpenChange` control visibility if you need to; omit for uncontrolled. With `defaultOpen` or a controlled `open` and the input never focused, the panel closes only via Esc, selection, or your `open` prop — there is no outside-click listener; outside-click dismissal comes from the input's blur.
+- Hide `footerAction` (pass `undefined`) while the query is empty — "View all results for “”" is noise.
+
+#### Shapes
+
+`TopBarSearchGroup` — one labelled block in `results`. Groups with no items are not rendered.
+
+<!-- prettier-ignore -->
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | yes | Visible heading; also the group's accessible name. |
+| `items` | `TopBarSearchItem[]` | yes | Result rows in this group. |
+
+`TopBarSearchItem` — one result row.
+
+<!-- prettier-ignore -->
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Unique across ALL groups. Identifies the result set: the highlight resets to the first row when the set of ids changes. |
+| `label` | `ReactNode` | yes | Primary text. Truncates to one line. |
+| `meta` | `ReactNode` | no | Trailing muted text, e.g. the entity type or an email. |
+| `icon` | `ReactNode` | no | Leading decorative icon (e.g. `<User size={16} />`); hidden from assistive tech. |
+| `href` | `string` | no | Renders the row as a link so Cmd/Ctrl/Shift/middle-click and "copy link" work natively. A plain click or Enter still calls `onSelect` (the library never navigates). |
+
+`TopBarSearchFooterAction` — the optional `footerAction`. It renders whenever the panel is shown (results, the loading row, or the empty row for a non-empty query), as the last row in the ↑/↓ cycle.
+
+<!-- prettier-ignore -->
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | yes | Row content. |
+| `onSelect` | `() => void` | yes | Called on Enter or click. |
+| `href` | `string` | no | Optional link target, same semantics as `TopBarSearchItem.href`. |
+
+#### When NOT to use
+
+- ❌ Picking a form value from a list — use `<Select>`.
+- ❌ Filter chips / multi-select facets — use `<OptionsPicker>`.
+- ❌ A command palette in a modal — not covered by combobox mode.
+- ❌ Left-side navigation column — use `<Rail>`.
+- ❌ Page-local heading + actions — use `<PageHeader>`, not a TopBar.
+- ❌ Action toolbar attached to a specific section — use a `<Cluster>` inside that section; TopBar is for the application's top chrome.
+- ❌ Wrapping `<TopBar.Search>` in `<Popover>` to show results — use combobox mode (`results`).
+
+#### Anti-patterns
+
+- ❌ Wrapping the bar in another `position: sticky` container — the bar already sticks. Layered sticky parents stack at the wrong offset.
+- ❌ Reaching for `<TopBar.IconButton>` outside the bar — it's a topbar-scoped size + indicator pattern. Use `<Button iconOnly variant="ghost">` for general icon buttons.
+- ❌ Putting a `<Button variant="primary">` inside the bar — primary actions belong in the page body where they're discoverable; the topbar is for navigation, search, and global ambient actions only.
+- ❌ Keying or remounting `<TopBar.Search>` as results arrive — the input is never remounted by changing `results`, so don't add a `key` that does. Pass `[]` (not `undefined`) while there are no results: `undefined` turns combobox mode off (no role, no panel).
+- ❌ Duplicate `id`s across groups — ids must be unique across ALL groups (they identify the result set for highlight reset).
+- ❌ Clearing the input inside `onChange` — it fights typing; clear in `onSelect` if you want that.
+- ❌ Navigating in both `onSelect` and via the `<a>` default — the library already prevents the default on plain clicks; route only in `onSelect`.
+- ❌ Relying on the indicator dot to communicate count to assistive tech — the dot is decorative (`aria-hidden`); put the count in the `aria-label` instead.
+
+```tsx
+// Right-aligned actions only — Start can be omitted; End still sits right.
+<TopBar>
+  <TopBar.End>
+    <TopBar.IconButton aria-label="Settings"><Settings size={16} /></TopBar.IconButton>
+  </TopBar.End>
+</TopBar>
+
+// Nested secondary toolbar — as="div" avoids stacking two <header> landmarks:
+<TopBar as="div" aria-label="Filters">
+  <TopBar.Start>…</TopBar.Start>
+</TopBar>
+
+// Search hotkey hint — array form renders one chip per key; string form one chip:
+<TopBar.Search placeholder="Search contacts, deals…" hotkey={['⌘', 'K']} />
+<TopBar.Search placeholder="Filter…" hotkey="/" />
+
+// Soft-cue indicator tone:
+<TopBar.IconButton aria-label="Maintenance scheduled" indicator indicatorTone="warning">
+  <Wrench size={16} />
+</TopBar.IconButton>
+```
+
+- `<TopBar.Start>` typically holds a brand mark, workspace switcher and/or `<TopBar.Search>`; `<TopBar.End>` trailing `<TopBar.IconButton>`s and the user `<Avatar>`.
+- `<TopBar.Search>` is a 32px pill with a leading search icon; the native `type="search"` gives `role="searchbox"` and the browser's clear button. It has no keyboard-shortcut behaviour of its own.
+- `<TopBar.IconButton>` is icon-only (the 32×32 size and `indicator` dot are bar-specific); for a labelled action use a regular `<Button>`.
+- ❌ A submit button inside the search wrapper: read the value from `onKeyDown` / `onChange` on Enter.
+- ❌ `placeholder` and `aria-label` set to different strings: the default aria-label IS the placeholder; override only when the placeholder is too terse alone.
+- ❌ A search field in a form: use `<Input>`; the pill styling is specific to the bar.

package/docs/components/Tour.md

@@ -0,0 +1,85 @@
+# `<Tour>` — guided tour / onboarding walkthrough
+
+```tsx
+<Button data-tour="bulk-edit">Bulk edit</Button>
+
+<Tour
+  open={open}
+  onOpenChange={setOpen}
+  onFinish={(reason) => markSeen('bulk-edit', reason)}
+  steps={[
+    { title: 'Welcome', body: 'A quick look around.' },
+    { target: 'bulk-edit', title: 'Bulk edit', body: 'Select rows, then edit them together.' },
+  ]}
+/>
+```
+
+**Removed tokens:** `--tour-pulse-color`, `--tour-pulse-width`, `--tour-pulse-spread` and `--tour-pulse-duration` are replaced by the `--tour-wave-*` tokens. `--tour-waiting-opacity` was removed (the waiting card stays opaque).
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `steps` | `TourStep[]` | yes | The steps, in order. Must be non-empty. |
+| `open` | `boolean` | yes | Controlled open state (required — like `Modal`, there is no uncontrolled mode: an uncontrolled tour could not be started or replayed). |
+| `onOpenChange` | `(open: boolean) => void` | yes | Called with `false` on Skip, Escape and Done. |
+| `onFinish` | `((reason: TourFinishReason) => void)` | no | Fires once per Skip / Escape / Done. NOT called when the consumer closes the tour itself by setting `open={false}` — only the tour's own end gestures fire it. Use it to persist "seen" state. |
+| `step` | `number` | no | Controlled step index. Control it when a step change must do something first — navigate to another page, open an accordion, switch a tab — then the Tour waits for the next target to mount. |
+| `onStepChange` | `((index: number) => void)` | no | Fires on every step change (Next, Back, arrow keys, `advanceOn`), controlled or not. |
+| `defaultStep` | `number` | no | Uncontrolled starting step. Default `0`. Every re-open starts here again. |
+| `modal` | `boolean` | no | `true` (default): dims the page with a spotlight cutout, blocks clicks outside it and traps focus — onboarding. `false`: card only, page stays usable — feature announcements. |
+| `targetTimeout` | `number` | no | Ms to wait for a step's target before falling back to a centered card. Default `5000` (room for a route change + data fetch). `Infinity` waits forever. |
+| `onTargetMissing` | `((step: TourStep, index: number) => void)` | no | Called when a step's target didn't appear within `targetTimeout`. Log it. |
+| `doneLabel` | `string` | no | Contextual label for the last step's button, e.g. `'Got it'` for a one-step announcement. Defaults to the i18n `tour.done` (`'Done'`). An empty string counts as unset. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Targets are `data-tour` values**, not selectors or refs: put `data-tour="x"` on the element, `target: 'x'` on the step. No `target` → centered step.
+- **Pointing into a menu:** a step can target an open `DropdownMenu`/`Popover`/`Select` panel or an item inside it. Pressing Next/Back or focusing the card doesn't close the surface, and it drops just under the scrim so only the target is lit, not the whole panel (when the step targets the panel itself, the whole panel stays above the scrim). Make the preceding step `interactive` + `advanceOn: 'click'` on the trigger so the user opens it themselves. On a non-interactive step a lifted panel is lit but not clickable (`data-tour-inert` blocks pointer events; it stays visible to assistive tech, and keyboard is held by the card's focus trap). For the same reason a lifted panel on a non-interactive step doesn't scroll by wheel: it's intended (look, don't touch).
+- **Known limit:** a step pointing into a nested surface (a `DropdownMenu` submenu, a `Popover` inside a `Popover`, the `DatePicker` clock) holds only that inner surface, so pressing Next/Back can still close its parent.
+- **Cross-page tours:** mount `<Tour>` once in the app shell, control `step`, navigate inside `onStepChange`. The Tour waits for the next target (`targetTimeout`, default 5000ms, `Infinity` = forever), then falls back to a centered card and calls `onTargetMissing`.
+- **"Click it to continue":** `{ interactive: true, advanceOn: 'click' }` — target stays clickable and joins the focus trap; the tour advances after its click handler runs. The card's Next (or Done) performs that click on the target (full pointer sequence), so the step's action still happens; Next never skips it unless the step sets `next: 'skip'` (below). The card shows a "Click the highlighted element to continue" hint (`tour.clickHint`) and demotes Next to `secondary` so the target reads as the primary action; in modal mode, waves grow outward from the spotlight edge (a static ring under reduced motion). Same hint + secondary Next with `modal={false}` (no spotlight there). Add `next: 'skip'` (default `'click'`) when the target's action has side effects Next shouldn't trigger: Next/Done then advance with `goNext()` without clicking the target (ArrowRight does the same but does nothing on the last step; only Done finishes), while a real click still advances — e.g. `{ target: 'delete-btn', title: 'Delete', interactive: true, advanceOn: 'click', next: 'skip' }`.
+- Strings (`Next`, `Back`, `Skip tour`, `Done`, `Step n of m`, the click hint) come from i18n `tour.*`; only `doneLabel` is a prop.
+
+**Anti-patterns:**
+
+- ❌ `target: '#bulk-edit'` — it's the `data-tour` value, not a selector.
+- ❌ Mounting a cross-page `<Tour>` inside a routed page — it unmounts on navigation.
+- ❌ `advanceOn: 'click'` without `interactive: true` in modal mode — the target is blocked.
+- ❌ Auto-opening every visit — gate on your own seen flag.
+- ❌ An `interactive: true` modal step whose target opens a `Modal`/`Drawer` — it
+  renders beneath the tour's scrim. End the step first (`advanceOn: 'click'`,
+  point the next step into the opened Modal/Drawer) or use `modal={false}`.
+  Library floating surfaces (menus, popovers, selects) opened from an
+  interactive target elevate above the tour automatically.
+
+```tsx
+// One-step feature announcement — page stays usable:
+<Tour open={open} onOpenChange={setOpen} modal={false} doneLabel="Got it"
+  steps={[{ target: 'bulk-edit', title: 'New: bulk edit', body: 'Select rows, then edit them together.' }]} />
+
+// Cross-page: controlled step, navigate first, Tour waits for the target.
+// Symmetric on i, not a one-shot `i === 3`: Back past step 3 must navigate away too.
+<Tour open={open} onOpenChange={setOpen} step={step}
+  onStepChange={(i) => { navigate(i >= 3 ? '/contacts' : '/deals'); setStep(i); }}
+  steps={steps} />
+```
+
+- Each step spotlights its `data-tour` target and anchors a card (title, body, "Step n of m", Skip / Back / Next) to it. Steps without a target, or whose target never appears, render as a centered card. Every transition animates; all motion drops under `prefers-reduced-motion`.
+- **Keyboard:** Escape skips; ←/→ move between steps (not inside inputs).
+
+**When NOT to use**
+
+- A single contextual hint on hover/focus: `<Tooltip>`.
+- An interactive panel the user opens themselves: `<Popover>`.
+- A blocking decision: `<Modal>` / `<ConfirmationPopover>`.
+- Persistent inline guidance: `<Alert>` or `EmptyState`.
+
+**More anti-patterns**
+
+- ❌ Two elements with the same `data-tour` value on screen: the first rendered wins (dev warning). Keep ids unique per screen.
+- ❌ 10+ step tours: keep onboarding to about 5-7 steps; split longer ones per page.

package/docs/components/TreeView.md

@@ -0,0 +1,113 @@
+# `<TreeView>` — lazily loaded hierarchy, as a file list or an org chart
+
+TL;DR: a WAI-ARIA tree for hierarchies the app loads level by level (organization units, folders, categories). Two views of the same data: `list` (file-explorer rows) and `chart` (classic top-down org chart). The app owns fetching, caching and errors; TreeView owns rendering, keyboard, focus, selection and the loading / error / "N more" rows.
+
+```tsx
+import { TreeView, type TreeViewNode } from '@eocrm/design-system';
+
+const [expanded, setExpanded] = useState<Set<string>>(() => new Set());
+const children = useQueries({ queries: [...expanded].map((id) => unitsQuery({ parent: id })) });
+const byId = new Map([...expanded].map((id, i) => [id, children[i]]));
+
+<TreeView
+  aria-label="Organization structure"
+  view="list" // or "chart"
+  roots={roots.map(toNode)}
+  childrenOf={(id) => {
+    const q = byId.get(id);
+    // No data yet: failed (and not retrying) → error row, otherwise → loading row.
+    if (!q?.data) return q?.isError && !q.isFetching ? { error: true } : undefined;
+    return q.data.units.map(toNode); // loaded data stays even if a background refetch fails
+  }}
+  expandedIds={expanded}
+  onExpandedChange={(id, open) =>
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (open) next.add(id);
+      else next.delete(id);
+      return next;
+    })
+  }
+  selectedId={selectedId}
+  onSelect={openDrawer}
+  onRetry={(id) => byId.get(id)?.refetch()}
+  overflowOf={(parentId) =>
+    hiddenCount(parentId) > 0 ? { label: t('more', { count: hiddenCount(parentId) }) } : null
+  }
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `aria-label` | `string` | yes | Accessible name of the tree, e.g. "Organization structure". Required. |
+| `view` | `'list' \| 'chart'` | no | Presentation. Default `'list'`. - `'list'` — file-explorer rows indented per level with a chevron; ↑/↓ walk rows, →/← expand/collapse. - `'chart'` — classic top-down org chart of boxes with connector lines; scrolls horizontally inside itself when wider than its container. Spatial keys: ↓ expands or enters, ↑ collapses or goes to the parent, ←/→ between siblings. |
+| `roots` | `TreeViewNode[]` | yes | Top-level nodes. |
+| `childrenOf` | `(id: string) => TreeViewChildren` | yes | Children of an expanded node: the array once loaded, `undefined` while loading, `{ error: true }` on failure. Called only for expanded nodes. |
+| `expandedIds` | `ReadonlySet<string>` | yes | Ids of expanded nodes (controlled). Fetch a node's children when it appears here. |
+| `onExpandedChange` | `(id: string, expanded: boolean) => void` | yes | Called when the user expands or collapses a node. |
+| `selectedId` | `string \| null` | no | Selected node id (controlled). Ignored when `onSelect` is absent. |
+| `onSelect` | `((id: string) => void)` | no | Called on click / Enter / Space on a node. Omit for a tree without selection (no `aria-selected`). Selection never follows focus. |
+| `onRetry` | `((id: string) => void)` | no | Makes a failed level's "Couldn't load. Retry" row actionable; called with the parent id. Without it the row is inert text. |
+| `overflowOf` | `((parentId: string \| null) => TreeViewOverflow \| null)` | no | "N more not shown" row at the end of a level (`parentId` `null` = root level), or `null` for none. Pass `onLoadMore` to make it actionable. |
+| `highlightedIds` | `ReadonlySet<string>` | no | Ids to paint as a path, e.g. the selected node's ancestor ids plus its own id (TreeView cannot derive ancestors: `childrenOf` is only called for expanded nodes). Visual only — no ARIA, no effect on selection or focus. Ids not rendered are ignored. List view: accent edge on the rows; chart view: accent boxes and the connector lines between highlighted parents and children. |
+| `onHoverChange` | `((id: string \| null) => void)` | no | Pointer entered/left a node's row (list) or box (chart); `null` on leave. Pointer only — no ARIA, focus or selection effect. Pair with `highlightedIds` to paint a hover chain. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Nodes.** `TreeViewNode = { id: string; label: string; hasChildren: boolean; content?: ReactNode }`. `hasChildren` drives the chevron / toggle and `aria-expanded` even before the children load; `label` is the accessible name and the typeahead text.
+- **Lazy by contract.** `childrenOf(id)` is called only for expanded nodes: return the array once loaded, `undefined` while loading, including a query that is pending but not fetching (a "Loading…" row), `{ error: true }` on failure (a "Couldn't load. Retry" row; actionable only with `onRetry`). `childrenOf` must also return `undefined` while a retry is in flight (react-query v5 keeps `isError` true while refetching after an error: return the error only when there is no data and nothing is fetching), otherwise there is no loading row and a second failure is silent. Start the fetch when an id appears in `expandedIds`. A tree already in memory is fine too: return arrays immediately, don't fake loading.
+- **Controlled.** `expandedIds` / `onExpandedChange` and `selectedId` / `onSelect` are controlled. Omit `onSelect` for a tree without selection. Selection never follows focus: arrows move, Enter / Space / click select.
+- **Overflow.** `overflowOf(parentId)` (`null` = root level) returns `{ label, onLoadMore?, loading? }` (or `null`) and adds a muted "N more not shown" row at the end of a level. `onLoadMore` makes it actionable, `loading` marks the fetch in flight; focus then moves to the first new item (if nothing new arrives it stays on the overflow row).
+- **Rows** are named by `label`; `content` is visual only and must not contain buttons, links or inputs (a treeitem's content is not separately reachable). Put actions in the selection target (a drawer, a detail pane).
+- **Keyboard — list:** ↑/↓ move, → expands or enters, ← collapses or goes to the parent, Home/End, Enter/Space select, type to jump (the typeahead buffer resets after 500ms). **Chart:** ↓ expands or enters, ↑ collapses or goes to the parent, ←/→ move between siblings; the tree describes these keys to screen readers (merged with your own `aria-describedby`).
+- **Screen readers:** one tab stop; levels, positions and expanded state come from ARIA. A slow (≥ 300ms) user-triggered load is announced once ("Loading…"), a failure is announced; success is silent. After Retry focus stays on the status row while loading and moves to the first child when children arrive (if the retry fails again it stays on the Retry row).
+- **Empty tree.** An empty tree is not useful and not valid ARIA (a `tree` needs items): until roots load render a `Skeleton`, `EmptyState` or `ErrorState` instead of `<TreeView roots={[]}>`. A node whose loaded children are `[]` renders no group.
+- **Highlighted path.** Pass `highlightedIds` the selected unit's ancestor ids plus its own id to paint the reporting line: list rows get an accent inline-start edge; chart boxes, and the connectors between a highlighted parent and its highlighted children, turn accent. TreeView cannot derive ancestors itself (`childrenOf` is only called for expanded nodes), so build the set from your data's parent map. Ids not rendered are ignored.
+
+  ```tsx
+  <TreeView
+    view="chart"
+    selectedId={selected}
+    onSelect={setSelected}
+    highlightedIds={pathTo(selected)} // selected id + its ancestor ids, from your parent map
+    {...rest}
+  />
+  ```
+
+- **Hover.** `onHoverChange(id | null)` fires when the pointer enters or leaves a node's whole row (list) or box (chart); `null` on leave. Status rows (loading / error / overflow) don't fire; pointer only, with no effect on focus, selection or ARIA. Pair it with `highlightedIds` to paint the hovered node's chain. If the hovered node unmounts (collapsed or removed) no `null` is emitted, so clear your hover state when you collapse or remove nodes.
+
+  ```tsx
+  const [hovered, setHovered] = useState<string | null>(null);
+
+  <TreeView
+    onHoverChange={setHovered}
+    highlightedIds={pathTo(hovered)} // hovered id + its ancestor ids, from your parent map
+    onExpandedChange={(id, open) => {
+      toggle(id, open);
+      setHovered(null); // the hovered node may have just unmounted
+    }}
+    {...rest}
+  />;
+  ```
+
+- **Sizing.** `list` grows with its content — put it in a scrolling parent for long trees. `chart` fills its parent's width and scrolls horizontally inside itself when the chart is wider; it opens centred on the selected (or first) item (when the view is chosen or the first items appear), and the focused box scrolls into view.
+
+#### When NOT to use
+
+- ❌ App navigation → `Rail` (with `Rail.Group`).
+- ❌ A flat or two-level list → `Card.List`, `Table`, `Accordion`.
+- ❌ Multi-select / checkbox trees, drag-and-drop reordering — not supported.
+
+#### Anti-patterns
+
+- ❌ Buttons, links or menus inside `content`.
+- ❌ Returning `undefined` forever on a failed fetch — return `{ error: true }`.
+- ❌ Selecting on focus (opening a drawer on every arrow key).
+- ❌ Using `highlightedIds` as selection — it is visual only and sets no ARIA; keep `selectedId` for the selected node.
+- ❌ Wrapping the chart view in a fixed-width scroller — it scrolls itself.

package/docs/components/VisuallyHidden.md

@@ -0,0 +1,43 @@
+# `<VisuallyHidden>` — content for assistive tech only
+
+```tsx
+<VisuallyHidden>Opens in a new tab</VisuallyHidden>
+<VisuallyHidden as="div">…block content…</VisuallyHidden>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `as` | `'span' \| 'div'` | no | Element to render. `'span'` for inline text (the common case — a link suffix, a labelling phrase). `'div'` when the hidden content is itself block-level (e.g. wraps other block elements). Default: `'span'`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- `as?: 'span' | 'div'` — default `'span'`. Use `'div'` when the hidden content wraps other block elements.
+- The "clip" technique (`position: absolute`, 1×1px, clipped) — NOT `display: none` / `visibility: hidden`, which would also remove it from assistive tech.
+- `forwardRef` to the rendered element; spreads `HTMLAttributes<HTMLElement>` last (consumer wins — nothing here is semantic to protect).
+- The building block `LiveRegion` renders its own announcement text into.
+
+**When NOT to use:** to hide something from everyone, use the `hidden` attribute or a conditional render — VisuallyHidden stays reachable by assistive tech, it isn't a display toggle. On a focusable element (a skip link) — the content stays invisible even focused; there's no show-on-focus variant yet. To label a control, prefer `aria-label` or a visible `<label>` over a hidden span in the DOM flow. For announcements, use `LiveRegion` — a plain hidden span isn't live.
+
+```tsx
+// New-tab suffix
+<a href={href}>
+  {label}
+  <VisuallyHidden> (opens in a new tab)</VisuallyHidden>
+</a>
+
+// Hidden heading for a landmark
+<nav aria-labelledby="site-nav-heading">
+  <VisuallyHidden as="div">
+    <Title id="site-nav-heading" order={2}>Site navigation</Title>
+  </VisuallyHidden>
+  <NavLinks />
+</nav>
+```
+
+Use it for text only screen-reader users need: a link's destination context, a landmark's hidden heading. For announcements use `<LiveRegion>{message}</LiveRegion>`, which renders a VisuallyHidden with the role / aria-live wiring.

package/docs/components/WidgetPreview.md

@@ -0,0 +1,54 @@
+# `<WidgetPreview>` — decorative miniature of a widget kind
+
+A data-free, purely decorative miniature of a dashboard widget kind (KPI, list, chart, line chart, pipeline, activity). Built for the `preview` slot of `CatalogPicker` items so users can see what a widget looks like before adding it. Always `aria-hidden`; the surrounding card's title names the item.
+
+```tsx
+import { CatalogPicker, WidgetPreview } from '@eocrm/design-system';
+
+<CatalogPicker
+  label="Widget catalog"
+  items={[
+    {
+      id: 'open-deals',
+      title: 'Open deals',
+      preview: <WidgetPreview variant="kpi" />,
+    },
+    {
+      id: 'revenue',
+      title: 'Revenue',
+      preview: <WidgetPreview variant="chart" />,
+    },
+  ]}
+  onSelect={(id) => addWidget(id)}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `variant` | `'kpi' \| 'list' \| 'chart' \| 'line' \| 'pipeline' \| 'activity'` | yes | Which widget kind the miniature depicts. Required. - `'kpi'` — label, a large value block (strong accent), an accented trend line. - `'list'` — rows of accented avatar + line; first avatar strong. - `'chart'` — a bar series (accented, one bar strong). - `'line'` — a line series over a light area (strong accent line). - `'pipeline'` — stage columns of cards; current stage header strong and its cards accented; next stage header accented. - `'activity'` — timeline rows with accented dots; first dot strong. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Six variants**, pick one via `variant` (required): `kpi` (label, large value, trend line), `list` (avatar + line rows), `chart` (bar series), `line` (line series over a light area), `pipeline` (stage columns of cards), `activity` (timeline rows with dots).
+- **Always `aria-hidden="true"`.** The attribute is applied after your props, so it cannot be overridden. It conveys nothing to assistive tech; put the information in the item's `title` / `description`.
+- **Data-free.** It takes no values. It depicts a kind of widget, never a real one.
+- **Fills its container width** with a fixed 16 / 10 aspect ratio. Size it by sizing the parent (the picker card does this).
+- Colours come from theme tokens, so dark mode follows automatically. Neutral pieces use `--color-border-strong` on the preview box (`--color-bg-subtle`). Accented pieces use `--color-accent` at half strength, and one hero piece per variant uses it at full strength. To retune, override `--widget-preview-bg`, `--widget-preview-shape`, `--widget-preview-accent` and `--widget-preview-accent-strong` on an ancestor. The defaults are high-contrast, so a local override added only for visibility is no longer needed.
+
+#### When NOT to use
+
+- ❌ A loading placeholder → `<DashboardWidget loading>` (variant-matched skeleton with the correct accessible text).
+- ❌ Real data visualisation. It is a picture of a layout, not a chart.
+- ❌ Anything a screen reader user must perceive. It is hidden from them by design.
+
+#### Anti-patterns
+
+- ❌ Expecting the preview to convey information to screen readers. Name and describe the item through `title` / `description`.
+- ❌ Putting interactive content or text inside it; it is a leaf graphic.
+- ❌ Using it outside a catalog or gallery context as general decoration.

package/docs/components/useBelowBreakpoint.md

@@ -0,0 +1,11 @@
+# `useBelowBreakpoint` — viewport breakpoint hook
+
+```tsx
+import { useBelowBreakpoint } from '@eocrm/design-system';
+
+const isOverlay = useBelowBreakpoint('lg'); // true at ≤768px viewport width
+```
+
+- Lives in `src/hooks/`, imported straight from the package root. `useBelowBreakpoint(breakpoint?: 'sm' | 'md' | 'lg'): boolean` — subscribes to `(max-width: …px)` on the **viewport** (`matchMedia`: `sm` 480 / `md` 640 / `lg` 768) and returns whether it currently matches. `breakpoint` is optional — omit it (or pass `undefined`) and the hook always returns `false`.
+- Returns `false` on the server, and stays `false` until hydration corrects it — only relevant if you server-render this. In a client-only render (no SSR — the CRM's case) the value is correct from the first render.
+- Viewport, not container — use it only where a container query would be circular, i.e. where the thing being measured is what the collapse changes: `<Rail>`'s own width (internal use) and `<AppLayout>`'s overlay-sidebar trigger (`sidebarOverlayBelow` — gate your `topBar` hamburger on this so it shows only while the overlay is active). For content that re-templates inside a box of stable width, use a `collapseBelow` prop (`<Grid>` / `<Split>` / `<Sortable>` / `<DashboardCanvas>` / `<DataTable>`) instead — those use container queries in CSS and need no hook.

package/docs/components/useMonth.md

@@ -0,0 +1,18 @@
+# Calendar primitives — `useMonth`, `useWeek`, `useDay`, `useAgenda`
+
+```tsx
+const grid = useMonth(cursorDate);
+// → { year, month, monthLabel, weekdayLabels, weeks }
+
+const week = useWeek(cursorDate);
+// → { weekLabel, days, weekdayLabels }
+
+const { day, dayLabel, dayShortLabel } = useDay(date);
+
+const { days, rangeLabel } = useAgenda(rangeStart, rangeEnd);
+```
+
+- Headless. These hooks return data shapes — no rendering. The Calendar UI components (Month/Week/Day/Agenda views) consume them.
+- Each hook accepts an optional `options.locale` to override the Context value. `useMonth`, `useWeek`, and `useAgenda` accept `options.weekStartsOn` to override the locale-derived first day (used by `useAgenda` to compute the locale-aware column index for each `Day.weekday`).
+- `Day.key` is `'YYYY-MM-DD'` in local time — safe React key, comparison handle, and event-lookup index.
+- Pure date math + `Intl` formatters live alongside as utility exports: `addDays`, `startOfWeek`, `formatMonth`, `getFirstDayOfWeek`, etc. Use them if you need to derive labels or do date math outside a component.

package/docs/setup.md

@@ -0,0 +1,51 @@
+# Setup (once per consuming app)
+
+Wire the provider, styles and tokens into a consuming app once.
+
+Two steps at your app root:
+
+```tsx
+// 1. Import the stylesheet once (tokens, modern reset, base typography).
+import '@eocrm/design-system/styles/global.scss';
+
+// 2. Wrap your tree in <AppProvider>.
+import { AppProvider } from '@eocrm/design-system';
+
+<AppProvider locale="en" intlLocale="en-US">
+  <App />
+</AppProvider>;
+```
+
+`<AppProvider>` bundles the app-level contexts so you don't wire them by hand:
+
+- `locale` (`'en' | 'ru'`) — selects the built-in UI-string bundle.
+- `intlLocale?` (BCP-47, e.g. `'en-US'`) — locale for Intl formatting (Calendar, dates, numbers). Defaults to `locale`.
+- `translations?` — deep-partial overrides merged over the built-in strings (rebrand a few keys; memoize the object).
+- `toast?` — `<ToastViewport>` config, or `false` to mount it yourself. Omitted ⇒ mounted with defaults.
+- `tokens?` — CSS design-token overrides (a flat `{ '--color-accent': '#7c3aed', '--radius-md': '6px' }` map) applied in **both** themes. Rebrands the system globally — including portaled `Modal`/`Tooltip`/`Toast`. Memoize it.
+- `darkTokens?` — token overrides applied **only** in dark (forced + system), merged over `tokens` (e.g. a lighter accent on dark surfaces). Memoize it.
+
+```tsx
+// Russian UI + a couple of rebranded strings + top-right toasts:
+const translations = useMemo(() => ({ alert: { dismiss: 'Скрыть' } }), []);
+<AppProvider locale="ru" translations={translations} toast={{ position: 'top-right' }}>
+  <App />
+</AppProvider>;
+```
+
+It composes `LocaleProvider` + `I18nProvider` and mounts the toast viewport. **Routing is yours** (`<AppProvider>` ships no router), and the stylesheet import above is still required. The individual providers (`LocaleProvider`, `I18nProvider`, `ToastViewport`) remain exported for advanced cases like pinning a subtree to a different locale.
+
+**When NOT to use:** for a per-subtree locale / i18n override, nest `LocaleProvider` / `I18nProvider` directly — `AppProvider` is the single app root, so don't nest a second one. For a tiny embed or isolated test that only needs strings, use `I18nProvider` alone (or pass `toast={false}`) to avoid the toast viewport.
+
+**Rebranding via tokens:**
+
+```tsx
+const tokens = useMemo(() => ({ '--color-accent': '#7c3aed', '--radius-md': '6px' }), []);
+const darkTokens = useMemo(() => ({ '--color-accent': '#a78bfa' }), []);
+
+<AppProvider locale="en" tokens={tokens} darkTokens={darkTokens}>
+  <App />
+</AppProvider>;
+```
+
+`tokens` apply in light **and** dark; `darkTokens` refine the dark scope only. They're emitted as a single declarative `<style>` that layers over the [dark theme](theming.md#dark-theme) correctly, and they win over a `data-accent` preset's token blocks. One exception to "override the accent and everything follows": a preset may set the link colour apart from its accent (`tealpine` does), so when rebranding the accent on top of a preset, also override `--color-link-fg` / `--color-link-fg-hover`. Any design token can be overridden — see the generated `@eocrm/design-tokens` Sass contract for the full CSS custom-property set. Contributors change shared values only in `packages/design-tokens/src/tokens.json`; `src/styles/tokens.scss` remains the stable consumer entry point.