@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/Lightbox.md

@@ -0,0 +1,105 @@
+# `<Lightbox>` — full-screen image & document gallery overlay
+
+`<Lightbox open onOpenChange items>` shows one large item at a time (an image, or a PDF in an `<iframe>`) with prev/next chevrons, ← → keys, a thumbnail strip, a position counter, and an optional caption. Controlled `open` like `<Modal>`; the current index is uncontrolled (`defaultIndex`) unless you pass `index` + `onIndexChange`. `loop` (default true) wraps at the ends. The consumer owns the trigger — typically a row of interactive `<Image>` thumbnails. For a single inline image use `<Image>`.
+
+```tsx
+const [open, setOpen] = useState(false);
+const [start, setStart] = useState(0);
+<Lightbox
+  open={open}
+  onOpenChange={setOpen}
+  defaultIndex={start}
+  items={files.map((f) => ({ src: f.url, alt: f.name, caption: f.name }))}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `open` | `boolean` | yes | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | yes | Fired when the Lightbox wants to close — Esc, backdrop click, the × button. |
+| `items` | `LightboxItem[]` | yes | The images and documents (mixed galleries are supported; see `kind` on `LightboxItem` for PDFs). A PDF without a `thumbnail` shows a document-icon placeholder in the strip; an unsafe (non-http(s)) document `src` shows a "Preview unavailable" message. An empty array renders nothing and behaves as closed (no inert page, scroll lock or focus trap) even while `open`. |
+| `defaultIndex` | `number` | no | Initial image index (uncontrolled). Defaults to `0`. Clamped to range. |
+| `index` | `number` | no | Controlled current index. When set, pair with `onIndexChange`. |
+| `onIndexChange` | `((index: number) => void)` | no | Fired on navigation (chevron / arrow key / thumbnail click). |
+| `loop` | `boolean` | no | Wrap past the first/last image. Defaults to `true`. |
+| `actions` | `((item: LightboxItem, index: number) => ReactNode)` | no | Extra header actions for the current item (e.g. a Download `<Button>`, a `<DropdownMenu>` "more" menu). Called with the current item and its index on every render, so it follows navigation. Rendered in the top-right toolbar BEFORE the close button. Use `<Button iconOnly variant="ghost" size="sm">` (or a DropdownMenu trigger built from one) — the toolbar re-themes ghost Buttons for the dark scrim (ghost tokens, full radius, `sm` height = the toolbar control size), so text Buttons render pill-shaped — keep actions icon-only. While an action's menu or popover is open, Esc closes it first, and ←/→ stay with it (not the gallery) while focus is in it — likewise while focus is on a text field, combobox (Select), radio (ButtonGroup), slider, tab or expanded trigger; a Tooltip on an action doesn't block navigation. Returning `null`/`undefined` renders nothing. REPLACES the built-in PDF download link: when `actions` is set, the Lightbox renders no download action of its own — include your own Download for PDF items if you want one. |
+| `className` | `string` | no | className for the dialog container. |
+| `aria-label` | `string` | no | Accessible label for the dialog. Defaults to the i18n "Image gallery" when omitted OR empty — an empty string is not an explicit name, so it takes the default too. |
+
+<!-- props:end -->
+
+- Each `LightboxItem` is `{ src, alt, kind?, caption?, thumbnail? }` — `alt` is required.
+- Single item → chevrons, counter, and strip auto-hide. Empty `items` → renders nothing.
+- Reuses the DS overlay machinery (focus-trap, scroll-lock, Esc — yielding to open floating surfaces first like Modal/Drawer, stacking above modals).
+
+Mixed gallery (images + a PDF):
+
+```tsx
+<Lightbox
+  open={open}
+  onOpenChange={setOpen}
+  items={[
+    { src: shot.url, alt: 'Screenshot' },
+    { src: doc.url, alt: 'Contract.pdf', kind: 'pdf' },
+  ]}
+/>
+```
+
+Header actions — `actions(item, index)` renders consumer controls in the top-right toolbar, before the close button, for the current item (re-rendered on navigation). Use `<Button iconOnly variant="ghost" size="sm">` (and DropdownMenu triggers built from one); the toolbar re-themes ghost Buttons for the dark scrim. The toolbar re-themes any Button inside it (ghost tokens, full radius, `sm` height = the toolbar control size), so a text Button renders pill-shaped — keep actions `variant="ghost" iconOnly`. A DropdownMenu, Popover or ConfirmationPopover opened from an action works normally — while focus is in it, ←/→ stay with it (no gallery navigation), and Esc closes it first, then the Lightbox. ←/→ also stay put while focus is on a text field, a Select (combobox), a ButtonGroup radio, a Slider, a Tab or an expanded trigger. A Tooltip on an action does not block ←/→.
+
+```tsx
+<Lightbox
+  open={open}
+  onOpenChange={setOpen}
+  items={files}
+  actions={(item) => (
+    <>
+      <Button
+        as="a"
+        href={item.src}
+        download
+        target="_blank"
+        rel="noopener noreferrer"
+        iconOnly
+        variant="ghost"
+        size="sm"
+        aria-label={t('download')}
+      >
+        <Download size={20} aria-hidden="true" />
+      </Button>
+      <DropdownMenu>
+        <DropdownMenu.Trigger>
+          <Button iconOnly variant="ghost" size="sm" aria-label={t('more')}>
+            <MoreHorizontal size={20} aria-hidden="true" />
+          </Button>
+        </DropdownMenu.Trigger>
+        <DropdownMenu.Content align="end">
+          <DropdownMenu.Item onSelect={() => rename(item)}>Rename</DropdownMenu.Item>
+        </DropdownMenu.Content>
+      </DropdownMenu>
+    </>
+  )}
+/>
+```
+
+**`actions` replaces the built-in PDF download.** Without `actions`, a PDF item gets a Download link automatically. With `actions` set, the Lightbox renders no download of its own — the consumer owns the whole header, so include a Download action yourself if PDFs (or images) should be downloadable.
+
+Tall or wide images are scaled down (`object-fit: contain`) to fit the stage — never cropped.
+
+**When NOT to use**
+
+- A single, always-visible image — use `<Image>` (optionally `interactive`).
+- An arbitrary modal dialog (not an image/PDF preview) — use `<Modal>`.
+
+**Anti-patterns**
+
+- ❌ Building your own `Modal` + `Image` + arrows — that is what this is.
+- ❌ Omitting `alt` on items — it is required and names the thumbnail and the stage.
+- ❌ Passing `index` without `onIndexChange` — navigation would be a no-op.
+- ❌ Passing `actions` and expecting the built-in PDF download to stay — `actions` replaces it; add your own Download action.
+- ❌ Primary/secondary Buttons in `actions` — they ignore the scrim re-theme and look out of place; use `variant="ghost" iconOnly size="sm"`.

package/docs/components/Link.md

@@ -0,0 +1,65 @@
+# `<Link>` — polymorphic styled anchor
+
+Inline navigation link. Polymorphic via `as` — defaults to `<a>`, consumers pass a router's `<Link>` for SPA navigation. Three visual variants cover the inline use cases.
+
+```tsx
+import { Link } from '@eocrm/design-system';
+
+// External — defaults to <a>
+<Link href="https://docs.example.com">Documentation</Link>
+
+// SPA route — pass router's Link
+import { Link as RouterLink } from 'react-router-dom';
+<Link as={RouterLink} to="/contacts">Contacts</Link>
+
+// Variants
+<Link href="/x">View all</Link>                                  {/* default — link colour, hover-underline */}
+<Link href="/x" variant="muted">Subdued nav</Link>               {/* breadcrumb-style */}
+<Link href="/x" variant="subtle">Contact name</Link>             {/* fg color, hover-accent */}
+
+// underline — independent of variant
+<Link href="/x" underline="always">documentation</Link>          {/* running text / body copy — required, see below */}
+<Link href="/x" variant="subtle" underline="none">Acme Inc</Link> {/* brand/nav — no hover underline */}
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'muted' \| 'subtle'` | no | Visual variant. See `LinkVariant` for descriptions. |
+| `underline` | `'hover' \| 'always' \| 'none'` | no | Underline behavior. See `LinkUnderline` for descriptions. Default: `'hover'`. |
+| `children` | `ReactNode` | no |  |
+| `as` | `ElementType` | no |  |
+| …native | | | plus native attributes of the `as` element (default `<a>`) |
+
+<!-- props:end -->
+
+- **Polymorphic**: `as={Component}` forwards all of Component's props with full TypeScript inference.
+- **Library has no router dependency** — the `as` mechanism is consumer-driven.
+- **Three variants**:
+  - `default`: link colour (`--color-link-fg`; the accent unless the accent set overrides it — `tealpine` uses a brighter teal at medium weight), hover-underline. Inline CTA ("View all →").
+  - `muted`: muted color, hover-accent. Low-emphasis nav (breadcrumb-style).
+  - `subtle`: foreground color, hover-accent + underline. Dense-surface name links. **Not deprecated** — this is `Link`'s own variant and is unrelated to `Text`/`Title`'s `tone="subtle"`, which WAS deprecated. Same word, opposite status: a grep for "subtle deprecated" will land on the tone, and `PersonDisplay.Name` uses this variant deliberately.
+- **`underline` prop** (`'hover'` | `'always'` | `'none'`, default `'hover'`) — orthogonal to `variant`:
+  - `'hover'` (default, same as omitting it): each variant's existing look — `default`/`subtle` underline on hover only, `muted` never underlines.
+  - `'always'`: underlined at rest and on hover, on every variant.
+  - `'none'`: never underlined, not even on hover, on every variant.
+  - **Links inside running text/body copy MUST use `underline="always"`.** The default accent-on-body contrast falls short of WCAG 1.4.1's 3:1 non-text threshold, so color alone isn't a sufficient cue — a link needs an underline to be told apart from surrounding words. `underline="none"` is for brand/nav links that want a variant's subtle color without the hover underline (the opposite end of the same axis).
+- **No `disabled` state** — render `<span>` directly for non-clickable labels.
+
+#### When NOT to use
+
+- ❌ Action triggers (submit, open modal) → use `<Button>`.
+- ❌ Mutually-exclusive switchers → use `<Tabs>` or `<ButtonGroup>`.
+- ❌ "Link styled as button" → use `<Button variant="ghost">`.
+
+#### Anti-patterns
+
+- ❌ `<Link href="#" onClick={...}>` — fake hrefs break right-click "open in new tab".
+- ❌ Forgetting `rel="noopener noreferrer"` on `target="_blank"` links.
+- ❌ Using `variant="default"` for low-emphasis nav like breadcrumbs.
+- ❌ A Link inside running text/body copy without `underline="always"` — color alone isn't a sufficient visual cue (WCAG 1.4.1).
+- ❌ A `default` Link inside `<Text weight="semibold">` (or `bold`) under `data-accent="tealpine"` — the link renders at the accent's medium weight, lighter than the words around it. Wrap the bold run in `<strong>` or give the Link a matching weight via `className`.

package/docs/components/LinkCard.md

@@ -0,0 +1,41 @@
+# `<LinkCard>` — clickable, full-surface Card
+
+```tsx
+// SPA route — pass your router's Link as `as`
+<LinkCard as={RouterLink} to="/contacts/42" padding="md">
+  <Stack gap="xs">
+    <Text weight="semibold">Acme Corp</Text>
+    <Text size="sm" tone="muted">12 open deals</Text>
+  </Stack>
+</LinkCard>
+
+<LinkCard href="https://status.example.com" tone="success">All systems operational</LinkCard>
+<LinkCard as="button" type="button" onClick={openImporter}>Import contacts</LinkCard>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | no | Inner padding — same scale as `Card`. Defaults to `'md'`. |
+| `tone` | `'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | Optional left-edge tone stripe — same vocabulary as `Card`. |
+| `children` | `ReactNode` | no |  |
+| `as` | `ElementType` | no |  |
+| …native | | | plus native attributes of the `as` element (default `<a>`) |
+
+<!-- props:end -->
+
+- A Card whose **whole surface** navigates/acts. Polymorphic like `<Link>` — `as` defaults to `<a>`; pass `as={RouterLink} to=…` for routes or `as="button"` for actions (the library has no router dep).
+- Carries `Card`'s `padding` (default `md`) + `tone` stripe (reuses `--card-*` tokens), plus a hover lift (border + shadow) and a `:focus-visible` ring.
+- Use `<Card>` for non-interactive grouping, `<Link>` for inline text, `<Button>` for form actions. **Don't nest** interactive controls inside it (invalid nested interactives).
+
+**Anti-patterns:**
+
+- ❌ Nesting interactive controls (`<Button>` / `<Link>`) inside a LinkCard — nested interactives are invalid + confusing.
+- ❌ `<LinkCard href="#" onClick={…}>` — fake href breaks "open in new tab". Use `as="button"` for actions.
+- ❌ `<LinkCard href="https://…" target="_blank">` without `rel="noopener noreferrer"` — security risk.
+
+**A11y:** renders a real `<a>` / `<button>` / router link, so it has native semantics; the children supply the accessible name — keep the primary label first. `:focus-visible` provides the keyboard ring.

package/docs/components/LiquidEditor.md

@@ -0,0 +1,84 @@
+# `<LiquidEditor>` — Liquid template editor
+
+Liquid template editor: syntax highlighting, line-number gutter, variable-insert menu, caret autocomplete, client-side unknown-variable flagging, and a controlled preview pane. Controlled only (`value` + `onChange`). It never parses or renders Liquid — backend syntax errors arrive via `invalid`/`error`; the rendered preview arrives via `preview`/`previewStatus`.
+
+```tsx
+const VARS = [
+  { code: 'first_name', label: 'First name', type: 'text', group: 'Built-in' },
+  { code: 'last_name', label: 'Last name', type: 'text', group: 'Built-in' },
+];
+
+<LiquidEditor value={formula} onChange={setFormula} variables={VARS} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | Controlled template source. |
+| `onChange` | `(value: string) => void` | yes | Fires on every edit (typing, paste, variable insert, autocomplete accept). |
+| `variables` | `LiquidVariable[]` | no | Available variables → insert menu, autocomplete, unknown flagging. |
+| `flagUnknownVariables` | `boolean` | no | Underline `{{ vars }}` not present in `variables`. Default `true` (no-op when `variables` empty). |
+| `invalid` | `boolean` | no | External error visual (red border) — set from a backend Liquid syntax error. Default `false`. |
+| `error` | `ReactNode` | no | External error message shown in the footer. Pairs with `invalid`. |
+| `preview` | `ReactNode` | no | Consumer-rendered preview output. When set (or `previewStatus` ≠ 'idle'), the pane shows. |
+| `previewStatus` | `'idle' \| 'loading' \| 'error'` | no | Preview pane chrome. Default `'idle'`. |
+| `previewPlacement` | `'bottom' \| 'right'` | no | Preview pane position. Default `'bottom'`. |
+| `showLineNumbers` | `boolean` | no | Show the line-number gutter. Default `true`. |
+| `showToolbar` | `boolean` | no | Show the toolbar (variable-insert menu). Default `true`. |
+| `toolbarActions` | `ReactNode` | no | Custom action buttons rendered in the toolbar, right-aligned just before the "Insert variable" button (e.g. a Docs / Help link). Pass `<Button size="sm">` elements (or a fragment of them); a `ghost` variant pairs well next to the bordered "Insert variable" button. Only renders when `showToolbar` is true. |
+| `filters` | `string[]` | no | Filter names offered in autocomplete after `\|`. Defaults to a common Liquid set. |
+| `minRows` | `number` | no | Minimum visible rows. Default `4`. |
+| `maxRows` | `number` | no | Maximum visible rows before the editor scrolls internally. Default unbounded. |
+| `readOnly` | `boolean` | no | Read-only: caret + selection allowed, no edits. Default `false`. |
+| `disabled` | `boolean` | no | Disabled: non-interactive + dimmed. Default `false`. |
+| `id` | `string` | no | Optional id forwarded to the textarea (for `<Field>` / label association). |
+| `name` | `string` | no | Optional name forwarded to the textarea. |
+| `placeholder` | `string` | no | Placeholder shown when empty. |
+| `aria-label` | `string` | no | Accessible label (defaults to the i18n `liquidEditor.editorLabel` when omitted OR empty — an empty string is not an explicit name). |
+| `aria-labelledby` | `string` | no | Id of an external label element. |
+| `aria-describedby` | `string` | no | Id(s) of external description element(s). Merged with the component's own footer description (the `error` / unknown-variable message), so a screen reader announces both. You usually don't need this — the footer is wired automatically; pass it only to add an extra external description. |
+| `className` | `string` | no | Extra class on the root wrapper. |
+
+<!-- props:end -->
+
+**Toolbar:** the right-aligned "Insert variable" dropdown is a bordered `secondary` `sm` button. Pass `toolbarActions` (a `ReactNode`, e.g. `<Button variant="ghost" size="sm">…</Button>` for a Docs/Help link) to add extra buttons right-aligned just before it. Hidden when `showToolbar={false}`.
+
+**Gutter:** `showLineNumbers={false}` hides the line-number gutter (default `true`) — right for single-line formula inputs and dense forms; combine with `showToolbar={false}` for the most minimal chrome.
+
+**Grouped/dotted palettes (`group`, `description`, `collection`):** each `variables` entry can carry a `group` (a section label in the insert menu, first-seen order — ungrouped entries render unlabeled), a `description` (a muted second line in the insert menu and autocomplete list, and — when the caret sits inside that exact reference — the footer, as `label — description`), and `collection: true` (an autocomplete/menu "list" tag; inserting it drops a `{% for item in code %}{{ item }}{% endfor %}` snippet with the caret left after `{{ item }}`, instead of `{{ code }}`). Unknown-variable flagging matches on the dotted `code` **root** (a variable coded `event.type` still validates inside `event.type.sub` — nested-field codes don't false-flag as unknown); autocomplete prefix-matches the full dotted `code` (typing `ev` or `event.t` suggests `event.type`).
+
+```tsx
+const VARS = [
+  {
+    code: 'event.type',
+    label: 'Event type',
+    group: 'Event',
+    description: 'The journal event type',
+  },
+  {
+    code: 'record.associations',
+    label: 'Associations',
+    group: 'Record',
+    collection: true,
+    description: "The record's links — iterate with for",
+  },
+];
+
+<LiquidEditor value={tpl} onChange={setTpl} variables={VARS} />;
+```
+
+When NOT to use: plain prose → `Textarea`; static read-only code → playground `CodeBlock`. Don't expect it to validate syntax (feed `error` from the backend) or to produce its own preview (preview is consumer-rendered).
+
+Inside a `<Field>`, the label is associated automatically (`id` / `aria-labelledby`):
+
+```tsx
+<Field label="Formula">
+  <LiquidEditor value={formula} onChange={setFormula} variables={VARS} />
+</Field>
+```
+
+- ❌ Adding `margin`/positioning hoping the editor self-places — that is the parent's job (`<Stack>` / `<Cluster>` / a wrapper `className`).

package/docs/components/List.md

@@ -0,0 +1,68 @@
+# `<List>` — bulleted / numbered prose lists (ul / ol)
+
+Semantic list of prose items: facts, steps, header names, error extras. Renders `<ul>` / `<ol>` with `<li>`, component-drawn markers aligned to the first text line, and a hanging indent. Compound: `List`, `List.Item`.
+
+TL;DR: `<List>` for bullets, `<List variant="number">` for ordered steps, `numberStyle="badge"` for numbered-step cards.
+
+```tsx
+<List variant="number" numberStyle="badge">
+  <List.Item>Open Settings and choose Integrations.</List.Item>
+  <List.Item>Paste the API token and save.</List.Item>
+</List>
+
+<List gap="xs">
+  <List.Item>
+    <code>X-RateLimit-Remaining</code> — requests left in the window.
+  </List.Item>
+  <List.Item>
+    <code>Retry-After</code> — seconds to wait after a 429.
+  </List.Item>
+</List>
+
+<List variant="number" numberStyle="badge" size="heading" gap="md">
+  <List.Item>
+    <Title order={3} size="xl">Create a token</Title>
+  </List.Item>
+</List>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `ListProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `variant` | `'bullet' \| 'number'` | no | Marker style. See `ListVariant`. Default `'bullet'`. |
+| `gap` | `'xs' \| 'sm' \| 'md'` | no | Space between items. See `ListGap`. Default `'sm'`. |
+| `size` | `'body' \| 'heading'` | no | Marker scale; use `'heading'` when each item starts with a `Title size="xl"`. See `ListSize`. Default `'body'`. |
+| `numberStyle` | `'plain' \| 'badge'` | no | Number look; only applies to `variant="number"`. See `ListNumberStyle`. Default `'plain'`. |
+| `children` | `ReactNode` | no | `List.Item` elements. A nested `List` goes inside a `List.Item`. |
+| …native | | | plus native HTML attributes |
+
+### `ListItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | no | Item content. Text, inline elements, or a nested `List`. |
+| …native | | | plus native `<li>` attributes |
+
+<!-- props:end -->
+
+- Numbers come from CSS counters, so adding, removing or conditionally rendering items keeps them contiguous. There is no `start` prop.
+- Markers are `aria-hidden`; the list carries an explicit `role="list"` so Safari/VoiceOver keeps list semantics.
+- Text inherits size and colour, so it works inside `Card`, `Alert` and prose-width containers.
+- Nest by putting a `List` inside a `List.Item`; it indents one level. A nested `List` uses its own `size`, so a body list inside a `size="heading"` step keeps body markers.
+- On a `size="heading"` List, marker size, shape and font size come from the `--list-heading-*` tokens: overriding `--list-marker-height`/`-width`, `--list-bullet-size`, `--list-number-font-size` or `--list-badge-size`/`-radius`/`-font-size` has no effect there. Colour, weight and gap tokens (`--list-marker-fg`, `--list-badge-bg`/`-fg`, `--list-*-font-weight`, `--list-marker-gap`) apply to both sizes.
+- `numberStyle` has no effect on bullets.
+- With `numberStyle="badge"` the numbers are visual only; screen readers announce the list position ("1 of 3") rather than the badge text.
+- `size="heading"` fits markers to a `Title size="xl"` first line; the badge turns into a rounded square.
+
+When NOT to use: key–value pairs → `DefinitionList`; rows of records → `Card.List` / `Table`; interactive or selectable rows → `Card.List`; custom markers or icons (unsupported).
+
+- ❌ Raw `<ul>` / `<ol>` or `Stack` + `Dot` composites for prose lists: use `List`.
+- ❌ Children other than `List.Item` (a `div`, text, a raw `li`): they get no marker and are not counted. Wrapper components are fine if they render `List.Item`.
+- ❌ Using `numberStyle="badge"` with `variant="bullet"` expecting badges: it is ignored.

package/docs/components/LiveRegion.md

@@ -0,0 +1,29 @@
+# `<LiveRegion>` — announcement region for consumer-level outcomes
+
+```tsx
+<LiveRegion>{status}</LiveRegion>
+<LiveRegion politeness="assertive">{error}</LiveRegion>
+<LiveRegion announceKey={saveCount}>{t('saved')}</LiveRegion>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | no | The message. Pass a string, a number, or an array of only strings/ numbers (e.g. `[count, ' files uploaded']`) — these compare by value, so an unchanged value does not re-announce and a changed one does. Anything else (JSX elements) compares by identity and re-announces on every parent render, even when the rendered text is unchanged. Empty, `null`, or `false` clears the region and announces nothing. |
+| `politeness` | `'polite' \| 'assertive'` | no | How urgently the region interrupts. - `'polite'` (default) — `role="status"` + `aria-live="polite"`. Waits for the screen reader to finish its current utterance. Use for routine outcomes: saves, copy confirmations, background updates. - `'assertive'` — `role="alert"` + `aria-live="assertive"`. Interrupts immediately. Reserve for errors that need immediate attention. Change politeness in the SAME render as the message (`politeness={error ? 'assertive' : 'polite'}` next to `{error ?? status}`): the role only flips while the region is empty, so the old text is never announced at the new urgency. A politeness-only change re-announces the current text at the new urgency. |
+| `announceKey` | `string \| number` | no | Change this (e.g. a counter) to announce the same message again. Without it, re-rendering with identical text is a no-op — screen readers only announce a live region on a text change. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- **Always mount it unconditionally** — it clears then rewrites its text ~50ms later on mount and on every change, so the empty → text transition is what triggers the announcement. A conditionally-mounted region won't announce reliably. Messages changing faster than every ~50ms keep restarting that delay — only the last one of the burst is announced.
+- Props type omits `role` / `aria-live` / `aria-atomic` / `hidden` / `aria-hidden` — it spreads the rest of `HTMLAttributes<HTMLSpanElement>` FIRST so those can't be overridden.
+
+**When NOT to use:** don't wrap a library component that already owns its own transient-state region (see [Transient state and screen readers](../transient-state.md)) — two regions announcing one event talk over each other. Don't announce text that's already visible and focused — the user hears it twice. Don't reach for `assertive` for routine success. Prefer a string child over JSX — element children re-announce on every parent render even when the rendered text is unchanged.
+
+- ❌ Placing it inside a `<label>` or a `<button>` — inside a `<label>` it joins the control's accessible name via name-from-content; inside a `<button>` it is pruned as children-presentational. Render it as a sibling instead.
+- ❌ Mounting it conditionally (`{msg && <LiveRegion>…}`) — keep it mounted and pass an empty message.

package/docs/components/LocaleProvider.md

@@ -0,0 +1,25 @@
+# `<LocaleProvider>` + `useLocale` — locale Context
+
+```tsx
+<LocaleProvider locale="ru-RU">
+  <App />
+</LocaleProvider>;
+
+const locale = useLocale(); // 'ru-RU', or navigator.language fallback
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `locale` | `string` | yes | BCP-47 locale string, e.g. 'en-US', 'ru-RU', 'de-DE'. |
+| `children` | `ReactNode` | yes |  |
+
+<!-- props:end -->
+
+- `LocaleProvider` exposes a BCP-47 locale string to descendants. Any locale-aware component (Calendar primitives today; future Input formatters, currency widgets) reads via `useLocale()`.
+- No `<LocaleProvider>` mounted? `useLocale()` falls back to `navigator.language` (or `'en-US'` in SSR / Node).
+- Stateless. To switch locale at runtime, re-render the Provider with a new `locale` prop. Nested Providers override outer ones.

package/docs/components/Logo.md

@@ -0,0 +1,41 @@
+# `<Logo>` — brand logo lockup
+
+```tsx
+import logo from '../assets/eocrm-logo.svg'; // a consumer-owned asset
+<Logo src={logo} text="eocrm" size="lg" />                       // mark + wordmark
+<Logo src={logo} label="eocrm" />                                // mark only (accessible name)
+<Logo src={logo} text="eocrm" textPlacement="bottom" />
+<Logo src={logo} text="eocrm" subtext="Free trial" size="sm" />  // mark + name + muted subline
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `src` | `string` | yes | The brand mark image URL — typically an imported SVG/PNG asset. The mark is a **consumer-owned asset**; the design system ships no logo of its own. Rendered as an `<img>` (`object-fit: contain`) with no CSS recolor — the asset carries its own color. For third-party SSO marks use `<BrandIcon>`. |
+| `text` | `ReactNode` | no | Wordmark rendered beside (or below) the mark — consumers pass `"eocrm"`. Omit for a mark-only logo. |
+| `textPlacement` | `'end' \| 'bottom'` | no | Where the wordmark sits relative to the mark. Defaults to `'end'` (beside); `'bottom'` stacks it under the mark, centered. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Mark size — `'sm'` (24) / `'md'` (32, default) / `'lg'` (40). |
+| `label` | `string` | no | Accessible name for the mark when there's no `text` (used as the image `alt`). Omit for a decorative mark (`alt=""`), or when `text` is present (the wordmark is the name). Never pass both `text` and `label`. |
+| `subtext` | `ReactNode` | no | Small, muted secondary line rendered under `text` — e.g. a plan or tagline (`subtext="Free trial"`). Only shown when `text` is present. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Arranges a **consumer-supplied** mark image (`src`, required — import an SVG/PNG) with an optional wordmark beside (default) or below (`textPlacement="bottom"`). The design system ships **no** logo of its own.
+- **Wordmark font:** override `--logo-text-font` / `--logo-text-font-weight` to set the wordmark's font + weight (defaults: inherited sans, bold). Affects only `text`, not the mark or `subtext`; load the font yourself (the DS ships none).
+- **Spacing:** `--logo-gap` (mark → wordmark, default `var(--space-2)`) and `--logo-text-gap` (wordmark → subtext, default `var(--space-1)`). `--logo-text-gap` only takes effect where `text-box-trim` is supported; elsewhere the lockup falls back to line-height leading for that separation, so it reads looser and taller (never clipped) — see the migration note below for how much. Where it does apply it is genuine clear space: adding a `subtext` moves the wordmark's under-edge from the baseline down to the font's descent, so a wordmark with descenders (`paygo`) keeps its tails out of the subline instead of eating the gap. Because it is measured from that descent line rather than from the ink, a descender-free wordmark shows roughly 1.8–2.3× the token as visible space (the descent is a fixed fraction of em while the token is a fixed 4px, so the ratio grows with `size`). The subtext itself keeps an `alphabetic` under-edge, so a subtext with descenders puts a little ink below the lockup's own bottom edge — ~2px at `sm`, its worst case; at `md`/`lg` the mark is tall enough to absorb it. Fine inside padded chrome, worth knowing if you clip a box sized exactly to the lockup. Like the migration figures, these depend on the subtext's face, which is `--font-family-sans` rather than your wordmark font.
+- **Optical alignment is automatic, and `text` decides it.** Where `text-box-trim` is supported the wordmark is trimmed to its cap edge, or to its x-height edge when every glyph tops out at x-height (`eocrm`, `acme`). Anything with a capital, an ascender (`b d f h k l t`), a dotted `i`/`j`, a digit, or a non-Latin script takes the cap edge — so `<Logo text="eocrm">` and `<Logo text="lockbox">` are trimmed to different edges — their boxes differ, while the ink stays on the same optical centre against the mark. Nothing to configure; pass a non-string `text` (an element) and it takes the cap edge too.
+- ⚠️ **_Migration:_ the lockup got shorter wherever `text-box-trim` is supported (Chrome/Safari; not Firefox).** Trimming the wordmark's half-leading is new — previous versions carried the font's full leading — most lockups with a `subtext`, and every `textPlacement="bottom"` lockup, render measurably shorter at the same `size`. Measured, per shape (before → after):
+  - `subtext="Free trial"`, beside the mark — `sm` 30.8px → 24.0px, `md` 35.2px → 32.0px
+  - `textPlacement="bottom"`, **no** subtext — `lg` 74.4px → 59.6px
+  - `textPlacement="bottom"` **with** a subtext — `sm` 62.8px → 55.3px
+
+  These come from the playground, which renders the wordmark in Outfit 600 and leaves the subtext on `--font-family-sans` — so every figure above with a subtext is a function of two faces. The DS ships no font of its own, so yours will shift all of them; treat these as the shape of the change, not constants. The side-by-side lockup **without** a subtext keeps its height at every size (the mark sets it), and at `lg` even the with-subtext lockup does — only `sm`/`md` shrink there.
+
+  **Height is not the only thing that moved.** Trimming the leading also raises the wordmark against the mark in **every** shape, including the ones whose height is unchanged. Side-by-side without a subtext, the wordmark's ink centre sat 1.3 / 2.2 / 3.0px _below_ the mark's **box** centre at `sm`/`md`/`lg` and now sits within 0.1px of it — it rises by roughly 1.5px at `sm` up to 3px at `lg`. That is the correction this is for (the wordmark used to hang low), but it means the shape you use most did change visually even though it did not change size. Firefox keeps the old position as well as the old height, so the same lockup differs across browsers by that 1.5–3px on top of the height gap — which is **up to** ~28% (`sm` with a subtext) and 0% for the side-by-side lockup without one. If you center a Logo in a fixed-height brand bar or auth splash, re-check that container; size containers off the mark, not the lockup.
+
+  ⚠️ Every pixel figure above is Chromium with the playground's Outfit-600 wordmark and `--font-family-sans` subtext, and **none of it is pinned by a test** — the Logo tests assert stylesheet text, not geometry. Retuning `--font-size-*` or swapping the brand font invalidates these numbers with nothing going red. Treat them as the shape and rough scale of the change and re-measure in your own face before sizing anything to them.

package/docs/components/Masonry.md

@@ -0,0 +1,48 @@
+# `<Masonry>` — height-balanced masonry layout
+
+```tsx
+<Masonry minColumnWidth="220px" gap="md">
+  {photos.map((p) => (
+    <Image key={p.id} src={p.src} alt={p.alt} aspectRatio={p.ratio} />
+  ))}
+</Masonry>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `gap` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | no | `xs`(4) / `sm`(8) / `md`(12, default) / `lg`(16) / `xl`(24) / `2xl`(32). |
+| `children` | `ReactNode` | no |  |
+| `columns` | `number` | no | Fixed number of columns. Mutually exclusive with `minColumnWidth`. |
+| `minColumnWidth` | `string` | no | Min column width (px) for a responsive column count. Default `'240px'`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+Packs variable-height children into columns (greedy shortest-column-first) →
+left→right reading order, balanced heights. Measures on the client + rebalances
+via `ResizeObserver`.
+
+- `columns` **xor** `minColumnWidth` (px string, default `'240px'`) — pass one.
+
+**When NOT to use:** equal-height tiles → `<Grid>`; one column → `<Stack>`;
+wrapping rows → `<Cluster>`. Display content only — rebalancing remounts children.
+
+Fixed column count:
+
+```tsx
+<Masonry columns={3} gap="lg">
+  {notes.map((n) => (
+    <Card key={n.id}>{n.body}</Card>
+  ))}
+</Masonry>
+```
+
+Before measurement (and without JS) children render round-robin across the columns. Heights re-balance on container resize and when child content settles (e.g. images finish loading).
+
+- ❌ Interactive / stateful children (videos, focus-holding forms) — rebalancing re-parents items between columns, so React remounts them.
+- ❌ Expecting a single top-to-bottom reading column — items are distributed across columns; order is left→right by placement.

package/docs/components/MediaTile.md

@@ -0,0 +1,95 @@
+# `<MediaTile>` — media tile with caption, revealed actions and selection
+
+`<MediaTile media title meta actions>` — a full-bleed `media` body (an `<Image>` or a file-type icon) with a `title` + `meta` caption and `actions`. Drop one per tile in a `<Masonry>` / `<Grid>` for a gallery or file grid.
+
+- `captionPlacement="overlay"` (default) — caption in a top bar and `actions` in a bottom bar, each over a gradient scrim, **revealed on hover / keyboard focus**. Compact; the name is hidden at rest.
+- `captionPlacement="below"` — caption in a **solid, always-visible** bar under the media (normal text colour on the surface); `actions` move to a top-right chip over the media, still revealed per `revealOn`. Use for a record's Files tab, where file names must be readable.
+- `controls="bar"` (with `captionPlacement="below"` only; ignored in overlay placement) — the checkbox and `actions` share one **full-width solid bar** across the top of the media (divider below) instead of two chips. Reads better over busy or light images. When `selectable`, a click on the bar's free space toggles selection; nothing in the bar reaches the tile `onClick`.
+- `selectable` adds a checkbox top-left over the media (`selected` / `onSelectedChange` / `selectLabel`); a selected tile gets `data-selected` and an accent ring. Only the checkbox toggles selection — the tile's own `onClick` (e.g. open preview) keeps working. With `revealOn="focus"` an unselected checkbox is hidden and ignores the pointer until focus-within (mouse users can't reach it), so pair `selectable` with `'hover'` or `'visible'`.
+- Clicks and keydowns on the controls in `actions` and on the checkbox **don't bubble to the tile** (nor to React handlers on its ancestors or document/window bubble-phase listeners; native listeners on ancestors inside the React root and capture-phase listeners still see them), so a tile `onClick` / `onKeyDown` never fires from them. A click on the overlay bar's empty scrim still reaches the tile; the below-placement actions chip (padding and gaps included) does not.
+- A tile `onClick` is a **pointer convenience** — the tile `<div>` is not focusable. Keyboard users need an equivalent control: put a Preview button in `actions`.
+
+The reveal uses `opacity` (not `visibility`), so the controls stay tabbable — tabbing in fires `:focus-within` and reveals them. On touch devices (`(hover: none)`), `revealOn="hover"` behaves like `"visible"` in both placements, so touch users can reach the controls. A checked checkbox is always shown.
+
+```tsx
+// File grid: readable names, multi-select, actions top-right (incl. a keyboard-reachable Preview)
+const [selected, setSelected] = useState<Set<string>>(new Set());
+const anySelected = selected.size > 0;
+
+<Masonry minColumnWidth="180px" gap="sm">
+  {files.map((f) => (
+    <MediaTile
+      key={f.id}
+      captionPlacement="below"
+      media={
+        <Image
+          src={f.thumbUrl}
+          alt={f.name}
+          aspectRatio={1}
+          objectFit="cover"
+          objectPosition="top"
+        />
+      }
+      title={f.name}
+      meta={formatBytes(f.size)}
+      selectable
+      selected={selected.has(f.id)}
+      onSelectedChange={(next) => toggle(f.id, next)}
+      revealOn={anySelected ? 'visible' : 'hover'} // selection mode: show every checkbox
+      onClick={() => openPreview(f)} // pointer shortcut; the Preview action is the keyboard path
+      actions={
+        <>
+          <Button
+            iconOnly
+            variant="ghost"
+            size="sm"
+            aria-label={`Preview ${f.name}`}
+            onClick={() => openPreview(f)}
+          >
+            <Eye size={16} />
+          </Button>
+          <Button iconOnly variant="ghost" size="sm" aria-label={`Download ${f.name}`}>
+            <Download size={16} />
+          </Button>
+        </>
+      }
+    />
+  ))}
+</Masonry>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `media` | `ReactNode` | yes | Tile body — full-bleed media (an `<Image>`, or a centered file-type icon). |
+| `title` | `ReactNode` | no | Caption leading content (e.g. the file name). Truncates with an ellipsis. |
+| `meta` | `ReactNode` | no | Caption trailing content (e.g. the file size). Sits at the end of the row. |
+| `actions` | `ReactNode` | no | Tile controls (e.g. preview / download / delete icon buttons). With `captionPlacement="overlay"` they sit in a centered bottom bar over a scrim; with `"below"` they sit in a top-right cluster over the media. Either way they follow `revealOn`. Clicks and keydowns on the controls inside don't bubble to the tile (in overlay placement a click on the bar's empty scrim still does; the below-placement chip swallows all clicks), so a tile `onClick` (e.g. open preview) never fires from an action. |
+| `captionPlacement` | `'overlay' \| 'below'` | no | Where `title` + `meta` render. Default `'overlay'`. - `'overlay'` — a top bar over a gradient scrim on the media, revealed per `revealOn`. Compact, but the name is hidden at rest for mouse users. - `'below'` — a solid bar under the media in normal text colour, ALWAYS visible (not affected by `revealOn`). Use for file grids where the name must be readable. |
+| `controls` | `'chips' \| 'bar'` | no | How the selection checkbox and `actions` are presented. Default `'chips'`. Only applies with `captionPlacement="below"`; ignored in overlay placement. - `'chips'` — two floating surface chips: checkbox top-left, actions top-right. - `'bar'` — one full-width solid bar across the top of the media (divider below): checkbox at the start, actions at the end. Reads better over busy or light images. Follows `revealOn`; the whole bar stays shown while selected. When `selectable`, a click on the bar's free space toggles selection (a pointer shortcut; the checkbox remains the keyboard control). Clicks and keys anywhere in the bar never reach the tile `onClick` — the bar is a control region, not the media. |
+| `revealOn` | `'hover' \| 'focus' \| 'visible'` | no | When the overlay bars, `actions` and the selection checkbox reveal. Default `'hover'`. - `'hover'` — on pointer hover OR keyboard focus-within (focus always included for a11y). On touch devices (`(hover: none)`) it behaves like `'visible'`. - `'focus'` — only on focus-within (no mouse-over reveal). - `'visible'` — always shown. A checked selection checkbox is always shown regardless. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg'` | no | Corner rounding (clips the media). Default `'md'`. |
+| `selectable` | `boolean` | no | Render a selection checkbox top-left over the media. Default `false`. Only the checkbox toggles selection — clicking the tile does not (so a tile `onClick`, e.g. open preview, keeps working; checkbox clicks and keys don't bubble to it). With `revealOn="focus"` an unselected checkbox is hidden and ignores the pointer until focus-within, so mouse users can't reach it — pair `selectable` with `'hover'` or `'visible'`. |
+| `selected` | `boolean` | no | Controlled selected state (only used when `selectable`). Sets `data-selected` + an accent ring on the tile. Default `false`. |
+| `onSelectedChange` | `((next: boolean) => void)` | no | Fires with the next selected state when the checkbox is toggled. |
+| `selectLabel` | `string` | no | Accessible name of the selection checkbox, e.g. `"Select report.pdf"`. Defaults to the localized "Select {title}" when `title` is a string, else "Select". |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Bars/caption render only when they have content; icon-only `actions` need `aria-label`s.
+- MediaTile clips + overlays only — the `media` (`<Image aspectRatio>`) owns the media's aspect; `captionPlacement="below"` adds the caption bar's height under it.
+- `selectLabel` defaults to the localized "Select {title}" when `title` is a string, else "Select" — pass it when `title` is a node.
+
+**When NOT to use:** a plain, non-revealing image block — `<Image>` (optionally inside a `<Card>`); a colored icon chip — `<IconTile>`.
+
+- ❌ Putting the ONLY copy of critical info in a hover-revealed overlay bar — it is hidden at rest for mouse users. Use `captionPlacement="below"` (or `revealOn="visible"`).
+- ❌ A click-only tile (`onClick` with no matching action) — the tile isn't focusable, so keyboard users can't open it. Add a Preview (or Open) button to `actions`.
+- ❌ `selectable` with `revealOn="focus"` — the unselected checkbox can't be clicked with a mouse. Use `'hover'` or `'visible'`.
+- ❌ Making the tile itself toggle selection (`onClick={() => toggle(id)}`) — it steals the click from preview/open and is not announced as a checkbox. Use `selectable` + `onSelectedChange`; the tile click stays free for opening.
+- ❌ `controls="bar"` with `captionPlacement="overlay"` — it is ignored there (the overlay already has its own top and bottom bars). Pair it with `captionPlacement="below"`.
+- ❌ Leaving `revealOn="hover"` while some tiles are selected — mouse users can't see which other tiles are selectable. Switch the grid to `revealOn="visible"` once anything is selected.