@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/Calendar.md

@@ -0,0 +1,158 @@
+# `<Calendar>` — month / week / day / agenda views
+
+```tsx
+// Uncontrolled
+<Calendar events={events} defaultView="week" />;
+
+// Controlled cursor + view
+const [cursor, setCursor] = useState(new Date());
+const [view, setView] = useState<CalendarView>('month');
+<Calendar
+  value={cursor}
+  onChange={setCursor}
+  view={view}
+  onViewChange={setView}
+  events={events}
+  onEventClick={(e) => openDetail(e)}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `events` | `readonly CalendarEvent[]` | no | Events to display. |
+| `view` | `'month' \| 'week' \| 'day' \| 'agenda'` | no | Active view (controlled). Pair with `onViewChange`. |
+| `defaultView` | `'month' \| 'week' \| 'day' \| 'agenda'` | no | Initial view (uncontrolled). Defaults to `'month'`. |
+| `onViewChange` | `((view: CalendarView) => void)` | no | Fires when the user clicks the view switcher. |
+| `value` | `Date` | no | Navigation cursor (controlled). |
+| `defaultValue` | `Date` | no | Initial cursor (uncontrolled). Defaults to `new Date()`. |
+| `onChange` | `((date: Date) => void)` | no | Fires on prev/next/today/keyboard navigation. |
+| `onDayClick` | `((date: Date) => void)` | no | Fires when the user clicks a day cell's empty space. - Month view: empty space in a day cell, the "+N more" overflow chip, or keyboard activation (Enter/Space) on a focused cell. - Week/Day view: empty hour-grid space inside that day's column — **mouse click only**. There is no keyboard equivalent in v3; consumers needing keyboard activation in week/day should surface their detail UI through the focusable event chips (which fire `onEventClick`). |
+| `onEventClick` | `((event: CalendarEvent) => void)` | no | Fires when the user clicks an event chip. |
+| `locale` | `string` | no | Override locale. Defaults to `useLocale()`. |
+| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | Override locale-derived first day of week. |
+| `maxLanesPerWeek` | `number` | no | Lane cap per week (month view). Default 3. Events beyond it collapse into a "+N more" chip; clicking it fires `onDayClick(date)`. |
+| `hourRange` | `[number, number]` | no | Hour range shown in week/day views (inclusive start, exclusive end). Defaults to `[7, 19]` (7am–7pm). Hours outside this range are NOT rendered (no row in the grid). |
+| `hourRowHeight` | `number` | no | Pixel height per hour row in week/day views. Default 48. |
+| `resources` | `readonly CalendarResource[]` | no | Split `view="day"` into one column per bookable subject — practitioner, chair, room, bay — all sharing a single time axis and a single scroll container. This is the "resource day view" of scheduling products. Events are routed by `CalendarEvent.resourceId`. A timed event whose `resourceId` matches nothing (or is absent) lands in a trailing "unassigned" column, which is only rendered when such an event exists. All-day events without a `resourceId` are day-wide and span every column. Ignored by month, week and agenda views — those have their own column meaning. Don't approximate it with N side-by-side `<Calendar view="day">` in a `Split`: each brings its own header, gutter and scroll, so they drift. |
+| `backgroundIntervals` | `readonly CalendarBackgroundInterval[]` | no | Availability underlay for week/day views: non-interactive bands painted behind the events, distinguishing "closed" from "open and free". "Open and busy" already reads from the event blocks themselves. An interval list rather than a weekly-hours object, because working hours vary by day (a lunch break), by date (a holiday, a short day) and by column (per-practitioner shifts). Bands take no part in the event collision cascade and never intercept clicks — `onDayClick` still fires through them. Every interval is clipped to each column's own date, so a week view needs one interval per day rather than one that all seven columns share. |
+| `onEventMove` | `((event: CalendarEvent, next: CalendarEventMove) => CalendarDropResult)` | no | Enables drag-to-reschedule in week/day views. Called on drop with the proposed placement; the event's duration is preserved. **Nothing moves until you commit it.** `events` stays the source of truth — apply the change to your own state to make it stick. To refuse a drop (the server rejects overlaps, out-of-hours bookings, …) return `false`, or a promise that resolves `false` or rejects: the block snaps back and the preview is discarded. Prefer `canDropEvent` for rules you can evaluate synchronously — it refuses the drop *during* the drag, so the user sees it before releasing. Omit to keep today's read-only behaviour. |
+| `onEventResize` | `((event: CalendarEvent, next: CalendarEventResize) => CalendarDropResult)` | no | Enables drag-to-resize in week/day views (a handle on the block's bottom edge). `startsAt` is unchanged; only `endsAt` moves. Same commit and rejection semantics as `onEventMove`. |
+| `canDropEvent` | `((event: CalendarEvent, next: CalendarDropCandidate) => boolean)` | no | Synchronous veto, evaluated continuously while dragging. Return `false` and the placement renders as a refused drop and is never proposed to `onEventMove` / `onEventResize`. Use for rules you can check locally (opening hours, overlaps within the loaded event set); use the handler's own return value for rules only the server can settle. `next.mode` says which gesture is being judged, and narrows the payload: `'move'` carries the target `resourceId`, `'resize'` cannot change the column so it doesn't. Rules like "shortening is always fine, relocating needs approval" are otherwise inexpressible — the predicate fires while the pointer is still at the origin, where both gestures report the event's own start. Note that `backgroundIntervals` does NOT gate drops. Shading a slot closed is presentation; enforcing it is this predicate's job. Derive both from one source so they cannot drift. |
+| `dragSnapMinutes` | `number` | no | Snap granularity for drags, in minutes. Default 15 — a drag lands on a quarter-hour boundary rather than an arbitrary pixel offset. Also the step size for the keyboard equivalent (Alt + arrow keys). Values below 1 (including 0 and negatives) are treated as 1 minute. |
+| `renderEvent` | `RenderEvent` | no | Optional custom renderer for the inner content of every event chip across views (month chips, week/day timed blocks, all-day band chips). The returned ReactNode replaces the default `<time> · <title>` markup inside the chip's button wrapper — the wrapper still handles tone background, click, tooltip, and (for timed blocks) absolute positioning. To override colors, return content with inline styling that fills the wrapper (e.g., `position: absolute; inset: 0; background: <color>`). The `ctx` argument carries view-aware metadata: `view`, `asAllDay`, `continuesLeft`/`continuesRight` (multi-day), `timeLabel`, `duration`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Four views: `'month'` (continuous event bars across the grid), `'week'` (7 columns × hour rows + all-day band), `'day'` (single column × hour rows), `'agenda'` (chronological list of the cursor's current week, grouped by day with empty days hidden).
+- Events are `{ id, title, startsAt, endsAt?, tone?, color?, allDay?, resourceId? }`. Multi-day events render as continuous bars in both the month grid and the week/day all-day band. `resourceId` routes a timed event to its column in the resource day view and is ignored by every other view.
+- **Two colour axes, and they do not compete.** `tone` is _semantic_ — what STATE the event is in: `neutral` (default) / `accent` / `success` / `warning` / `danger`. `color` is _identity_ — WHICH category it belongs to, as one of the 30 `PaletteColor`s. Use `color` when your events belong to a colour-bearing category the tenant chose (an appointment type, a calendar, a resource class).
+- With **no** `color`, tone paints the whole block exactly as it always has, and `allDay: true` renders as a tone-filled band (no time prefix). With `color` set, `color` takes the fill (palette tint background, saturated palette colour for text and border) and a non-`neutral` `tone` moves to a saturated stripe down the event's **leading edge** — so a category-coloured event can still show a state that must not be missed. There is no precedence rule to remember because the axes occupy different pixels.
+
+  ```tsx
+  // Category only — a clean single colour.
+  { id: '1', title: 'Consultation', startsAt, color: 'violet' }
+  // Category AND state — violet block, danger stripe. Both readable.
+  { id: '2', title: 'Consultation', startsAt, color: 'violet', tone: 'danger' }
+  ```
+
+  Don't map categories onto tones instead: tones are semantic and finite, two categories would collide on one tone, and the result is wrong in both directions — a `danger` chip that is merely a category, and a genuinely urgent event that looks like one.
+
+- **This is the opposite of `Badge`**, where `color` takes precedence over `tone` and the tone is discarded. Calendar renders both, because a calendar tone can carry states closer to safety than decoration (a masked hour, a released slot) and dropping one would make a free hour read as a booked one. Don't carry the Badge rule across.
+- **Both axes are visual only** — neither sets ARIA, and a 3px band is not an accessible signal (same contract as `Badge`). If a state must reach assistive tech, keep it in the event `title`. And pick category colours that contrast with the tones you use — measured RGB distance between the band colour and the category's own saturated colour — grouped by tone and ordered within each group: `success` + `mint` (11) / `emerald` (15) / `teal` (35) / `green` (41); `danger` + `red` (17) / `coral` (44); `warning` + `orange` (16) / `coral` (25) / `red` (43) / `amber` (44); `accent` + `blue` (40). Read it as a threshold, not a ranking. The worst pair is `success` + `mint` at 11, and anything under ~20 is effectively invisible at the rendered 4px (a 3px band plus the 1px border in the same colour; the agenda row has no border, so 3px there); the low 20s are detectable side-by-side but unreliable alone, and the low 40s are where this list stops rather than where the problem does. These moved (`success` + `mint` 18 → 11, `danger` + `red` 36 → 17) when those tones were raised to clear WCAG AA; `Calendar.collisions.test.ts` recomputes the list from the shipped tokens. Nothing enforces this — keep the state in the title too when a tenant's category colour collides.
+
+- In the **agenda** view the row is never filled (a tint would clash with the today-group accent and the hover background), so `color` sets the leading dot and `tone` still gets the edge stripe.
+- A coloured **all-day** chip uses the same palette tint as a timed one rather than the tone-filled treatment: the palette ships a `bg`/`fg` pair, and a filled variant would mean inventing 30 more tokens and asserting contrast at 12px for each. **The visible consequence:** a coloured all-day event renders at _timed-chip weight_ — same tint, same border, only the time prefix missing — so in a band that mixes coloured and uncoloured all-day events, the coloured ones read lighter. Colour the whole category or none of it if that bothers you.
+- On a multi-day bar the band repeats on **every** segment, including ones that continue from a previous week. It marks the event's state, not its start.
+- Controlled cursor via `value` / `onChange`, or uncontrolled via `defaultValue`. Controlled view via `view` / `onViewChange`, or uncontrolled via `defaultView`.
+- Overlapping timed events in week/day views render as a Google-Calendar-style cascade: each lane is offset to the right by a small constant step but every block extends to the column's right edge, with later lanes overlaying earlier ones via `z-index`. Hovering or keyboard-focusing a block lifts it to full width on top of all neighbours. A horizontal "now" line marks the current time in today's column.
+- Locale-aware via `useLocale()`; override with `locale` prop. UI strings (`today`, `viewMonth`, etc.) come from the i18n provider (`useTranslation`) — override them with `<I18nProvider overrides={{ calendar: { today: '…' } }}>`. There is no `labels` prop. For Russian copy and dates: `<I18nProvider locale="ru"><Calendar locale="ru-RU" … /></I18nProvider>`.
+- Read-mostly **by default**: `onDayClick` and `onEventClick` callbacks; opt into editing by wiring `onEventMove` / `onEventResize` (see _Drag to move and resize_ below). `onDayClick` fires across all views — month-cell click, "+N more" chip, keyboard activation (Enter/Space) on a focused cell, and (in week/day views) clicks on the empty hour-grid space of a day column. No built-in popover or modal — wire your own detail UI.
+- ARIA: month view is `role="grid" aria-readonly="true"`; arrow keys move focus, PageUp/PageDown navigates months, Enter/Space calls `onDayClick`. Week/day views are also `role="grid"` with `role="row"` + `role="columnheader"` headers and standard sequential tab order for event blocks — `aria-readonly="true"` there too, until a drag handler is wired (see below). Agenda view exposes the visible week as `role="list"` with each day group as a `role="listitem"` and the day label as an `<h3>` heading inside — screen readers announce the date grouping before reading each event row. **Known v3 gap:** in week/day views, `onDayClick` on empty hour-grid space is **mouse-only** (no keyboard equivalent). Consumers needing keyboard activation should drive their detail UI through the focusable event chips via `onEventClick`.
+
+#### Resource columns — one day, N lanes
+
+```tsx
+<Calendar
+  view="day"
+  events={appointments} // each carries resourceId
+  resources={[
+    { id: 'ana', label: 'Ana' },
+    { id: 'ben', label: 'Ben' },
+  ]}
+/>
+```
+
+- Routing is by `CalendarEvent.resourceId`. A **timed** event whose `resourceId` matches nothing (or is absent) lands in a trailing **Unassigned** column, which is only rendered when at least one such event exists. An **all-day** event with no `resourceId` is day-wide and spans every column; with one, it pins to that column.
+- Two bookings at the same hour in _different_ columns are not a collision — each takes lane 0 and full column width. The cascade still applies within one column.
+- Month, week and agenda views ignore `resources` — their columns already mean something else.
+
+#### Availability underlay — shade closed time, tint free time
+
+```tsx
+<Calendar
+  view="day"
+  events={appointments}
+  resources={resources}
+  backgroundIntervals={[
+    { startsAt: at(7, 0), endsAt: at(9, 0), resourceId: 'ana', tone: 'unavailable' },
+    { startsAt: at(9, 0), endsAt: at(17, 0), resourceId: 'ana', tone: 'available' },
+  ]}
+/>
+```
+
+- A booking calendar has three states and `hourRange` alone expresses none of them: **closed** (rendered but greyed), **busy** (an event covers it — already works), **free** (clickable). `backgroundIntervals` paints the first and third behind the events.
+- An interval list, not a weekly-hours object, because working hours vary by day (a lunch break), by date (a holiday, a short day) and by column (per-practitioner shifts).
+- `tone`: `'unavailable'` (default) shades; `'available'` tints. `resourceId` restricts the band to one resource column and is ignored in week view (and in a resource-less day view).
+- **Intervals are always clipped to each column's own date**, `resourceId` or not. Shading 08:00–09:00 across a week takes seven intervals, one per day — a single interval does not span the columns.
+- Bands render beneath events, take no part in the collision cascade, are `aria-hidden`, and are `pointer-events: none` — `onDayClick` still fires through them. Intervals are clipped to each column's day and to `hourRange`; ones that fall entirely outside are dropped.
+- Don't fake this with all-day events — that pollutes the `events` array you also read back.
+- **The underlay is paint, not policy.** Bands never gate drops — `backgroundIntervals` and `canDropEvent` are independent, and shading a slot closed does not stop a drag landing in it. A screen that shades shifts _and_ enables drag must express the same rule twice: once as intervals to draw it, once in `canDropEvent` to enforce it. Derive both from one source so they cannot drift.
+
+#### Drag to move and resize
+
+```tsx
+<Calendar
+  view="day"
+  events={appointments}
+  resources={resources}
+  dragSnapMinutes={15}
+  canDropEvent={(ev, next) => isWithinOpeningHours(next)}
+  onEventMove={async (ev, next) => {
+    const ok = await api.reschedule(ev.id, next);
+    if (!ok) return false; // rejected → the block snaps back
+    setAppointments((prev) => applyMove(prev, ev.id, next));
+  }}
+  onEventResize={(ev, next) => setAppointments((p) => applyResize(p, ev.id, next))}
+/>
+```
+
+- Both handlers are optional and additive — omit them and the calendar behaves exactly as before (read-only). `onEventMove` makes blocks draggable; `onEventResize` adds a handle on the block's bottom edge.
+- **A drop is proposed, never applied.** `events` stays the source of truth: commit the change to your own state or the block snaps back. `next` is `{ startsAt, endsAt, resourceId? }` for a move (duration preserved; `resourceId` is the column it landed on) and `{ startsAt, endsAt }` for a resize (`startsAt` unchanged).
+- **Two ways to refuse a drop.** `canDropEvent` is a synchronous predicate evaluated _continuously during_ the drag — the placement renders as refused for as long as the pointer rests on it, and never reaches the handler. Its `next.mode` says which gesture is being judged and narrows the payload (`'move'` carries the target `resourceId`; `'resize'` can't change the column, so it doesn't), which is what makes rules like "shortening is fine, relocating needs approval" expressible. The handler itself can return `false`, or a promise resolving `false` or rejecting, for rules only the server can settle; that verdict is announced in the live region rather than styled (the gesture is over by then), and the preview is held until the promise settles so an accepted drop doesn't flash back mid-request.
+- Dragging sideways crosses columns: another weekday in week view, another resource lane in the resource day view.
+- **Keyboard equivalent**, so rescheduling isn't mouse-only: on a focused block, `Alt`+`↑`/`↓` moves by one snap step, `Alt`+`←`/`→` moves a column, `Alt`+`Shift`+`↑`/`↓` changes the end time. Every block carries the full shortcut list as its `aria-describedby` description — it has to live on the blocks, since `role="grid"` here is not focusable and a description there would never be announced — and an assertive live region names the event and reports each proposed slot, each refusal, and each gesture that was already at the edge of what the bounds allow. With a drag handler wired, the grid drops `aria-readonly`.
+- **Bounds.** One rule governs both gestures: **the allowed range always contains where the event already is**, so a bound can refuse to move something further but never moves it the opposite way. Within that, a move keeps the start inside the visible `hourRange` — an unclamped upward drag would project into the previous calendar day — while the end runs past it freely, so an overnight booking keeps its duration; and a resize may grow or shrink the event by at most a day per gesture — the bound is on the CHANGE, not the absolute duration, so a multi-day booking stays adjustable — which lets an event be extended past midnight while stopping a runaway pointer delta rolling through whole dates. An event that already starts before `hourRange` (its block renders clipped at the top) is _not_ pulled into the window.
+- A gesture the bounds refuse outright proposes nothing: the handler is not called (it is typically an API write) and the live region says the event cannot move further.
+- Every time comes from the `CalendarEvent`, never from the rendered block — the layout clips a block that ends on a later day, so it is shorter than the event it represents.
+- **A move preserves ELAPSED duration**, not the row count. The two differ only on a daylight-saving day, where the grid necessarily draws wall-clock rows (01:00–05:00 occupies four rows though three hours pass) while a booking is its real duration — a 30-minute appointment takes 30 real minutes on any day of the year. This is also why a drop onto the skipped hour can't come back zero-length.
+- **Known gaps.** `onDayClick` still reports only a date, so in a resource day view it cannot say which column a free slot belongs to. After a keyboard column move, the block re-parents into the new column and loses focus, so nudges can't be chained. `touch-action: none` on a movable block means a touch that starts on an event drags it rather than scrolling the grid. Resource columns are `1fr` with no minimum width, so a dozen lanes squash rather than scroll — the all-day band lays itself out separately and would drift out of alignment if only the hour grid could scroll.
+- The click that terminates a drag is swallowed, so `onEventClick` doesn't fire on a reschedule. A plain click still opens your detail UI.
+- Drag-to-**create** (dragging empty grid space to draft a new event) is still out of scope — use `onDayClick` plus your own form.
+
+#### When NOT to use
+
+- ❌ Single-date or date-range selection → `<DatePicker>` / `<DateRangePicker>`.
+- ❌ Drag-to-create (see above).
+
+#### Anti-patterns
+
+- ❌ Mounting `<Calendar>` with no `events` AND no `onDayClick`: the grid is fully inert.
+- ❌ Pre-grouping events by day in the consumer. Pass the flat array; the layout algorithms group and lane internally.
+- ❌ Treating `onEventMove` as the thing that moves the event. It proposes; your state disposes, and not committing means the block snaps back.
+- ❌ Faking the availability underlay with all-day events, or approximating resource columns with N side-by-side day calendars (see above). Use `backgroundIntervals` and `resources`.

package/docs/components/Card.md

@@ -0,0 +1,165 @@
+# `<Card>` — bordered container
+
+- `fill` makes the Card fill a definite-height parent (`height: 100%`) and
+  applies `min-width: 0` so it can shrink inside narrow Grid, Sortable, and
+  DashboardCanvas cells. When a direct `Card.Body` is present, it also creates
+  Card's internal column/min-height chain. It does not create a height by
+  itself; bound the parent (for example with `Constrain height`) when needed.
+
+```tsx
+<Card padding="md">
+  <Stack gap="md">...</Stack>
+</Card>
+
+// Tone-coded stat card — 3px left-edge stripe in the tone color:
+<Card padding="md" tone="accent">Open deals</Card>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `CardProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | no | Inner padding. - `none` — use when the card contains a table or list that should bleed edge-to-edge; inner sections manage their own padding. - `sm` (12px) — dense info cards. - `md` (16px) — default for plain-content cards. - `lg` (24px) — emphasis cards, marketing-style panels. When omitted, defaults to `'md'` for plain content, or `'none'` when the card contains compound subcomponents (`Card.Header` / `Card.Body` / `Card.List` / `Card.ListRow`) so its sections bleed to the card edge automatically. Pass an explicit value to override the auto-detect. **Detection is shallow:** only direct children are inspected. Fragments (`<>...</>`) are transparent — the detection recurses into them, so conditional renders that wrap compound children in a Fragment still trigger the auto-detect. But wrapping a `Card.Header` in any other element (`<div>`, `<Stack>`, etc.) defeats the heuristic — pass `padding="none"` explicitly in that case. |
+| `tone` | `'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | Optional left-edge tone stripe (3px). Useful for "stat card" / "status card" patterns where one card in a row needs visual emphasis. Default: no stripe (the card keeps its standard bordered look). Uses the same tone vocabulary as `Alert`: `accent` / `info` / `success` / `warning` / `danger`. |
+| `overflow` | `'hidden' \| 'visible'` | no | How the card clips its children at the rounded border. - `hidden` (default) — children are clipped to the rounded border. This prevents the visible seam that appears at the corners when a child has square corners (Table's internal scroll wrapper, images, full-bleed media). Overlays in this library (DropdownMenu, Tooltip, Popover, Drawer, Modal) portal to `document.body` and are NOT clipped by this. Focus rings are NOT exempt: an `outline` is clipped by an ancestor's overflow, so a focusable flush against the card edge loses that band — draw its ring inset by passing `$offset: calc(-1 * var(--ring-offset))` to the `focus-ring` mixin, not a separate `outline-offset` after the `@include` (a `structure.test.ts` gate fails the build on that shape). - `visible` — opt out of clipping. Use when a direct child needs to overhang the card edge — decorative badges that protrude from a corner, hover-lift transforms whose shadow extends past the card border, etc. |
+| `fill` | `boolean` | no | Fill the containing block's height and allow the Card to shrink within a narrow grid cell. Use in stretched Grid, Sortable, or DashboardCanvas cells whose wrapper already has a definite height. When a direct `Card.Body` child is present, `fill` also establishes Card's internal column and minimum-height chain; add `scroll` to the Body to keep a sibling Header fixed above a scrolling content region. Defaults to `false`. |
+| …native | | | plus native `<div>` attributes |
+
+### `CardBodyProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `scroll` | `boolean` | no | Makes the body the flexible vertical scroll region of a `fill` Card while sibling `Card.Header` content stays fixed. The Card's parent must provide a definite height. Defaults to `false`. |
+| …native | | | plus native `<div>` attributes |
+
+### `CardHeaderProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `headerLevel` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | no | Heading level for the title text. Defaults to `'h3'` (assumes the page has an h1/h2 above). Override when this section sits beneath an h1 directly (`headerLevel="h2"`) or further nested (`headerLevel="h4"`). |
+| `surface` | `'default' \| 'subtle'` | no | `'subtle'` paints the header on a tinted (sunken) surface, for a nested editable sub-section inside a `Card.Body` (e.g. a condition group). Defaults to `'default'`. |
+| `controls` | `ReactNode` | no | Optional interactive slot right after the title (e.g. a `ButtonGroup` mode switch). Rendered outside the heading, so it is not part of the heading's name. Order: title, controls, meta, action. Controls never shrink: on a wide header the title ellipsizes down to a short minimum width; on a narrow header (under ~360px of content) the controls wrap onto a second row under the title, which keeps the first row with meta and action. Keep titles short, or pass a `title` attribute for long ones. |
+| `action` | `ReactNode` | no | Optional right-aligned slot — typically a `<Link>` or `<Button>` that lets the user navigate to a full list or take a section-level action. Rendered inside a `<span>` that never shrinks or wraps (flex-shrink: 0; with `meta` or `controls`, min-width: max-content). Beside `controls` it is the removal/section action of a nested sub-group (e.g. a ghost delete button), right-aligned after any meta. |
+| `meta` | `ReactNode` | no | Optional secondary, non-interactive text beside the title — freshness ("Updated 3 minutes ago") or status. Muted and single-line; sits just before `action` and is the first thing to give way at narrow widths: it truncates with an ellipsis before the title gives up any width, while `action` keeps its width. In a `fill` Card (which needs a parent of definite width) it is also visually hidden, still read by screen readers, once only a sliver would show. Not part of the heading's name. Put controls in `controls` or `action`, never here. `false` and `''` count as no meta. |
+| `children` | `ReactNode` | yes | Title content. Becomes the inner text of the heading element. Typically a plain string, but can contain inline elements if needed. |
+| …native | | | plus native `<div>` attributes |
+
+### `CardListProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Row items — typically `<Card.ListRow>` elements. |
+| …native | | | plus native `<ul>` attributes |
+
+### `CardListRowProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Row content — typically a `<Stack>` or `<Cluster>` of text and metadata. |
+| …native | | | plus native `<li>` attributes |
+
+<!-- props:end -->
+
+```tsx
+// Fixed header + scrolling body in a definite-height dashboard cell.
+<Constrain height="sm">
+  <Card fill>
+    <Card.Header>Pipeline</Card.Header>
+    <Card.Body scroll>
+      <Stack gap="sm">...</Stack>
+    </Card.Body>
+  </Card>
+</Constrain>
+```
+
+```tsx
+// Compound API — section card with header + list (Dashboard's "Deals needing attention" pattern).
+// No `padding` prop needed — Card auto-detects compound children and defaults to padding="none".
+<Card>
+  <Card.Header
+    action={
+      <Link as={RouterLink} to="/deals">
+        View all
+      </Link>
+    }
+  >
+    Deals needing attention
+  </Card.Header>
+  <Card.List>
+    {deals.map((d) => (
+      <Card.ListRow key={d.id}>
+        <Stack gap="xs">
+          <span>{d.title}</span>
+          <span>{d.company}</span>
+        </Stack>
+        <Avatar name={d.owner} size="sm" />
+      </Card.ListRow>
+    ))}
+  </Card.List>
+</Card>
+```
+
+- **Compound API** — `Card.Header` / `Card.Body` / `Card.List` / `Card.ListRow` for section-card patterns. Drop `padding="none"` — the parent Card auto-detects compound children.
+- `Card.Header`: title row (`h3` by default, override via `headerLevel`) with optional right-aligned `action` slot and bottom-border separator. Optional `meta` is muted secondary text (freshness, status) just before `action`; at narrow widths it truncates before the title shrinks (in a `fill` Card it then hides visually, staying readable by screen readers), and `action` never shrinks. Keep controls out of `meta`. With `controls` the order is title · controls … meta · action: controls and `action` never shrink, meta truncates first, and `action` stays right-aligned.
+- With `controls`, the title stays on one line. On a wide header it ellipsizes down to a short minimum width rather than pushing the controls out; on a narrow header (under ~360px of content) the controls wrap onto a second row under the title, and the first row keeps title · meta · action. For long titles beside `controls`, pass a `title` attribute so the full text stays reachable (`<Card.Header controls={…}><span title={name}>{name}</span></Card.Header>`), or keep titles short.
+- `Card.Body`: padded `<div>` content section. Add `scroll` beneath a Header in a `fill` Card to make Body the flexible vertical scroll region while Header stays fixed. Card intentionally owns this layout because it relates only its own compound pieces; the parent still owns the Card's definite outer height. `scroll` also sets `tabIndex={0}`, because a scroll container with no focusable descendant is unreachable by keyboard (axe `scrollable-region-focusable`) — pair it with `role="group"` and an `aria-label` when the content is worth naming, and pass `tabIndex={-1}` to opt out if the body already contains something focusable.
+- `Card.List`: semantic `<ul>` with list-reset styling — screen readers announce "list with N items".
+- `Card.ListRow`: `<li>` with padded content and bottom dividing border; last-child border suppressed automatically.
+- **Never nest Card in Card** — except an editable, repeatable sub-group (e.g. a condition group) inside a `Card.Body`, using `Card.Header surface="subtle"`; never for display-only content or as a layout wrapper. `controls` holds the sub-section's inline controls and `action` its remove button:
+
+```tsx
+<Card>
+  <Card.Header>Rules</Card.Header>
+  <Card.Body>
+    <Card>
+      <Card.Header
+        surface="subtle"
+        controls={
+          <ButtonGroup value={mode} onValueChange={setMode} aria-label="Match">
+            <ButtonGroup.Item value="all">Match all</ButtonGroup.Item>
+            <ButtonGroup.Item value="any">Match any</ButtonGroup.Item>
+          </ButtonGroup>
+        }
+        action={
+          <Button iconOnly variant="ghost" aria-label="Delete group">
+            <X size={12} />
+          </Button>
+        }
+      >
+        Group
+      </Card.Header>
+      <Card.Body>…conditions…</Card.Body>
+    </Card>
+  </Card.Body>
+</Card>
+```
+
+- `Card.Header` sits flush with the card edge inside `<Card padding="none">`. It renders a `<div>` holding the heading element plus an optional `<span>` wrapping `action` (with `meta`, a muted `<span>` between them and the header switches to a grid). With `controls`, the header is an inline-size container holding one inner `<div>` grid of four items — heading · controls `<span>` · meta (or an empty spacer) · action (or an empty placeholder) — so `action` stays right-aligned; a container query moves the controls to a second row when the header is narrow. The containment means a controls header contributes no intrinsic width, so give its Card a definite width (any block parent does). Under an `h1` with no `h2` above, pass `headerLevel="h2"`.
+- `Card.List` / `Card.ListRow`: row dividers use a `:last-child` selector to suppress the final bottom border. Fragments are transparent, but wrapping rows in an extra `<div>` or other element breaks the match and leaves a stray divider on the last row. Render rows as direct children (or via `.map`).
+- `Card.Body` keeps `scroll` for a bounded `fill` Card (Grid, Sortable or DashboardCanvas cell); for page-level scrolling let the page or `AppLayout` own the scroll area. Keep it a direct child of Card (Fragments are transparent) so Card can detect the compound structure.
+
+#### When NOT to use
+
+- ❌ Inside another Card, except the editable sub-group exception above (`Card.Header surface="subtle"` in a `Card.Body`). Never as the only child of another Card, or as a layout primitive (use `Stack` / `Cluster` / `Grid`). Card is for semantic grouping.
+- ❌ For every container. If the page looks like a deck of cards, nothing is visually grouped.
+- ❌ `Card.Body` outside a Card. It owns padding and sizing only as part of Card's compound structure.
+
+#### Anti-patterns
+
+- ❌ `<Card style={{ padding: 20 }}>`: use `padding`. A missing value is a token/scale conversation.
+- ❌ `<Card style={{ overflow: 'visible' }}>`: use `<Card overflow="visible">`.
+- ❌ `<Card style={{ height: '100%' }}>`: use `<Card fill>`, which also applies the shrink-safe minimum width for narrow grid cells.
+- ❌ Hand-rolling a flex column and scrolling body in a Card, or consumer CSS for `flex: 1`, `min-height: 0` or `overflow-y: auto`. Use `<Card fill>` with `<Card.Body scroll>`.
+- ❌ Expecting `scroll` to create a height. The Card's parent must provide a definite height; `fill` carries that bound into the body.
+- ❌ Hover shadows to make Cards "interactive". If the whole card is clickable, that's a different component (`LinkCard`).
+- ❌ Hand-rolling a left stripe via `className` / `style`. Use `tone`; it reserves the border-left space so layout never shifts.
+- ❌ Hand-rolling `.cardHeader` / `.list` / `.listRow` SCSS. Use the compound API.

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.