@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/Radio.md

@@ -0,0 +1,37 @@
+# `<Radio>` — single radio button
+
+```tsx
+<Radio name="plan" value="pro" checked={plan === 'pro'} onChange={setPlan} label="Pro" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | The value submitted when this radio is selected. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Ring diameter + label type scale. Defaults to `'md'`. - `'sm'` — 14px ring, font-size-sm label. - `'md'` — 16px ring, font-size-md label. - `'lg'` — 20px ring, font-size-lg label. Inside `<RadioGroup>`, the group's `size` becomes the default; explicit per-radio `size` still wins. |
+| `checked` | `boolean` | no | Controlled checked state. Inside `<RadioGroup>`, leave this unset — the group computes `checked` from its `value`. If you explicitly set `checked` on a Radio inside a group, your prop wins and the group's controlled invariant breaks (don't do this). |
+| `defaultChecked` | `boolean` | no | Initial checked state for uncontrolled standalone use. |
+| `label` | `ReactNode` | no | Label rendered next to the ring. The whole `<label>` is the click target. Omit for icon-only radios + pass `aria-label`. |
+| `invalid` | `boolean` | no | Toggles the error visual + `aria-invalid='true'`. Inside a `<RadioGroup>`, the group's `invalid` becomes the default for this radio — explicit per-child `invalid` (including `false`) still wins. |
+| `onChange` | `((value: string, event: ChangeEvent<HTMLInputElement, Element>) => void)` | no | Fires when the radio is selected. Receives the radio's `value` AND the native event. Inside a group, this runs FIRST, then the group's `onChange` fires. |
+| …native | | | plus native `<input>` attributes |
+
+<!-- props:end -->
+
+- Native `<input type='radio'>` is visually hidden but stays in tab order + AT tree — browser arrow-key navigation between same-`name` radios works for free.
+- **Prefer `<RadioGroup>`** for proper fieldset/legend a11y and centralized state. Standalone `<Radio>` is for embedding a single radio next to other controls.
+
+Inside a group (preferred): `<RadioGroup name="size" defaultValue="md" label="T-shirt size"><Radio value="sm" label="Small" />…</RadioGroup>`.
+
+**When NOT to use:** 10+ options — `<Select>`; multi-select — a set of `<Checkbox>`es; a single binary on/off — `<Switch>`.
+
+**Anti-patterns**
+
+- ❌ Standalone radios without a wrapping `<fieldset>` — fails AT grouping. Use `<RadioGroup>`.
+- ❌ Setting `checked` on a Radio inside a `<RadioGroup>` — the group's `value` already controls each child's checked state.
+- ❌ Omitting both `label` and `aria-label` — the radio is unlabelled to AT.
+- Inside a group, a Radio's `onChange` runs first, then the group's `onChange`.

package/docs/components/RadioGroup.md

@@ -0,0 +1,56 @@
+# `<RadioGroup>` — fieldset wrapper for related radios
+
+```tsx
+<RadioGroup name="size" defaultValue="md" label="T-shirt size">
+  <Radio value="sm" label="Small" />
+  <Radio value="md" label="Medium" />
+  <Radio value="lg" label="Large" />
+</RadioGroup>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes | Form `name` shared by all radio children. Required. |
+| `value` | `string` | no | Controlled selected value. Pair with `onChange`. |
+| `defaultValue` | `string` | no | Initial selected value for uncontrolled use. |
+| `onChange` | `((value: string, event: ChangeEvent<HTMLInputElement, Element>) => void)` | no | Fires when the user selects a different radio. Receives the new value AND the native event so consumers can read modifier keys, etc. |
+| `label` | `ReactNode` | no | Optional group label, rendered as `<legend>`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Default size for child radios. Per-child explicit `size` wins. Defaults to `'md'`. |
+| `orientation` | `'vertical' \| 'horizontal'` | no | Layout direction. `'vertical'` (default) / `'horizontal'`. |
+| `disabled` | `boolean` | no | Disable every child. Per-child explicit `disabled` wins. |
+| `invalid` | `boolean` | no | Apply the invalid visual to every child + set `aria-invalid` on the fieldset. |
+| `required` | `boolean` | no | Mark every child as required (HTML form validation). |
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<fieldset>` attributes |
+
+<!-- props:end -->
+
+- Renders `<fieldset>` + optional `<legend>` for AT grouping. Children should be `<Radio>`s.
+- `FormData.get(name)` returns the selected value on native `<form>` submit.
+- The group's `value` drives each child's `checked` — don't set `checked` per-child inside a group (the group already does it).
+- Per-child `onChange` fires BEFORE the group's `onChange` (both run on every selection — `preventDefault` does NOT gate the group's state update). Use per-child handlers for side-effects scoped to one option; the group's handler is the single source of truth for the selected value.
+
+```tsx
+// Controlled
+const [plan, setPlan] = useState('free');
+<RadioGroup name="plan" value={plan} onChange={setPlan} label="Plan">
+  <Radio value="free" label="Free" />
+  <Radio value="pro" label="Pro" />
+</RadioGroup>
+
+// Horizontal layout
+<RadioGroup name="orientation" defaultValue="left" orientation="horizontal">
+  <Radio value="left" label="Left" />
+  <Radio value="center" label="Center" />
+</RadioGroup>
+```
+
+**When NOT to use:** 10+ options — `<Select>`; multi-select — a list of `<Checkbox>`es (no group component yet).
+
+- ❌ Setting `checked` on the child `<Radio>`s — the group handles that.
+- ❌ Setting a per-radio `name` inside a group — overridden by the group's `name`.

package/docs/components/Rail.md

@@ -0,0 +1,191 @@
+# `<Rail>` — collapsible left-side navigation
+
+Vertical nav anchored to one side of a page. Switches between a wide labelled mode (240px) and a narrow icon-only mode (56px) via a CSS width transition. Sections of items, parent groups with subitems, and a hover-popover that surfaces a collapsed group's subitems without expanding the rail.
+
+```tsx
+import { Rail } from '@eocrm/design-system';
+import { NavLink } from 'react-router-dom';
+import { Home, Users, Settings } from 'lucide-react';
+
+<Rail defaultCollapsed={false} aria-label="Main navigation">
+  <Rail.Header>
+    <BrandLogo />
+  </Rail.Header>
+
+  <Rail.Section title="Main">
+    <Rail.Item icon={<Home />} as={NavLink} to="/" end>
+      Dashboard
+    </Rail.Item>
+    <Rail.Item icon={<Users />} as={NavLink} to="/contacts" badge="12">
+      Contacts
+    </Rail.Item>
+  </Rail.Section>
+
+  <Rail.Section title="Operations">
+    <Rail.Group icon={<Settings />} label="Settings">
+      <Rail.Item as={NavLink} to="/settings/general">
+        General
+      </Rail.Item>
+      <Rail.Item as={NavLink} to="/settings/security">
+        Security
+      </Rail.Item>
+    </Rail.Group>
+  </Rail.Section>
+
+  <Rail.Footer>
+    <Rail.CollapseToggle />
+  </Rail.Footer>
+</Rail>;
+```
+
+<!-- props:start -->
+
+## Props
+
+### `RailProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `collapsed` | `boolean` | no | Controlled collapsed flag. Provide alongside `onCollapsedChange` to drive the rail's narrow/wide state externally (e.g. persisted to localStorage or URL). Omit both `collapsed` and `defaultCollapsed` to let the rail stay expanded. |
+| `defaultCollapsed` | `boolean` | no | Initial collapsed state for the uncontrolled case. Has no effect when `collapsed` is provided. Defaults to `false` — the rail mounts expanded. |
+| `onCollapsedChange` | `((collapsed: boolean) => void)` | no | Fires whenever the rail toggles, both controlled and uncontrolled. Useful for persisting the state to localStorage or the URL. |
+| `collapseBelow` | `'sm' \| 'md' \| 'lg'` | no | Force the icon-only collapsed mode while the **viewport** is at or below a width threshold: `'sm'` 480px / `'md'` 640px / `'lg'` 768px. Omit for no responsive behavior (the default) — `collapsed` alone governs. Below the threshold the rail renders collapsed regardless of `collapsed` / `defaultCollapsed`; above it, the consumer's value governs again, untouched. It is a **presentation override, not a user choice**, so `onCollapsedChange` does NOT fire when the viewport crosses the threshold in either direction — a narrow window can't silently rewrite a persisted preference. `<Rail.CollapseToggle>` hides itself while the override is active, since it could not change anything. Unlike `<Grid collapseBelow>` / `<Split collapseBelow>`, which measure their own width with a container query, this measures the viewport: the rail's own width is exactly what collapsing changes, so a container query would be circular. Same token scale, different basis. ⚠️ **Your shell's column track must follow.** The override shrinks the rail but is invisible to the layout around it — a shell that sizes its rail track from its OWN `collapsed` state will keep a 240px track around a 56px rail and leave a dead gap on every screen. Key the track off the viewport or off the rail instead, both of which work precisely because the basis here is the viewport rather than a container: (example below) |
+| `aria-label` | `string` | no | Accessible label for the wrapping `<nav>` landmark. Defaults to `t('rail.navigation')` when omitted OR empty — an empty string is not an explicit name — so screen readers always announce a name for the region. Override when the page has multiple navigation rails. |
+| `children` | `ReactNode` | yes | Rail children — typically a sequence of `<Rail.Header>`, `<Rail.Section>`, `<Rail.Group>`, `<Rail.Spacer>`, `<Rail.Footer>`. Order matters: a leading `<Rail.Header>` is pinned above the scroll box, and the first `<Rail.Footer>` is the split point — everything before it goes in the scroll box, the Footer and anything after it stay outside and pinned to the bottom. A `<Rail.Spacer>` is not needed for that; use it to push a trailing *section* (settings, help) down inside the scrolling area. |
+| …native | | | plus native HTML attributes |
+
+**`collapseBelow`** example:
+
+<!-- prettier-ignore -->
+```scss
+// Either mirror the breakpoint: a (max-width: 768px) media query setting
+// .shell { grid-template-columns: 56px 1fr; }…
+// …or follow the rail's own state attribute, no breakpoint duplication:
+.shell:has(nav[data-collapsed]) { grid-template-columns: 56px 1fr; }
+```
+
+### `RailCollapseToggleProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `aria-label` | `string` | no | Override the auto-generated aria-label (defaults to `t('rail.expand')` / `t('rail.collapse')` depending on the current state, when omitted OR empty — an empty string is not an explicit name). |
+| …native | | | plus native `<button>` attributes |
+
+### `RailFooterProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| …native | | | plus native `<div>` attributes |
+
+### `RailGroupProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | yes | Required leading icon — the only thing visible when the rail is collapsed. Groups always have an icon; subitems don't need one. |
+| `label` | `string` | yes | Group label — visible next to the icon when the rail is expanded, and rendered as the flyout's header when collapsed. |
+| `open` | `boolean` | no | Controlled inline-expand state (only meaningful when the rail itself is expanded — collapsed-mode uses hover-driven popover state instead). Provide alongside `onOpenChange` to drive open state externally. |
+| `defaultOpen` | `boolean` | no | Initial open state for the uncontrolled case. Default `false`. |
+| `onOpenChange` | `((open: boolean) => void)` | no | Fires whenever the inline-expand toggles. |
+| `children` | `ReactNode` | yes | Subitems — typically a list of `<Rail.Item>` without icons. |
+| `as` | `ElementType` | no |  |
+| …native | | | plus native attributes of the `as` element (default `<div>`) |
+
+### `RailHeaderProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| …native | | | plus native `<div>` attributes |
+
+### `RailItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | no | Leading icon — required for top-level items (the only thing visible when the rail is collapsed); optional for items nested inside a `<Rail.Group>` (Jira renders subitems without icons). |
+| `badge` | `ReactNode` | no | Optional trailing badge — typically a `<Badge>` or a small numeric pill. Right-aligned when the rail is expanded; fades to invisible when collapsed (the badge content is announced by screen readers either way since it's still in the DOM). |
+| `children` | `ReactNode` | no | The label text — visible when expanded, used as the tooltip when collapsed. Optional at the type level only to satisfy the polymorphic `forwardRef` generic; in practice every item has a label. |
+| `as` | `ElementType` | no |  |
+| …native | | | plus native attributes of the `as` element (default `<a>`) |
+
+### `RailSectionProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | no | Section heading rendered in small-caps muted style above the section's items. Hidden when the rail is collapsed (a small visual gap remains between sections via the rail's `gap`). When provided, doubles as `aria-label` for the section's `role="group"` so screen readers can navigate by group. |
+| `children` | `ReactNode` | yes | Items and/or groups belonging to this section. |
+| …native | | | plus native `<div>` attributes |
+
+### `RailSpacerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Compound API** — `Rail.Header` / `Rail.Section` / `Rail.Item` / `Rail.Group` / `Rail.Spacer` / `Rail.Footer` / `Rail.CollapseToggle`.
+- **`Rail.Header` brand area (default)** — a brand block with a header→nav divider out of the box, sized to line up with `<TopBar>`: a **leading** `<Rail.Header>` is pinned above the scrolling item list and runs the **full rail width**, at least `--rail-header-height` tall (default `var(--topbar-height)`) with its content **vertically centred**, so in an `AppLayout` its divider continues the TopBar's bottom border as one line — expanded, collapsed, with `sidebarPinned`, and wherever `--topbar-height` is retuned (the defaults resolve on the header element, so a retune on a theme wrapper or the AppLayout carries through). Tokens: `--rail-header-height` (set `auto` for a content-height header), `--rail-header-padding` (default `var(--rail-header-divider-width) calc(var(--rail-padding-x) + var(--rail-item-padding-x)) 0` — the inline inset puts the brand mark on the same x as the item icons; the divider-width top inset centres the brand in the full bar height, window edge to the bottom of the divider, so a 32px mark and its wordmark land on whole pixels and stay level with each other) and `--rail-header-divider-width` (default `var(--border-width)`, color `--rail-border-color`). No prop and no raw CSS needed. For a bare header, override the padding/divider tokens to `0` and `--rail-header-height` to `auto` (otherwise it keeps the 56px floor). **Pinning needs `<Rail.Header>` as the rail's literal first child** (directly or inside a Fragment): Rail recognises it by element type, so a header placed later, or rendered from your own wrapper component (`<MyBrand/>` that returns a `<Rail.Header>`), stays inside the scroll box — it scrolls away, the divider stops short of the rail edges, and the brand sits 8px right of the icon column. Write `<Rail.Header><MyBrand/></Rail.Header>` instead. Children render inside an inner block box, so their own flow is unchanged: inline content (`<img/> Acme`) stays on one line, block children stack. When the rail is **collapsed** the header centers its content in the 56px track — render a mark-only brand there (read the state with `useRail()`). A brand too wide for the track is clipped; the centering is `safe`, so it aligns to the start edge in that case and you lose the trailing end rather than both sides. The header's **inline padding is zeroed** while collapsed — not just the default but whatever you set `--rail-header-padding` to (there is no collapsed-only token). _Migration:_ (a) the header no longer scrolls with the item list, and a tall header (org switcher, search) now permanently takes that height from the list; (b) every rail header is now at least `--topbar-height` (56px) tall, also without a TopBar (e.g. in AppLayout's overlay drawer) — set `--rail-header-height: auto` to get the old content height; (c) the rail's top/inline padding moved from the `<nav>` onto the scroll body and footer wrapper — `--rail-padding-x/y` still apply there, but no longer surround the header; (d) a custom `--rail-header-padding` written for the old in-padding header needs `--rail-padding-x` added to its inline value, and its block padding now shifts the centred brand rather than spacing it from the divider; (e) remove any app-side shim that sized the header to the top bar; (f) a header rendered through a wrapper component must become a literal `<Rail.Header>` (see above); (g) children now sit in an inner box, so styles that treated the header element itself as their layout container (a `className` with `display: flex; gap`, or a `.myHeader > img` selector) no longer reach them — put that layout on your own brand element inside the header.
+- **Layout-owning primitive (Hard rule 4 exception)** — like `<Modal>`, `<Drawer>`, `<Page>`, the rail owns its own width and height because that IS its job. Place the rail inside whatever container shape your page needs (sticky aside, fixed sidebar, in-flow column).
+- **Collapse state**: controlled (`collapsed` + `onCollapsedChange`) or uncontrolled (`defaultCollapsed`). The `<Rail.CollapseToggle>` button reads context and flips the state without prop drilling.
+- **`useRail()`** reports the EFFECTIVE `collapsed` plus `collapsedByViewport` (true while `collapseBelow` forces the collapse) for custom chrome that needs to tell the two apart.
+- ⚠️ **Make your shell's rail track follow the override.** It shrinks the rail but is invisible to the layout around it, so a shell sizing its rail column from its OWN `collapsed` state keeps a 240px track around a 56px rail — a dead gap on every screen. Key the track off the viewport (`@media (max-width: 768px) { .shell { grid-template-columns: 56px 1fr } }`) or off the rail itself (`.shell:has(nav[data-collapsed]) { grid-template-columns: 56px 1fr }`, no breakpoint duplication). Both work only because this basis is the viewport, not a container.
+- **`Rail.Item` is polymorphic** — `as={NavLink}` (or any router primitive) sets `aria-current="page"` on the rendered anchor; Rail's CSS applies the active accent via `[aria-current="page"]` and `:has([aria-current="page"])` selectors. No router dependency in the library.
+- **`Rail.Group`** — renders inline-expanding subitems when the rail is expanded, and a hover-popover (`right-start` placement, 80ms open delay, 200ms close grace) when collapsed — portaled to `document.body` at `--z-popover` and auto-elevating above Modal/Drawer like other floating surfaces. Auto-opens on mount when the group's own link or any subitem is the active route (one-shot, uncontrolled-only — a manual close sticks).
+- **`Rail.Group` can be a link AND a toggle** — pass `as` (same polymorphic contract as `Rail.Item`) and the row splits into two hit-targets: icon + label navigate and carry `aria-current="page"` (so the row highlights like any item), while a separate chevron `<button>` owns `aria-expanded` + `aria-controls` with an `Expand <label>` / `Collapse <label>` accessible name. Keyboard order is link, then chevron. **Omitting `as` is byte-for-byte today's toggle-only shape** (one `<button>` spanning the row) — the feature is purely additive. Note the spread target moves with `as`: without it the remaining props land on the wrapping `<div>` (unchanged); with it they land on the rendered link, since that is what `to` / `end` / `replace` are for — **except `className` and `ref`, which stay on the wrapper `<div>` in both shapes**. Your `onPointerEnter` / `onPointerLeave` / `onFocus` / `onBlur` / `onClick` are _composed_ with the group's own handlers (yours runs first) rather than replacing them: those five open the collapsed-mode flyout, and overriding them would leave the subitems unreachable while the rail is collapsed. Pass **`end`** if you don't want the group counted as current on child routes — `to="/deals"` without it also matches `/deals/01K7…`, so opening one record auto-opens the saved-view list. **Collapsed, a linkable group has no chevron** — the single 56px target navigates on click and opens the flyout on hover/focus, and the flyout's header is a link to the same destination so the parent page stays reachable from inside the panel.
+
+  ```tsx
+  <Rail.Group as={NavLink} to="/deals" icon={<Handshake />} label="Deals">
+    <Rail.Item as={NavLink} to="/deals?view=open">
+      My open USD
+    </Rail.Item>
+  </Rail.Group>
+  ```
+
+- **`Rail.Spacer`** — `flex-grow: 1` filler that pushes trailing _sections_ (Settings, Help) to the bottom of the scrolling body. Not needed to pin the footer.
+- **Scrolling** — everything before the first `Rail.Footer` renders in one scroll box; the Footer is extracted out of it and stays pinned on its own, no Spacer required. The box scrolls vertically only — the X axis is clipped, since the rail is fixed-width and labels are meant to clip as it collapses. **Collapsed, the scrollbar is hidden entirely** (`scrollbar-width: none`): a gutter is a quarter of the 56px rail's inner width and shifts every item pill off-center. Wheel/trackpad and scroll-into-view on Tab still scroll it; the bar returns when the rail expands.
+- **i18n**: `rail.expand` / `rail.collapse` (toggle aria-label), `rail.navigation` (default `<nav>` aria-label), `rail.expandGroup` / `rail.collapseGroup` (prefix for a linkable group's chevron, interpolated with the group label).
+
+#### When NOT to use
+
+- ❌ Top-bar / horizontal nav — use a `<Cluster>` + `<Link>` row.
+- ❌ A value picker (status, country) — use `<Select>`.
+- ❌ A focus-locked dialog navigation — use `<Modal>` / `<Drawer>`.
+
+#### Anti-patterns
+
+- ❌ Forking width via inline style — rebind the `--rail-width-*` tokens in a parent stylesheet.
+- ❌ Hand-rolling active-state styling. Set `aria-current="page"` on the rendered element (NavLink does this for you) and the CSS handles it.
+- ❌ Multi-level group nesting (groups inside groups). v1 supports one level only.
+- ❌ Adding a synthetic "All deals" first subitem so the parent list stays reachable — that's what `Rail.Group`'s `as` prop is for. Make the group itself the link.
+- ❌ Putting an icon-less top-level item directly inside a section — when the rail collapses there's nothing visible. Items without icons belong inside a `<Rail.Group>`.
+
+- **`Rail.Item`** defaults to `<a href>`. Expanded it shows icon + label + optional `badge` on one row; collapsed (top-level) it shows the icon only, wrapped in a `<Tooltip>` so the label stays discoverable (only when the children are a string and the item is a direct rail child — group subitems show their labels in the flyout). A `badge` fades as the rail collapses.
+- **`Rail.Section title="…"`** renders `<div role="group">` with the title as `aria-label`; visually the title is a small-caps muted line above the items, faded out (height 0, opacity 0) when collapsed.
+- **`Rail.CollapseToggle`** is a ghost icon-only button whose `aria-label` flips between expand / collapse; its chevron rotates 180° when collapsed so it always points outward. Drop it in `<Rail.Footer>` or anywhere inside the rail. `Rail.Footer` typically holds a user chip, theme switcher or the toggle.
+- **`Rail.Spacer`:** when the item list overflows, the body scrolls and the spacer collapses to nothing, so items after it scroll WITH the content; only `Rail.Footer` stays outside the scroll box. Use the Footer for anything that must stay visible on a tall scroll.
+- **Group auto-open and timing:** the active-route auto-open is one-shot; pass a controlled `open` for exact sync. Re-entering the trigger or the flyout cancels the pending close.
+
+Controlled, persisted to localStorage (add `collapseBelow="sm"` for a forced collapse on phone-width viewports):
+
+```tsx
+const [collapsed, setCollapsed] = useState(() => localStorage.getItem('rail') === '1');
+<Rail
+  collapsed={collapsed}
+  onCollapsedChange={(c) => {
+    setCollapsed(c);
+    localStorage.setItem('rail', c ? '1' : '0');
+  }}
+>
+  …
+</Rail>;
+```
+
+- ❌ Wrapping subcomponents in extra `<div>`s — the `[data-collapsed]` cascade is brittle to extra wrappers and the active-state CSS (`:has([aria-current="page"])`) won't reach where you expect.
+- ❌ Putting non-`<Rail.Item>` children inside a `<Rail.Group>` — subitems should match the item shape so the active-state cascade reaches them.

package/docs/components/RelativeDateInput.md

@@ -0,0 +1,114 @@
+# `<RelativeDateInput>` — editor for a relative date or date-range expression
+
+Edits one expression **string** (`today+7d`, `last:30d`, `this:quarter:to_date`) that the eocrm server resolves to real dates at use time: list filters, saved views, dashboard periods, automation conditions, custom-field defaults. It is controlled: `value` in, `onChange` out.
+
+```tsx
+import { useState } from 'react';
+import { Button, Cluster, Field, RelativeDateInput } from '@eocrm/design-system';
+
+// Point: anchor + signed offset, or an exact date ("Exact date" switch).
+const [due, setDue] = useState<string | null>('today+7d');
+<RelativeDateInput mode="point" value={due} onChange={setDue} aria-label="Due date" />;
+
+// Point on a datetime field: adds the Now anchor, hour/minute offsets and a minute-precision exact datetime.
+<RelativeDateInput
+  mode="point"
+  allowNow
+  value={due}
+  onChange={setDue}
+  aria-label="Created after"
+/>;
+
+// Range, with presets (toggle buttons; the one equal to `value` is pressed).
+const [period, setPeriod] = useState<string | null>('last:7d');
+<RelativeDateInput
+  mode="range"
+  value={period}
+  onChange={setPeriod}
+  presets={[
+    { label: 'Last 30 days', value: 'last:30d' },
+    { label: 'Last 7 days', value: 'last:7d' },
+    { label: 'This month', value: 'this:month' },
+    { label: 'Quarter to date', value: 'this:quarter:to_date' },
+  ]}
+  aria-label="Period"
+/>;
+
+// Inside a Field with an error. asGroup: Field is the group, its label names it (no
+// htmlFor onto a div) and the error describes it; Field injects `required`, and `invalid` only when it has an `error`.
+// Pass no aria-label here: unnamed, the control renders no group role of its own.
+<Field asGroup required label="Due date" error="Pick a due date">
+  <RelativeDateInput mode="point" value={due} onChange={setDue} />
+</Field>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `mode` | `'range' \| 'point'` | yes | What the expression describes. - `'point'` — one date: an anchor (today, now, start/end of a period) plus a signed offset, or an exact date. - `'range'` — a date range: last/next N units, a whole this/last/next period, or a period to date. |
+| `allowNow` | `boolean` | no | Datetime fields: offers the Now anchor with hour/minute offsets, and a minute-granular exact date (UTC `YYYY-MM-DDTHH:mm:ssZ`). Default `false`. |
+| `value` | `string \| null` | yes | The controlled expression (see the grammar in the docs), or `null` for none. `null` shows the defaults (`today` / `this:month`) without emitting them. A value that doesn't parse shows the defaults plus an "Unrecognised value" note. |
+| `onChange` | `(expr: string \| null) => void` | yes | Fires with the next canonical expression after a valid edit, and only when it differs from `value`. Invalid drafts (an out-of-range amount, an exact date not yet picked) never fire it. |
+| `presets` | `readonly RelativeDatePreset[]` | no | Quick-pick toggle buttons rendered above the controls. The one whose `value` equals the canonical form of `value` is pressed (`last:07d` presses `last:7d`). |
+| `disabled` | `boolean` | no | Disables every control, presets included. Default `false`. |
+| `invalid` | `boolean` | no | Error chrome on the controls (`aria-invalid`), e.g. from `<Field error>`. Default `false`. The Exact-date Switch is never marked invalid. |
+| `required` | `boolean` | no | Consumed for `<Field asGroup required>` composition, so Field can show its required marker. Adds no ARIA: `role="group"` does not support `aria-required` (ARIA 1.2), and the controls always show a value. Default `false`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+## How it behaves
+
+- **Point mode:** an anchor (Today, Now with `allowNow`, Start/End of this/last/next week/month/quarter/year), a sign, an amount, a unit, and an **Exact date** switch that swaps the relative controls for a `DatePicker`.
+- **Range mode:** a kind (**Past**, **Coming**, **Calendar period**, **Period to date**) followed by an amount + unit (Past / Coming) or a period (the rest). Whole periods read as composed labels such as "This week" and "Month to date".
+- **Only valid expressions are emitted.** An out-of-range or non-integer amount shows an inline error and does not call `onChange` until it is valid. `onChange` also does not fire when the edit would produce the current `value`.
+- **It never emits `null`.** `null` _in_ means "no value" and shows the defaults (`today` / `this:month`) without emitting them. To let users clear a filter, give them your own chip or reset button that sets your state to `null` (see the "Clearing" pattern below).
+- **An unrecognised incoming `value`** (one that does not parse in this `mode` / `allowNow`) shows the defaults plus an "Unrecognised value: …" note and emits nothing until the user edits.
+- **Presets** are toggle buttons (`aria-pressed`); choosing one emits its `value`. Their `label` is yours (translate it yourself). Clicking a pressed preset keeps it selected (radio-like; it never un-presses to `null`). A preset whose `value` does not parse in this `mode` / `allowNow` renders disabled, never emits, and logs a dev-mode `console.warn`.
+- **`invalid`** marks the selects, amount and date picker invalid. The Exact-date `Switch` is intentionally not marked: it is a mode toggle, not the erroneous value.
+- **Group role:** with `aria-label` or `aria-labelledby` the root is a named `role="group"`; without one (e.g. inside `<Field asGroup>`, which is the group) it has no role, so there is no nameless nested group. Outside a `Field`, always pass `aria-label` / `aria-labelledby`: an unnamed RelativeDateInput has no group semantics. The "Unrecognised value" note describes every control as well as a named root. `required` (injected by Field) is consumed for Field's marker and adds no ARIA, since `role="group"` does not support `aria-required`.
+- **Leaving Now** for another anchor resets the offset (unit to days, amount to 0) and emits the bare anchor, since `now-3h` has no day equivalent.
+- `allowNow` gates three things together: the `now` anchor, the `h` / `min` units (only on `now`), and a minute-precision exact datetime in UTC (`YYYY-MM-DDTHH:mm:ssZ`).
+
+```tsx
+// Clearing is the consumer's job: the control never emits null.
+<Cluster align="center">
+  <RelativeDateInput mode="range" value={period} onChange={setPeriod} aria-label="Period" />
+  {period !== null && (
+    <Button variant="ghost" onClick={() => setPeriod(null)}>
+      Clear
+    </Button>
+  )}
+</Cluster>
+```
+
+## Grammar
+
+The canonical strings the component reads and writes. Anything else does not parse.
+
+<!-- prettier-ignore -->
+| Mode | Expression | Meaning |
+|---|---|---|
+| point | `today` | Today |
+| point | `now` | Now (`allowNow` only) |
+| point | `start:{this\|last\|next}:{week\|month\|quarter\|year}` | Start of the period; `end:…` for the end |
+| point | anchor `{+\|-}{N}{unit}` | Offset, N 0–1000: `today+7d`, `now-30min`, `end:next:quarter+1d` |
+| point | `YYYY-MM-DD` | Exact date |
+| point | `YYYY-MM-DDTHH:mm:ssZ` | Exact UTC datetime (`allowNow` only) |
+| range | `last:{N}{d\|w\|m\|y}` / `next:{N}{d\|w\|m\|y}` | Rolling past / coming, N 1–1000: `last:30d` |
+| range | `{this\|last\|next}:{week\|month\|quarter\|year}` | Whole calendar period: `this:week` |
+| range | `this:{week\|month\|quarter\|year}:to_date` | Period to date: `this:month:to_date` |
+
+Units are `d` (days), `w` (weeks), `m` (months), `y` (years), `h` (hours), `min` (minutes). `h` and `min` are valid only on the `now` anchor. **These spellings must match the eocrm server**; the component and the server parse the same strings. Absolute values are not part of the range grammar.
+
+`parseRelativeDate(expr, { mode, allowNow })` returns a structured `RelativeDateValue`, or `null` if `expr` is not valid; `formatRelativeDate(value)` returns the canonical string. They round-trip every canonical expression.
+
+## When NOT to use
+
+- **Absolute-only dates.** If the user is picking a fixed calendar date or range and nothing relative, use `DatePicker` / `DateRangePicker` (or the inline variants).
+- **Displaying a resolved date.** This edits the expression; it does not show what it resolves to (that is the server's job).
+- **Custom anchors or business days.** Not supported.

package/docs/components/RichText.md

@@ -0,0 +1,44 @@
+# `<RichText>` — read-only rich-text renderer
+
+Renders a `RichDoc` (the in-house rich-text model) read-only: paragraphs, H1–H3, bullet/ordered lists, blockquotes, code blocks, and inline marks (bold/italic/underline/strike/code/link). No editor libraries. Build docs with the exported engine constructors/transforms.
+
+```tsx
+const doc = {
+  blocks: [
+    createBlock('heading', 'Notes', { level: 2 }),
+    createBlock('paragraph', 'See the docs.'),
+  ],
+};
+<RichText value={doc} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `RichDoc` | yes | The document to render. Build one with `emptyDoc()` / `createBlock()` or the transforms. |
+| `renderLink` | `RenderLink` | no | Substitute how a link renders. Called per link with `{ href, text }` and the default `<a>` node; return your own node (e.g. a task/member chip) or the `defaultNode` to keep the standard anchor. Render-time only — the document model is unchanged, so serialization still emits a plain link. Prose link styling (accent colour + underline) applies to BARE anchors only: an `<a>` you return with any `className` — including a DS `<Link>` — keeps its own decoration and colour entirely. |
+| `renderMention` | `RenderMention` | no | Substitute how an `@`-mention renders. Called per mention with `{ id, label }` and the default mention span; return your own node (e.g. an interactive member chip / popover trigger) or the `defaultNode` to keep the standard non-interactive span. Render-time only — the document model is unchanged, so serialization still emits the mention mark. Composes with `renderLink`. |
+| `imageMaxHeight` | `number` | no | Maximum DISPLAYED height of image attachments, in px. Default: the `--size-rich-text-image-max-height` token (480px). A taller image shrinks (width follows, aspect preserved) — render-time only; stored `width`/`height` are unchanged, so existing documents need no migration. There is no "off": pass a large value to effectively remove the cap. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+**`renderLink`** (optional) — substitute how a link renders. The consumer checks "is this URL in my space?" and returns its own node (e.g. a task/member chip) or the supplied `fallback` (the standard `<a>`). It's render-time only — the model and `toHtml`/`toMarkdown` still emit a plain link, so serialization is unchanged. Don't do heavy synchronous work or block on the network inside it; return a component that handles its own lookup/cache. The same resolver works in `<RichText>` (viewer) and `<RichTextEditor>` (where a substituted link becomes an atomic chip). Typing against a link's trailing edge produces UNLINKED text — the link is inherited only with the caret strictly inside it, so text typed after a chip is visible instead of disappearing into the link's text under the unchanged href.
+
+```tsx
+const renderLink: RenderLink = ({ href }, fallback) => {
+  const m = /^https?:\/\/app\.eocrm\/task\/(\d+)/i.exec(href);
+  return m ? <Badge tone="purple">#{m[1]}</Badge> : fallback;
+};
+<RichText value={doc} renderLink={renderLink} />;
+```
+
+**`renderMention`** (optional) — `(mention: { id, label }, defaultNode) => ReactNode` — same contract as `renderLink` but for `@`-mention marks (render an interactive member chip/popover trigger), or return `defaultNode` for the standard non-interactive mention span. Composes with `renderLink`. Render-time only — `toHtml`/`toMarkdown` and the model still emit the mention mark. Works in both `<RichText>` and `<RichTextEditor>` (where a substituted mention becomes an atomic chip).
+
+When NOT to use: plain text → `Text`. For editing → `<RichTextEditor>`. The model is immutable; render the doc returned by a transform, never mutate in place.
+
+- ❌ Hand-writing HTML to display rich content — feed a `RichDoc` to `<RichText>`.

package/docs/components/RichTextEditor.md

@@ -0,0 +1,112 @@
+# `<RichTextEditor>` — controlled rich-text editor (contentEditable)
+
+Controlled WYSIWYG over the in-house engine. `value: RichDoc` + `onChange: (doc) => void` (feed it back into `value`). Type to edit; ⌘/Ctrl+B/I/U and ⌘/Ctrl+⇧X toggle marks over a selection; Enter splits, Backspace/Delete merge.
+
+```tsx
+const [doc, setDoc] = useState(emptyDoc());
+// Plain editor (keyboard shortcuts only)
+<RichTextEditor value={doc} onChange={setDoc} placeholder="Write a note…" />;
+
+// With built-in formatting toolbar
+<RichTextEditor value={doc} onChange={setDoc} toolbar placeholder="Write a note…" />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `RichDoc` | yes | Controlled document. Render the doc returned by `onChange` back into `value` as-is, right away — a cloned/normalized copy reads as an outside replacement and resets undo history; one stored only after a later edit (debounced, or a deferred render the next keystroke beats) is treated as rejected. Defer expensive consumers (preview, save), not `value`. |
+| `invalid` | `boolean` | no | `aria-invalid` on the textbox. Field / SettingRow inject it. Default: `false`. |
+| `required` | `boolean` | no | `aria-required` on the textbox. Field / SettingRow inject it. Default: `false`. |
+| `onChange` | `(doc: RichDoc) => void` | yes | Fires with the new document after every edit. |
+| `readOnly` | `boolean` | no | Non-editable: renders the content read-only (prefer `<RichText>` for pure display). |
+| `placeholder` | `string` | no | Shown when the document is empty. |
+| `autoFocus` | `boolean` | no | Focus the editor on mount. |
+| `toolbar` | `false \| true \| 'auto'` | no | Render the built-in formatting toolbar above the editor — Undo/Redo buttons, mark toggle buttons (bold/italic/underline/strike), a block-type dropdown (paragraph/headings/quote/code), and bullet/numbered list toggles. The toolbar dispatches through the same commit path the keyboard uses and reflects the active marks + current block of the live selection. Default `false` (keyboard-only). When `readOnly`, the toolbar renders disabled. `'auto'` shows the toolbar only when the editor is **focused or non-empty**, and keeps it shown while the editor's own overlays (the link editor / mention menu) are open — so opening the link editor on a focused-but-empty composer doesn't collapse the bar. The editable is NOT remounted as the bar appears or hides (the bar toggles in a stable shell), so there's no focus/selection loss. Use it for a compact, focus-gated composer (e.g. a comment box) instead of hand-rolling the show-on-focus logic and working around overlay focus theft. |
+| `mentions` | `MentionsConfig` | no | Enable `@`-mention autocomplete. Supply `onQuery` to resolve candidates for the text typed after the trigger (default `@`); the editor renders a floating combobox and inserts a styled mention chip carrying the chosen item's `id`. Omit to disable mentions. See {@link MentionsConfig}. |
+| `autolink` | `boolean` | no | Turn typed and pasted URLs into links automatically. While typing, a URL is linked when you type a space after it; on paste, plain-text URLs are linked (a single bare URL pasted over a selection links the selection). Default `true`. Set `false` to disable both the type rule and paste autolinking (the ⌘/Ctrl+K link tool still works). The href is sanitized — only safe schemes (http/https/`www.`) become links. |
+| `renderLink` | `RenderLink` | no | Substitute how a link renders. Called per link with `{ href, text }` and the default `<a>`; return your own node (e.g. a task/member chip) or the `defaultNode` to keep the standard anchor. A custom node renders as a non-editable **atomic chip** — the caret steps over it and a single Backspace/ Delete removes the whole link. |
+| `renderMention` | `RenderMention` | no | Substitute how an `@`-mention renders. Called per mention with `{ id, label }` and the default mention span; return your own node (e.g. an interactive member chip / popover trigger) or the `defaultNode` to keep the standard non-interactive span. A custom node renders as a non-editable **atomic chip** — the caret steps over it as a single unit. Composes with `renderLink` (both usable together). |
+| `imageMaxHeight` | `number` | no | Maximum DISPLAYED height of image attachments, in px. Default: the `--size-rich-text-image-max-height` token (480px). A taller image shrinks (width follows, aspect preserved); the resize handle and width slider stop where the image hits the cap. Render-time only — stored `width`/`height` are unchanged. Pass the same value to the read-only `<RichText>` so both agree. |
+| `blockControls` | `boolean` | no | Show Notion-style per-block controls: a left gutter that appears on the hovered/focused block with an insert button (`＋`, adds an empty paragraph below) and a drag handle (`⠿`) that opens a block menu (Turn into ▸, Duplicate, Move up/down, Delete). Reordering is subtree-aware for nested lists. Keyboard: Shift+F10 / the ContextMenu key opens the focused block's menu; ⌘/Ctrl+⇧↑ / ⌘/Ctrl+⇧↓ move the block; ⌘/Ctrl+D duplicates. Default `false`. Ignored when `readOnly`. Independent of `toolbar`. |
+| `upload` | `UploadConfig` | no | Enable file upload: a toolbar button (when `toolbar`) and clipboard-file paste. `onUpload(file)` resolves with where the file landed; images render inline as a preview, other files as a download chip. Reject `onUpload` to show a retry/remove error; reject with `new UploadError(message)` to also show that (user-facing, localized) reason on the block — any other rejection shows only "Upload failed". `onUploadingChange` fires while any upload is in flight — wire it to your submit button's disabled state. Validation (size/type) belongs in `onUpload` (`accept` is only a native-picker hint and is bypassed by paste). Omit to disable. Ignored when `readOnly`. When `blockControls` is also on, a ready image attachment can be configured (alt text, alignment, replace, open/download) via the block menu's "Configure" item. The width slider appears only for an image that renders as a preview (a safe, fetchable src — an embed); an uploaded image whose object-URL src renders as a download chip isn't resizable here. Alignment + width round-trip through HTML but not Markdown. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+**`toolbar` prop** (`boolean | 'auto'`, default `false`): renders a formatting bar above the editor surface. `toolbar="auto"` shows the bar only when the editor is **focused or non-empty**, and keeps it shown while the editor's own overlays (link editor / mention menu) are open — so opening the link editor on a focused-but-empty composer doesn't collapse the bar. The editable is not remounted as the bar appears/hides (no focus/selection loss). Use `'auto'` for a compact, focus-gated composer (e.g. a comment box) instead of hand-rolling show-on-focus + overlay-focus handling. The toolbar contains:
+
+- **Mark buttons** — Bold, Italic, Underline, Strikethrough. Reflect `aria-pressed` based on the current selection (or pending marks at a collapsed caret). Clicking with a selection toggles the mark over it; clicking at a collapsed caret sets a "pending" mark applied to the next typed characters (then clears).
+- **Block-type dropdown** — Paragraph, Heading 1–3, Quote, Code block. Shows the current block type; mixed multi-block selections show "Mixed".
+- **List toggles** — Bullet list, Numbered list. Toggle between the list type and paragraph.
+- **Link button** — add/edit a link on the selection. Reflects `aria-pressed` when the caret is inside a link.
+- **Emoji insert** — opens a searchable `EmojiPickerPopover`; selecting an emoji inserts it at the caret.
+- **Color** — two separate pickers, **Text color** and **Highlight**, each its own toolbar button (and its own ⠿-menu submenu when `blockControls` is enabled). Each picker is a grid of small **named badges** (the Palette-demo chip look — subtle bg fill + strong fg text): the default brand colors first (gray + semantic red/green/amber/blue, backed by the `--color-fg-muted`/`--color-danger`/`--color-success`/`--color-warning`/`--color-accent` tokens), then the rest of the categorical palette (each palette extra uses its `-fg`/`-bg` token), led by a Default/clear badge. Applied to the selection from the toolbar, or to a whole block from the ⠿ menu. Colors round-trip through HTML and are dropped in Markdown.
+- **Undo / Redo buttons** — undo/redo the last change; disabled at the ends of the history.
+
+**List keys:**
+
+- `Enter` on an empty list item exits the list (converts to paragraph).
+- `Tab` / `Shift+Tab` indent and outdent list items (clamped at depth 0).
+
+**Pending marks:** toggling a mark at a collapsed caret (via toolbar or ⌘B/I/U/⌘⇧X shortcut) queues it; the next inserted text gets that mark applied, then the queue clears. Moving the caret discards pending marks (with or without a toolbar).
+
+**`blockControls` prop** (opt-in, default off): Notion-style per-block gutter — `＋` insert below, drag the gutter (the whole strip) to reorder with an in-place reflow (subtree-aware for nested lists) + a block menu (turn into / duplicate / move up·down / delete). Reorder/duplicate/delete are subtree-aware for nested lists (a list item carries its nested children); **turn-into acts on the single anchor block only** (idempotent — choosing the current type is a no-op). Keyboard: Shift+F10 opens the menu, ⌘/Ctrl+⇧↑·↓ move, ⌘/Ctrl+D duplicate. Independent of `toolbar`; ignored when `readOnly`. All ops route through `value`/`onChange` and are undoable.
+
+**`upload` prop** (opt-in): file upload via a toolbar button (when `toolbar`) + clipboard-file paste. `upload={{ onUpload, accept?, onUploadingChange? }}` — `onUpload(file)` resolves `{ url, name?, mime?, width?, height?, alt? }`; images render inline as a preview, other files as a download chip. Reject `onUpload` to show a retry/remove error; reject with `new UploadError(message)` (exported) to show that reason on the block — write it for end users, localized. Any other rejection shows only "Upload failed", so raw `Failed to fetch` / HTTP-client messages never leak. A failure is also announced to screen readers through a polite live region ("Upload failed: {file}. {reason}"), since it usually lands while the user is typing elsewhere; the read-only `<RichText>` shows a failed block's text without Retry/Remove. Wire `onUploadingChange(uploading)` to your submit button's disabled state. Validate size/type inside `onUpload` (the picker `accept` is a hint only; paste bypasses it). Uploaded files are void **attachment blocks** — `blockControls` can reorder/duplicate/delete them. With the caret on an attachment (e.g. after an image that ends the doc), typing or Enter continues in a new paragraph after it — even from a caret before the image, since the model has one position per attachment; Backspace from after it (or Delete from before it) removes it; Backspace from before it (or Delete from after it) only moves the caret into the neighboring block — unless that block is empty or another attachment, which is removed instead (the caret stays put). Stored doc JSON round-trips losslessly; HTML import maps `<img>` → an image attachment (Markdown image import is not supported). Ignored when `readOnly`. Ready image attachments are configurable via the block-menu's "Configure" item (requires `blockControls`): alt text, alignment, replace-in-place, open/download — plus a width slider **only** when the image renders as a preview (a safe, fetchable src — an embedded/imported image); an uploaded image whose object-URL src renders as a download chip isn't resizable here. A previewable image also gets a drag handle on its bottom-right corner (pointer only — keyboard/AT users use the Width slider); both the slider and the handle resize the image **live** and a whole drag is one undo step. Alignment + width persist in the doc and serialize to HTML; Markdown drops them. A newly uploaded/pasted image is laid out at its **perceived** size — natural pixels ÷ device pixel ratio, capped to the editor width — so a retina screenshot isn't inserted at 2× the size you saw; image **display height** is capped (`imageMaxHeight`, default 480px via `--size-rich-text-image-max-height`) — a tall photo shrinks with its aspect kept, the resize handle / width slider stop at the cap, and stored `width`/`height` are untouched (pass the same `imageMaxHeight` to the read-only `<RichText>`); return natural `width`/`height` from `onUpload` (or omit them and the editor measures the file). Persisted/imported image blocks (whose transient upload `status` is dropped on save) stay fully editable — the resize handle and the "Configure" popover treat "ready **or** status-absent" as settled, so editing an existing image comment works exactly like the brand-new composer.
+
+**Links:** select text and press ⌘/Ctrl+K (or the toolbar link button) to add or edit a link; with the caret inside a link the URL is pre-filled and a Remove button appears; with no selection the URL is inserted as linked text. Esc / click-outside cancels. Stored hrefs are sanitized at render time (`safeHref` blocks `javascript:`/`data:`/protocol-relative).
+
+**Autolink** (`autolink` prop, default `true`): typing a URL followed by a space, or pasting text containing a URL, turns it into a `link` mark automatically (`http(s)://…` or a bare `www.…` host; unsafe schemes are left as plain text). Set `autolink={false}` to disable both the type rule and paste autolinking.
+
+**`renderLink`** (optional, same `RenderLink` as `<RichText>`): preview links inline — the consumer checks "is this URL in my space?" and returns a chip or the `fallback` `<a>`. In the editor a substituted link becomes an **atomic chip**: the caret sits before/after it (arrow keys step over it, never inside) and Backspace deletes the whole chip in one step. It's render-time only — `toHtml`/`toMarkdown` and the model still emit a plain link, so serialization is unchanged. Don't do heavy synchronous work inside it.
+
+**`renderMention`** (optional, same `RenderMention` as `<RichText>`): `(mention: { id, label }, defaultNode) => ReactNode` — same contract as `renderLink` but for `@`-mention marks (render an interactive member chip/popover trigger); composes with `renderLink`. A substituted mention becomes an **atomic chip** the caret steps over as one unit. Render-time only — `toHtml`/`toMarkdown` and the model still emit the mention mark.
+
+```tsx
+const renderLink: RenderLink = ({ href }, fallback) => {
+  const m = /^https?:\/\/app\.eocrm\/task\/(\d+)/i.exec(href);
+  return m ? <Badge tone="purple">#{m[1]}</Badge> : fallback;
+};
+// autolink is on by default; type/paste a URL to link it
+<RichTextEditor value={doc} onChange={setDoc} toolbar renderLink={renderLink} />;
+```
+
+**Import:** `fromHtml(html)` and `fromMarkdown(md)` parse a string into a `RichDoc` (e.g. to seed `value` from stored/legacy content). Pasting rich HTML into the editor imports it as formatted content (parsed + sanitized). Markdown import is via `fromMarkdown` only — pasted plain text (incl. Markdown source) inserts literally, except that bare URLs in pasted plain text autolink (see Autolink above). Both `from*` functions require a DOM environment (`DOMParser`); Markdown has no underline syntax and images/tables aren't modeled.
+
+**Export:** `toHtml(doc)` and `toMarkdown(doc)` serialize a `RichDoc` back to a string (the inverse of `fromHtml`/`fromMarkdown`) — e.g. for storage, email bodies, or display outside the editor. `toHtml` is lossless (`fromHtml(toHtml(doc))` round-trips); `toMarkdown` drops underline (no Markdown syntax — use `toHtml` for full fidelity). Both escape output and run hrefs through `safeHref`.
+
+**Mentions:** pass `mentions={{ onQuery }}` (optional `trigger`, default `@`) to
+enable `@`-autocomplete. `onQuery(query)` returns `MentionItem[]` (`{ id, label,
+description?, avatarUrl? }`), sync or async. Picking a candidate inserts a chip
+carrying the `id`; chips survive `toHtml`/`fromHtml` round-trips but degrade to
+plain `@label` text in `toMarkdown`. Chips are inert references, not links.
+
+**Undo/redo:** built in — ⌘/Ctrl+Z undo, ⌘/Ctrl+Shift+Z (or ⌘/Ctrl+Y) redo, plus the toolbar Undo/Redo buttons. Typing coalesces into one step (short bursts), and replacing `value` from outside the editor clears the history.
+
+**Input rules:** typing a Markdown marker + space at the start of a paragraph auto-converts the block — `# `/`## `/`### ` → headings, `- `/`* `/`+ ` → bullet list, `1. ` → ordered list, `> ` → blockquote, a triple-backtick fence → code block. One Undo reverts the conversion.
+
+Read-only display of an existing document: `<RichTextEditor value={doc} onChange={() => {}} readOnly />` (or use `<RichText>`). `@`-mentions: `<RichTextEditor value={doc} onChange={setDoc} mentions={{ onQuery: (q) => searchUsers(q) }} />`.
+
+**Anti-patterns**
+
+- ❌ Treating it as uncontrolled — you MUST feed `onChange`'s doc back into `value`, or edits won't stick. Never mutate `value` in place.
+- ❌ Storing `onChange`'s doc later (debounced / `setTimeout` / after an `await`), or deferring `value` itself (`startTransition` / `useDeferredValue` on the editor's doc) — every edit builds on the current `value`, so the next keystroke can beat the late update and drop text. Store it right away; defer the expensive consumers (preview, autosave) instead. An edit whose doc hasn't arrived as `value` by the next edit, undo or upload settle is treated as rejected: its undo step is dropped and its caret isn't restored.
+- ❌ Cloning or normalizing the doc in `onChange` before storing it (`setDoc(structuredClone(d))`, a re-parse, an immutable-library copy) — the editor detects an outside `value` replacement by object identity, so a copy wipes undo history on every keystroke. Store the exact object `onChange` gave you; transform only on save.
+- ❌ Implementing your own undo/redo stack — history is tracked internally (⌘/Ctrl+Z, ⌘/Ctrl+⇧Z or ⌘/Ctrl+Y, toolbar buttons).
+- ❌ Hand-rolling a link UI or a toolbar by reaching into the DOM — press ⌘/Ctrl+K or pass `toolbar`; both route through the controlled `value`/`onChange` round-trip.
+- ❌ Pre-stripping pasted HTML to plain text — paste rich HTML directly; the editor parses it (sanitized) into the model. Seed stored content with `fromHtml` / `fromMarkdown`.
+- ❌ Hand-rolling HTML/Markdown from the model — use `toHtml` / `toMarkdown`.
+- ❌ Using mentions or `renderMention` for plain links — that is the link tool (⌘K) / `renderLink`. A mention chip is an inert reference carrying an `id`, not a navigable anchor; the two compose.
+- ❌ Returning thousands of unfiltered items from `onQuery` — filter server-side (or by `query`); the menu renders what you return.
+- ❌ Relying on Markdown to preserve mentions — `toMarkdown` is lossy (plain `@label`); use `toHtml`/`fromHtml` to round-trip the id.
+- ❌ Building a custom block drag/menu by reaching into the DOM — pass `blockControls`; insert/move/duplicate/delete route through `value`/`onChange` and are undoable.
+- ❌ Expecting Backspace to delete a whole block — it edits text; use the block menu's Delete (or select the block's text and delete).
+- ❌ Persisting or submitting the doc while an upload is in flight — gate your submit on `upload.onUploadingChange` (transient attachment blocks are skipped by `toHtml`/`toMarkdown`, but the model still carries them until they settle).
+- ❌ Relying on the picker `accept` for validation — it is only a hint and paste bypasses it; enforce size/type inside `onUpload` and reject to show an error.
+- ❌ Expecting image alignment/width to survive a Markdown round-trip — they serialize to HTML only; the stored RichDoc JSON is lossless.
+
+When NOT to use: read-only display → `<RichText>`. It's controlled — render `onChange`'s doc back into `value`, never mutate in place.