@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/CatalogPicker.md

@@ -0,0 +1,83 @@
+# `<CatalogPicker>` — searchable card picker for a catalog
+
+A search box, optional category pills, a live result count and an auto-fill grid of cards, for choosing one item from a catalog (e.g. "Add widget"). It is a surface, not an overlay: drop it into `Drawer.Body` or `Modal.Body`. Selecting is an action (`onSelect(id)`), not a value; the app decides whether to add immediately or open a configure step.
+
+```tsx
+import { Badge, CatalogPicker, Drawer, WidgetPreview } from '@eocrm/design-system';
+
+<Drawer open={open} onOpenChange={setOpen}>
+  <Drawer.Header>Add widget</Drawer.Header>
+  <Drawer.Body>
+    <CatalogPicker
+      label="Widget catalog"
+      categories={[
+        { id: 'sales', label: 'Sales' },
+        { id: 'tasks', label: 'Tasks' },
+      ]}
+      items={[
+        {
+          id: 'open-deals',
+          title: 'Open deals',
+          description: 'Count of deals in open stages.',
+          category: 'sales',
+          tags: ['pipeline', 'kpi'],
+          badge: <Badge>New</Badge>,
+          preview: <WidgetPreview variant="kpi" />,
+        },
+        {
+          id: 'my-tasks',
+          title: 'My tasks',
+          category: 'tasks',
+          preview: <WidgetPreview variant="list" />,
+          disabledReason: 'Already on dashboard',
+        },
+      ]}
+      onSelect={(id) => addOrConfigure(id)}
+    />
+  </Drawer.Body>
+</Drawer>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `items` | `CatalogPickerItem[]` | yes | The catalog. Rendered in the given order. |
+| `categories` | `CatalogPickerCategory[]` | no | Category pills (after a leading localized "All"). Omit or pass `[]` for no pills. |
+| `onSelect` | `(id: string) => void` | yes | Called with the item id when an AVAILABLE item is clicked or activated with Enter/Space. |
+| `label` | `string` | yes | Accessible name of the results listbox, e.g. "Widget catalog". Required. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **`onSelect` is an action.** It fires on click, Enter or Space of an available item. Options are `aria-selected="false"` always; nothing stays selected. Close the overlay or open the next step in the handler.
+- **Search** matches a case-insensitive substring of `title`, `description` or any of `tags` (tags are not rendered). Combined with the category pill (AND). Items keep your order.
+- **Categories.** Omit or pass `[]` for no pills; otherwise a localised "All" pill is added first and is the default. Items without a `category` only appear under "All".
+- **Result count** is a `role="status"` element ("N results") that updates as the filter changes. When nothing matches, an `EmptyState` replaces the grid.
+- **Unavailable items** (`disabledReason`): stay visible and focusable, dimmed, `aria-disabled`, reason shown as text and added to the option's description. `onSelect` is not called. Never hide them.
+- **Keyboard** (one tab stop; roving focus inside the grid):
+  - `ArrowDown` in the search field focuses the first result.
+  - `←` / `→` move by one item (flipped in RTL); `↑` / `↓` move by one row (column count read from the rendered grid); `Home` / `End` jump to first / last.
+  - `↑` from the first row returns focus to the search field.
+  - `Enter` / `Space` activate (no-op on an unavailable item).
+  - Changing the query or category resets the focus target to the first result.
+- **The toolbar is sticky** so search stays reachable while the drawer/modal body scrolls.
+- **Options must not contain interactive content.** Each card is a single `role="option"`; `preview` and `badge` are display-only.
+- Fills its container width; the grid fills the row with as many columns as fit (about 2 in a Drawer, 3 to 4 in a Modal).
+
+#### When NOT to use
+
+- ❌ A persistent form value (a field that stores a choice) → `<Select>` / `<IconPicker>`.
+- ❌ Filtering a list or table → `<OptionsPicker>` / `<FilterChip>`.
+- ❌ Picking emoji → `<EmojiPicker>`.
+- ❌ Multi-select. It selects one item per activation.
+
+#### Anti-patterns
+
+- ❌ Hiding unavailable items instead of passing `disabledReason`. Users then cannot tell why a widget is missing.
+- ❌ Putting buttons or links inside `preview` / `badge`. Options must not contain interactive content; nested controls are unreachable and invalid ARIA.
+- ❌ Building overlay behaviour into the picker — put it in `Drawer.Body` / `Modal.Body`.
+- ❌ Passing `label` as a placeholder-style hint. It is the listbox's accessible name ("Widget catalog").

package/docs/components/Chart.md

@@ -0,0 +1,114 @@
+# `<Chart>` — time-series chart for a dashboard widget
+
+Line, bar, stacked bar or area chart over app-bucketed categories. Fills a `DashboardWidget variant="chart"` body, reflows to any cell size, and ships its own legend, tooltip, keyboard inspection, data table and empty state. The app owns data, formatting, loading and errors.
+
+```tsx
+import { Chart, DashboardWidget, ErrorState } from '@eocrm/design-system';
+
+<DashboardWidget variant="chart" title="Deals won" loading={isLoading}>
+  {error ? (
+    <ErrorState title="Could not load" headingLevel={4} />
+  ) : (
+    <Chart
+      type="line"
+      label="Deals won per week"
+      categories={['W1', 'W2', 'W3', 'W4']}
+      series={[
+        { key: 'won', label: 'Deals won', values: [3, 5, null, 8] },
+        { key: 'won-prev', label: 'Previous period', values: [2, 4, 6, 5], comparisonOf: 'won' },
+      ]}
+      formatValue={(n) => numberFormat.format(n)}
+    />
+  )}
+</DashboardWidget>;
+
+// Stacked, with the previous period as a total line
+<Chart
+  type="stacked-bar"
+  label="Deals won by owner"
+  categories={weeks}
+  series={[
+    ...owners.map((o) => ({ key: o.id, label: o.name, values: o.values })),
+    { key: 'prev', label: 'Previous period', values: prevTotals, comparisonOf: 'total' },
+  ]}
+  formatValue={formatCurrency}
+/>;
+
+// Markers: an event line, a campaign band, weekends as subtle decorative bands
+<Chart
+  type="line"
+  label="Calls per day"
+  categories={days}
+  series={calls}
+  formatValue={formatCount}
+  markers={[
+    { key: 'launch', label: 'Launch', at: '10 Jul' },
+    { key: 'promo', label: 'Summer promo', from: '21 Jul', to: '30 Jul' },
+    ...weekends.map(([sat, sun]) => ({ key: sat, from: sat, to: sun, tone: 'subtle' as const })),
+  ]}
+/>;
+
+// Footnote: a short note under the plot; the plot fills the rest of the cell
+<DashboardWidget variant="chart" title="Revenue">
+  <Chart
+    type="line"
+    label="Revenue per month"
+    categories={months}
+    series={revenue}
+    formatValue={formatCurrency}
+    footnote={`${excluded} deals in other currencies not included`}
+  />
+</DashboardWidget>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `type` | `'line' \| 'bar' \| 'stacked-bar' \| 'area'` | yes | Chart form. Required. - `'line'` — one smoothed line per series; trends over time. Comparison series dashed. - `'bar'` — grouped bars per category; compare a few series per bucket. Comparison bars outlined + light fill. - `'stacked-bar'` — bars stacked per category; parts of a total. Comparison only as `comparisonOf: 'total'` (dashed total line). - `'area'` — smoothed stacked areas; parts of a total over time. Same comparison rule as `stacked-bar`. |
+| `label` | `string` | yes | Accessible name of the figure and caption of its data table, e.g. "Deals won per week". Required. |
+| `categories` | `string[]` | yes | X-axis buckets, already formatted by the app ("12 Jan", "W3", "Mar"). `series[].values[i]` belongs to `categories[i]`. |
+| `series` | `ChartSeries[]` | yes | Series to plot, in a stable order: colour follows position (non-comparison series 1–8 get palette slots 1–8), so keep the order fixed when filtering. At most 8 primary series — fold the rest into an "Other" series in the app (series 9+ still render, dashed/outlined, with a dev warning). `values` shorter than `categories` are padded with gaps; `null` is a gap (lines break, bars are absent). `comparisonOf` marks a de-emphasised comparison (e.g. previous period): a series key (line / bar) or `'total'` (stacked-bar / area). |
+| `formatValue` | `(n: number) => string` | yes | Formats a number for axis ticks, tooltip and data table (the app owns i18n and currency). Required. |
+| `emptyMessage` | `ReactNode` | no | EmptyState title when there are no categories or every value is null/zero. Default: translated "No data for this period". |
+| `hiddenSeries` | `string[]` | no | Controlled list of hidden series keys (legend toggles). Omit for uncontrolled. Unknown keys are ignored. If it would hide every primary series, it is ignored for primaries (the last primary can't be hidden). |
+| `onHiddenSeriesChange` | `((keys: string[]) => void)` | no | Called with the next hidden keys when the user toggles a legend item. |
+| `markers` | `ChartMarker[]` | no | Static annotations pinned to `categories`: `{ key, label?, at }` draws a vertical line at one category, `{ key, label?, from, to }` shades a category range (inclusive), e.g. a campaign or weekends. `tone`: `'neutral'` for events (the tone default) or `'subtle'` for recurring context. Labelled markers are also listed in the tooltip, the keyboard announcement and the data table; unlabelled ones are decorative. A marker naming an unknown category is ignored with a dev warning. |
+| `footnote` | `ReactNode` | no | Short note under the plot, e.g. "3 deals in other currencies not included" or why a comparison was omitted. Takes its own row (wraps, never truncates) and the plot fills the rest; also describes the plot for screen readers. Shown in the empty state too, where it often explains the emptiness. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- **Pre-bucketed data.** `categories` are x labels the app already formatted; `series[].values[i]` belongs to `categories[i]`. Shorter `values` are padded with gaps, extras ignored. `null` and non-finite values (NaN, Infinity) are gaps: lines and areas break, bars are absent.
+- **Types.** `line` (trend), `bar` (grouped per bucket), `stacked-bar` (parts of a total), `area` (always stacked; overlapping areas hide each other).
+- **Smoothing.** Every line (comparisons and the `stacked-bar` total included) and `area` is drawn with a monotone curve: it passes through every value and never leaves the range of the two values it joins, so there is no dip before a step, no bump after it, no peak above a real maximum and no negative between counts. Peaks, troughs and flat runs ease in flat. Two-point runs are straight. Stacked areas are the exception: each layer stays within its own values, but where layers trade places the stacked top can rise slightly above the largest real total; the y axis grows to keep it inside the plot. Stacked areas smooth each series on its own and stack the curves, so a steady layer stays steady whatever its neighbours do, a series that is 0 has no thickness, and with non-negative data no layer turns inside out or crosses its neighbour. A `'total'` comparison equal to the stack stays close to its top but is smoothed on its own, so next to a spike or a series' zero it can drift up to about a tenth of the plot height (typically 2–4%). Markers and the tooltip sit on the real points; the data table has the exact values. Not configurable.
+- **Y axis** always includes 0, with rounded ticks formatted by `formatValue`. In `bar` and `line`, negative values grow down from 0; `stacked-bar` diverges around 0 (positives up, negatives down); `area` stacks without a diverging offset, so negatives accumulate.
+- **Colour** follows a series' position among non-comparison series: 1–8 get the 8 validated palette colours (light + dark). Keep the order stable so filtering never repaints survivors.
+- **Comparison series** (`comparisonOf`): in `line` / `bar`, name the parent's key — it inherits the parent's colour, dashed (line) or outlined with a light fill (bar), sits after its parent in legend and tooltip, and hides with it. In `stacked-bar` / `area`, use `comparisonOf: 'total'` — a dashed neutral line of the previous period's total. Mismatches are ignored with a dev warning.
+- **Markers** (`markers`) are static annotations pinned to `categories`: `{ key, label?, at }` draws a dashed vertical line at the centre of one category; `{ key, label?, from, to }` shades whole buckets from `from` to `to` (inclusive, either order). Positions snap to buckets: there is no sub-bucket time. `tone: 'neutral'` (default) for events, `'subtle'` for recurring context such as weekends (one marker per weekend). Bands sit behind the grid and data, lines behind the data. Labels are drawn at the top of the plot when they fit (earlier markers win a collision; hidden when the chart is compact) and are always listed in the tooltip, the keyboard announcement and a "Markers" column of the data table. Unlabelled markers are decorative. A marker naming an unknown category is ignored with a dev warning. Building markers with `.map` inside an array literal widens `tone` to `string`: write `'subtle' as const`. Don't encode status with markers (no red "incident" tone): put the meaning in the label.
+- **Footnote** (`footnote`) is a short muted note in its own row under the plot, e.g. excluded currencies or why a comparison was dropped. It wraps (never truncates) and the plot shrinks to make room, so keep it to a line or two. It is also the plot's accessible description (after the key hint), and stays visible in the empty state, where it often explains why there is no data. Don't use it for errors (use `ErrorState`) or for legends.
+- **Legend** appears with more than one series. Hover or focus an item to highlight its series; click to hide/show it (`aria-pressed`). The last visible primary series can't be hidden: its button is `aria-disabled` but stays focusable. A comparison's button is disabled while its parent is hidden. Control with `hiddenSeries` / `onHiddenSeriesChange` to persist per widget. Below 120px height the legend shrinks to one row with a "+N" counter; overflow items are not rendered, so they are not keyboard-reachable (the data table still lists every series) — except hidden series, which always render so they can be re-shown (the "+N" counts only the remaining visible ones).
+- **Tooltip** on hover or tap shows every visible series at that bucket. On touch, tapping the plot shows it and it stays until you tap outside the plot. **Keyboard:** the plot is one tab stop (named by `label`, with the key hint as its description); ←/→ move, Home/End jump, Esc closes. Screen-reader users in browse mode never receive the arrow keys on the plot — they should read the data table instead. Values are announced politely only while a keyboard user inspects — never on load, so a dashboard of charts stays quiet.
+- **Screen readers** (browse mode: use the table, not the plot's arrow keys) get a visually hidden data table (caption = `label`) with exactly the plotted values (a null cell reads "No data"); the SVG is hidden from them. Identity never relies on colour alone: dashes for comparisons, marker shapes per series, labels everywhere.
+- **Empty** (no categories, or every value null/0) renders `EmptyState` with `emptyMessage` (default "No data for this period"; an empty string falls back to the default).
+- **Sizing.** Fills its parent (`width/height: 100%`) and redraws on resize. The parent must have a definite height (e.g. a `DashboardWidget` chart body); in an auto-height parent the plot measures 0 and only the legend renders. X labels never overlap: end labels are clamped inside the chart and the last label is dropped if it would collide. It never scrolls horizontally.
+- **Performance.** Layout is recomputed when the `formatValue`, `categories` or `series` identities change. Memoise them (`useCallback` / `useMemo`) when the parent re-renders often.
+
+#### When NOT to use
+
+- ❌ One headline number → `DashboardWidget variant="kpi"` or `StatGroup`.
+- ❌ More than 8 groups at once → fold the tail into an "Other" series in the app (the DS can't know whether your metric is additive).
+- ❌ Two measures with different units → two charts. There is no dual axis.
+- ❌ Non-time categorical comparisons that need sorting, pies, scatter or zoom — not supported.
+
+#### Anti-patterns
+
+- ❌ Wrapping `Chart` in a fixed-height or scrolling div inside the widget body. The cell is the size.
+- ❌ Rendering a note next to `Chart` in the widget body (it steals the plot's height unpredictably). Use `footnote`.
+- ❌ Passing `loading` / error UI into `Chart`. Use `DashboardWidget loading` and an `ErrorState` child.
+- ❌ Reordering `series` by value each refresh — colours jump between entities.
+- ❌ Formatting inside `categories` with the value (`"W1: 3"`); values go in `series`, labels in `categories`.
+- ❌ Comparison series on 8 groups (16 marks): compare only ungrouped or with ≤ 4 groups.

package/docs/components/ChatBubble.md

@@ -0,0 +1,55 @@
+# `<ChatBubble>` — one chat message, plus `ChatBubble.List` (the `role="log"` container)
+
+A message bubble aligned by speaker: `from="member"` (the signed-in user, end side, accent tint) or `from="assistant"` (start side, neutral). Always put bubbles inside `<ChatBubble.List aria-label="…">`: it is a `role="log"` + `aria-live="polite"` region, so a screen reader announces each new message, with the speaker, as it arrives.
+
+```tsx
+import { Button, ChatBubble } from '@eocrm/design-system';
+
+<ChatBubble.List aria-label="Conversation with Scout">
+  <ChatBubble from="member">Which deals are at risk?</ChatBubble>
+  <ChatBubble from="assistant" footer={<Button size="xs">Helpful</Button>}>
+    Three deals have had no activity for 14 days.
+  </ChatBubble>
+  {waiting && <ChatBubble from="assistant" pending />}
+</ChatBubble.List>;
+```
+
+<!-- props:start -->
+
+## Props
+
+### `ChatBubbleProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `from` | `'member' \| 'assistant'` | yes | Speaker. `member` = the user (accent tint, end side); `assistant` = the AI (neutral, start side). |
+| `children` | `ReactNode` | no | Message content. Ignored while `pending`. |
+| `footer` | `ReactNode` | no | Slot below the coloured body, same side (feedback buttons, sources). |
+| `pending` | `boolean` | no | Show a "typing" indicator instead of `children`; announced once when inserted into a `ChatBubble.List`. Intended for `from="assistant"`. Default: `false`. |
+| …native | | | plus native `<div>` attributes |
+
+### `ChatBubbleListProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | The `ChatBubble`s of the conversation, oldest first. Pass an `aria-label` naming the conversation. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **The speaker is spoken.** Every bubble starts with a visually hidden, localised "You said: " / "Assistant said: " (`chatBubble.*` i18n keys, no label props).
+- **`pending`** shows animated dots (static under `prefers-reduced-motion`) and a hidden "Assistant is typing…"; `children` are ignored. Inserted into the `role="log"` list it is announced once, and the real reply is announced when it replaces it. `aria-busy` is not used. It carries no "said" prefix; the typing text names the speaker.
+- **`footer`** renders below the coloured body, same side, outside the tint.
+- `ChatBubble.List` spreads props first: `role` and `aria-live` always win. Gap between bubbles is `--chat-bubble-list-gap`.
+- Bubble width is capped at `--chat-bubble-max-width` (80%). The root is a full-width row; alignment is `justify-content`, so the parent never needs to align it.
+
+**When NOT to use:** threaded/commented records (use `Thread`), toasts or banners (use `toast` / `Banner`), a bubble outside a `ChatBubble.List` for a live conversation (nothing will be announced), rich per-message layout (the body is plain content; compose it inside `children`).
+
+**Anti-patterns**
+
+- A `ChatBubble.List` without `aria-label`.
+- Overriding `role` on `ChatBubble.List`: ignored — it is always `role="log"`. Don't wrap the bubbles in your own `role="list"`/`listitem` markup either: a list inside the log adds noise ("list, 3 items") to every announcement.
+- Setting `aria-busy` or building your own typing indicator: use `pending`.
+- Re-adding a "You:" / "Assistant:" prefix in `children`: it would be read twice.

package/docs/components/ChatLauncher.md

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

package/docs/components/Checkbox.md

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

package/docs/components/CircularProgress.md

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

package/docs/components/Cluster.md

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

package/docs/components/Code.md

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