@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/Textarea.md

@@ -0,0 +1,59 @@
+# `<Textarea>` — multi-line text
+
+The dumb multi-line companion to `<Input>`. Auto-grows by default; capped by `maxRows`. Optional character counter below the field.
+
+```tsx
+import { Textarea } from '@eocrm/design-system';
+
+// Default — auto-grows, 3 min rows, no max.
+<Textarea placeholder="Write something…" />
+
+// With counter (Twitter-style).
+<Textarea maxLength={140} defaultValue={value} onChange={(e) => setValue(e.target.value)} />
+
+// Fixed rows + drag-to-resize.
+<Textarea autoGrow={false} minRows={4} resize="vertical" />
+
+// Capped growth.
+<Textarea minRows={2} maxRows={8} />
+
+// Error state.
+<Textarea invalid aria-describedby="bio-error" />
+<p id="bio-error">Bio is required.</p>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `invalid` | `boolean` | no | Toggles the error visual (red border + danger focus ring) and sets `aria-invalid="true"`. Pair with a visible error message and an `aria-describedby` pointer at the message id. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Visual size. Defaults to `'md'`. Affects typography + padding only, not height — that comes from `minRows`. - `'sm'` — tighter padding + `--font-size-sm`. Used in dense forms. - `'md'` — default padding + `--font-size-md`. Most form contexts. - `'lg'` — same padding as md but `--font-size-lg`. Hero / focus textareas. Note: this collapses the native HTML `<textarea size>` attribute. Use `style={{ width }}` or a parent container for explicit width. |
+| `disableAutofill` | `boolean` | no | Block browser autofill AND password managers from offering to fill this textarea. Same heuristic as Input — see Input's JSDoc for the full set of opt-out attributes applied. Smart default: when omitted, block iff `autoComplete` is also omitted (or `'off'`). Explicit autocomplete hints opt back IN to autofill. Pass `true` to force-block, `false` to force-allow. |
+| `minRows` | `number` | no | Minimum visible rows. The textarea never renders shorter than this, regardless of content. Default: `3`. Also seeds the native `rows` attribute for SSR / no-JS rendering. |
+| `maxRows` | `number` | no | Maximum visible rows. Beyond this, content scrolls inside the field instead of expanding further. Only meaningful when `autoGrow` is true. Default: `undefined` (unbounded growth). |
+| `autoGrow` | `boolean` | no | When true, height adapts to content between `minRows` and `maxRows`. Default: `true`. When false, height locks at `minRows` and a scrollbar appears past it. |
+| `resize` | `'none' \| 'vertical' \| 'both'` | no | User-drag resize handle direction. Default: `'vertical'`. **Forced to `'none'`** when `autoGrow` is `true` — user-drag fights the auto-grow measurement and produces erratic behavior. To enable a resize handle, opt out of auto-grow with `autoGrow={false}`. |
+| `showCount` | `boolean` | no | Show the character counter (`${value.length}` or `${value.length} / ${maxLength}` when both are set). Default: `true` when `maxLength` is set, `false` otherwise. The counter renders as a `<span aria-live="polite" aria-atomic="true">` inside the wrapper, below the textarea. It updates on every input — works for both controlled and uncontrolled textareas. |
+| …native | | | plus native `<textarea>` attributes |
+
+<!-- props:end -->
+
+- **Smart autofill blocking** — same heuristic as Input.
+
+#### When NOT to use
+
+- ❌ Single-line input → `<Input>`.
+- ❌ Choosing from a fixed list → `<Select>`.
+- ❌ Rich text editing (bold, lists, mentions) → use `<RichTextEditor>` (toolbar, list toggles, mark shortcuts shipped).
+- ❌ Password fields → `<PasswordInput>`.
+
+#### Anti-patterns
+
+- ❌ Using `placeholder` as a label.
+- ❌ Setting both `autoGrow={true}` AND expecting `resize="vertical"` to render a drag handle — auto-grow wins; the handle is hidden.
+- ❌ Building your own character counter outside the component when `maxLength` / `showCount` would do it.
+
+Forwards the `<textarea>` (not the wrapper `<div>`) via ref. All native textarea attributes pass through except `size` (shadowed by the size prop) and `rows` (computed from `minRows`). It always renders a wrapper `<div>` so the optional counter has somewhere to live, unlike `<Input>`.

package/docs/components/Thread.md

@@ -0,0 +1,52 @@
+# `<Thread>` — nested-reply threading primitive
+
+`<Thread>` + `<Thread.Item node>` — a per-level left vertical rail connecting a parent comment to its nested replies, with the leading `node` slot (`<Avatar>` / icon / `<Dot>`) as the connection point. Replies are written as nested `<Thread.Item>`s; the recursive compound detects them (by identity) and indents under the rail. Depth-capped (`maxDepth`, default `4`) so deep threads stop marching right — past the cap, replies render flat at the same indent. `<Thread compact>` tightens the gaps for dense sidebars. The node centers on the first body line (the header) by default — pass `nodeAlign="top"` to top-align it instead. The rail terminates at the last reply's elbow, so it's surface-independent (no `--thread-surface` to keep in sync — works on tinted backgrounds). Semantic `<ul>`/`<li>`.
+
+```tsx
+<Thread maxDepth={4}>
+  <Thread.Item node={<Avatar name="Maya Chen" size="sm" />}>
+    <Stack gap="xs">
+      <Text size="sm">
+        <strong>Maya Chen</strong> · 2h ago
+      </Text>
+      <Text size="sm">Flagged the Acme renewal — usage dropped last quarter.</Text>
+    </Stack>
+    {/* replies = nested <Thread.Item>s; render them inline with the body */}
+    <Thread.Item node={<Avatar name="Tom Okafor" size="sm" />}>
+      <Text size="sm">Good catch — I'll set up a call.</Text>
+    </Thread.Item>
+  </Thread.Item>
+</Thread>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `ThreadProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `maxDepth` | `number` | no | Max visual nesting depth before replies render flat (no further indent). Once the cap is reached, deeper replies keep the same indent level so the thread stops marching right. Default `4`. |
+| `compact` | `boolean` | no | Tighter gaps for dense surfaces (sidebars, panels). The remapped tokens cascade to every nested item via CSS custom properties. Default `false`. |
+| `nodeAlign` | `'header' \| 'top'` | no | Where the leading `node` sits relative to the comment body. - `header` (default) — vertically centered on the **first body line** (the author / timestamp header), Jira/GitHub style, so a node taller than one line (e.g. a 24px `<Avatar>`) reads as centered against the name rather than top-aligned. Assumes the header line-box matches `--thread-header-line-height` (defaults to `<Text size="sm">`); override that token if your header line differs. Remove any old header `lineHeight` override (e.g. `var(--size-sm)`) — it now double-compensates. - `top` — top-aligned with the body (the node's top meets the body's top). Use when the node is about one line tall, or when you deliberately want top alignment. |
+| `children` | `ReactNode` | yes | The `<Thread.Item>`s. |
+| …native | | | plus native `<ul>` attributes |
+
+### `ThreadItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `node` | `ReactNode` | yes | The leading marker the rail connects to — an `<Avatar>`, icon, or `<Dot>`. Centered in its node box so the rail/elbow connectors meet it cleanly regardless of node content; by default the box centers on the first body line so a taller node aligns to the header (see `Thread`'s `nodeAlign`). It's a slot: there is no built-in avatar. Size the node to `--thread-node-size` (default `sm` / 24px) — e.g. `<Avatar size="sm">`; for a larger node, override `--thread-node-size` to match. |
+| `children` | `ReactNode` | yes | The comment body/actions, plus optional nested `<Thread.Item>` replies. Plain children render as the comment body; any direct `<Thread.Item>` child renders as a reply under the rail. |
+| …native | | | plus native `<li>` attributes |
+
+<!-- props:end -->
+
+- Plain children are the comment body; any direct `<Thread.Item>` child is a reply. Don't wrap a reply in a Fragment / wrapper — the sort matches `Thread.Item` by identity and it won't be detected.
+- **When NOT to use**: a flat activity feed with no parent/child nesting → `<Timeline>`; plain indentation with no connecting line → `<Indent>`.
+
+- Also not for a non-threaded vertical list (`<Stack>`) or an avatar + name/meta row (`<PersonDisplay>`; use it as an item's `node` / body, not instead of Thread).
+- ❌ Layout margins on items: spacing comes from `compact` / the row-gap token.

package/docs/components/TimeField.md

@@ -0,0 +1,70 @@
+# `<TimeField>` — standalone time-of-day input
+
+```tsx
+import { TimeField, type TimeValue } from '@eocrm/design-system';
+const [time, setTime] = useState<TimeValue | null>({ hours: 9, minutes: 0 });
+<TimeField value={time} onChange={setTime} aria-label="Start time" />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `TimeValue \| null` | yes | Selected time. `null` disables the field — the field cannot be activated until the parent supplies a value (used by the picker family to gate time selection on a date being chosen first). |
+| `onChange` | `(value: TimeValue) => void` | yes | Fired when the user commits a new time, either by typing + focus leaving the field (input, chevron or clock) / Enter, by clicking a row in the popover, or by clicking the Now button. The emitted value is always 24-hour internal regardless of display cycle. |
+| `step` | `number` | no | Minutes step. Default `15`. Controls the row count in the minutes column (e.g., 15 → 4 rows: 00/15/30/45) AND rounds typed input on commit. Set `1` to disable rounding. |
+| `hourCycle` | `'12' \| '24' \| 'auto'` | no | Display + parse cycle. - `'24'` — hour list 00–23, text input shows `HH:mm`, no AM/PM column. - `'12'` — hour list `12, 1, 2, …, 11` with an AM/PM column; text input shows `h:mm AM/PM`. - `'auto'` (default) — reads the active locale via `Intl.DateTimeFormat`; en-US → 12h, ru-RU → 24h. Typed input is lenient regardless of cycle — both 24h (`14:30`) and AM/PM (`2:30 PM`) shapes parse in either mode. |
+| `locale` | `string` | no | Locale override for `hourCycle='auto'` detection + text formatting. Defaults to the active `<LocaleProvider>` / browser locale. |
+| `hideNowButton` | `boolean` | no | Hide the "Now" quick-pick button in the popover footer. Default `false` (button shown). |
+| `aria-label` | `string` | no | Accessible label. Optional, but the control MUST be named: pass `aria-label` for a standalone TimeField, OR `aria-labelledby` when an external element (e.g. a `<Field>` label) names it. If both are given, `aria-labelledby` wins. |
+| `aria-labelledby` | `string` | no | Id(s) of element(s) that label this control — forwarded onto the inner `<input>` so a `<Field label>` names it. Takes precedence over `aria-label`. |
+| `aria-describedby` | `string` | no | Id(s) of element(s) that describe this control (e.g. a `<Field>` error or helper message) — forwarded onto the inner `<input>`, not the wrapper, so the description is announced when the input is focused. |
+| `disabled` | `boolean` | no | Disables the input + popover trigger. |
+| `invalid` | `boolean` | no | Toggles the error visual and sets `aria-invalid="true"` on the text input. Pair with a visible message and `aria-describedby` pointing at its id, exactly like `Input` / `Textarea` / `Select`. TimeField was the only form control in the library without this — 15 other controls set `aria-invalid` and it set nothing, so a TimeField inside a `<Field error=…>` looked wrong and announced valid. |
+| `required` | `boolean` | no | Sets `aria-required` on the text input. Field / SettingRow inject it; it used to fall through onto the wrapper div as a stray `required` attribute. |
+| `id` | `string` | no | Stable id for the input (so an external `<label htmlFor>` can target it). |
+| `className` | `string` | no | Additional className on the wrapper. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+```tsx
+// Forced 24-hour cycle, 30-minute step, no Now button.
+<TimeField
+  value={time}
+  onChange={setTime}
+  hourCycle="24"
+  step={30}
+  hideNowButton
+  aria-label="Departure time"
+/>
+```
+
+```tsx
+// Controlled inside a custom widget — the boundary conversion the picker
+// family uses internally.
+<TimeField
+  value={value ? { hours: value.getHours(), minutes: value.getMinutes() } : null}
+  onChange={(t) => setValue(combineDateAndTime(value, t.hours, t.minutes))}
+  step={15}
+  aria-label="Meeting time"
+  disabled={value == null}
+/>
+```
+
+- Bare text input + chevron toggle that opens a popover with hour / minute (and AM/PM in 12h mode) listbox columns plus a "Now" footer button. The wrapper IS the public element; the input has no border of its own — the wrapper renders the same chrome as `<Input>`.
+- Used internally by `<DatePicker>` / `<DateRangePicker>` / `<InlineDatePicker>` / `<InlineDateRangePicker>` when `granularity="minute"`; public for consumers who need a time input without a date.
+- Keyboard inside the popover (WAI-ARIA APG listbox pattern with roving tabIndex per column):
+  - `ArrowDown` on the input opens the popover and focuses the current hour row.
+  - `ArrowUp` / `ArrowDown` move within the focused column (no wrap).
+  - `ArrowLeft` / `ArrowRight` switch columns (Hours ↔ Minutes ↔ AM/PM in 12h mode).
+  - `Home` / `End` jump to first / last row in the focused column.
+  - `Enter` / `Space` commit the focused row.
+  - `Escape` closes and returns focus to the input.
+  - Tab from the last row reaches the Now button (it's outside the roving set, in natural Tab order).
+- Now button reads `new Date()`, applies `roundTimeToStep(step)`, fires `onChange`, and leaves the popover open so the user can fine-tune.
+- Re-exports of the underlying utils are available for consumers building their own time UI on top of TimeField: `resolveHourCycle`, `getLocaleHourCycle`, `roundTimeToStep`, types `TimeValue` / `HourCycle`.
+- **When NOT to use.** For datetime (date + time-of-day), use `<DatePicker>` / `<DateRangePicker>` / `<InlineDatePicker>` / `<InlineDateRangePicker>` with `granularity="minute"` — those wire the boundary `Date ↔ TimeValue` conversion plus the hidden form mirror for you. For elapsed-duration inputs (e.g. "3h 15m" meeting length), TimeField is wrong semantics — it clamps to 23:59 and parses AM/PM; use a numeric input pair. Time zones are out of scope — the value contract is wall-clock.

package/docs/components/Timeline.md

@@ -0,0 +1,57 @@
+# `<Timeline>` — vertical activity-feed primitive
+
+`<Timeline>` + `<Timeline.Item node>` — a connector line running between per-item `node` slots (`<Avatar>` / `<Dot>` / icon) with content to the right; the line stops at the last node. `<Timeline compact>` tightens it for a sidebar widget. Semantic `<ol>`/`<li>`. For a plain list use `<Stack>`.
+
+```tsx
+<Timeline>
+  {activities.map((a) => (
+    <Timeline.Item key={a.id} node={<Avatar name={a.actor} size="sm" />}>
+      <Text size="sm">
+        <strong>{a.actor}</strong> · {a.type} · {a.time}
+      </Text>
+      <Text size="sm" tone="muted">
+        {a.body}
+      </Text>
+    </Timeline.Item>
+  ))}
+</Timeline>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `TimelineProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `compact` | `boolean` | no | Tighter gutter, node box, and spacing for dense sidebar widgets. Default `false`. |
+| `children` | `ReactNode` | yes | `<Timeline.Item>`s. |
+| …native | | | plus native `<ol>` attributes |
+
+### `TimelineItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `node` | `ReactNode` | yes | The gutter node — an `<Avatar>`, `<Dot>`, icon, etc. Centered in a fixed node box so the connector aligns regardless of node content. |
+| `children` | `ReactNode` | yes | The item content (right of the node) — e.g. name·type·time, body, system text. |
+| …native | | | plus native `<li>` attributes |
+
+<!-- props:end -->
+
+- The last item's connector stops automatically (CSS `:last-child`); `compact` flows via CSS vars.
+
+```tsx
+// Compact sidebar widget with dot nodes:
+<Timeline compact>
+  <Timeline.Item node={<Dot tone="success" />}>
+    <Text size="sm">Renewal confirmed</Text>
+  </Timeline.Item>
+</Timeline>
+```
+
+- Not for a horizontal step indicator (Timeline is vertical).
+- ❌ Hand-rolling the connector line: it is built in.
+- ❌ Layout margins on items: spacing comes from `compact` / the row gap token.

package/docs/components/Title.md

@@ -0,0 +1,54 @@
+# `<Title>` — semantic heading
+
+```tsx
+<Title order={1}>Dashboard</Title>
+<Title order={2}>Recent activity</Title>
+<Title order={3} tone="muted">Filter group</Title>
+<Title order={2} size="lg">Visually compact h2</Title>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `order` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | yes | Heading semantic level (1–6). REQUIRED — forces the consumer to think about heading hierarchy on the page. Drives both the rendered element (`<h1>`–`<h6>`) and the default visual size (1→3xl, 2→2xl, 3→xl, 4→lg, 5→md, 6→sm). |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'` | no | Visual size override. Defaults to the size for the given `order`. Use this when the semantic level and the visual size need to diverge — e.g. a small section title that's still an `<h2>` for screen readers. |
+| `tone` | `'default' \| 'muted' \| 'subtle' \| 'accent' \| 'danger'` | no | Color tone. Defaults to `'default'` (full foreground). - `default` — `--color-fg` - `muted` — `--color-fg-muted` - `subtle` — **@deprecated: resolves to `muted`. Use `muted`.** In LIGHT theme the two neutrals were indistinguishable: OKLab ΔE 0.0261 when the deprecation was filed, 0.0365 after `--color-fg-muted` was retuned, against the 0.065 floor this library's perceptual gates use. In DARK they were 0.0707 apart — a real step — so **this deprecation changes dark-theme appearance**: `subtle` text in dark gets lighter, moving from `--color-fg-subtle` to `--color-fg-muted`. That is the accepted trade (a tier that exists in one theme only is not a tier), but it is a visual change, not the removal of a duplicate. `--title-fg-subtle` now aliases `--title-fg-muted`, so nothing breaks at the type or build level; if you need the old dark value back, override `--title-fg-subtle`. - `accent` — `--color-accent` - `danger` — `--color-danger` |
+| `weight` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` | no | Font weight. Defaults to `'semibold'` (matches the most common heading weight across the existing mockups). |
+| `truncate` | `boolean` | no | Truncate the title to a single line with ellipsis. Useful inside narrow cards or grid cells. Defaults to `false`. The full text remains in the accessibility tree — screen readers read the entire string. Don't additionally add `aria-label` to "compensate" for the visual clip. |
+| `children` | `ReactNode` | yes | Title text content. |
+| …native | | | plus native `<h1–h6>` attributes |
+
+<!-- props:end -->
+
+- `order: 1 | 2 | 3 | 4 | 5 | 6` — required. Renders `<h1>` … `<h6>` AND drives the default visual size.
+- Default size map: `1→3xl`, `2→2xl`, `3→xl`, `4→lg`, `5→md`, `6→sm`. Override with `size` (same vocab: `xs | sm | md | lg | xl | 2xl | 3xl`).
+- **Use `<Title>` for every heading in your UI.** Raw `<h1>` / `<h2>` is forbidden.
+
+`size` decouples visual size from the semantic level (e.g. a nested section that needs a smaller-looking h2).
+
+```tsx
+// Heading + supporting paragraph in a Stack:
+<Stack gap="xs">
+  <Title order={1}>Dashboard</Title>
+  <Text size="md" tone="muted">
+    Pipeline summary for this week.
+  </Text>
+</Stack>
+```
+
+**When NOT to use**
+
+- Body text: use `<Text>`.
+- Inline emphasis: use `<strong>` / `<em>` / `<Text weight="semibold">`.
+- Monospaced identifiers: use `<Code>`.
+- Picking a font size without thinking about hierarchy: the required `order` prop forces the question of what level this heading is on the page.
+
+**Anti-patterns**
+
+- `<h2 className={styles.title}>`: use `<Title order={2}>`; consumer SCSS should never name a typography class.
+- `<Title order={1} size="xs">`: usually a sign the heading hierarchy is wrong. Bump the order up instead of shrinking a low-order heading.
+- Skipping heading levels (`order={1}` then `order={4}`) hurts screen-reader users; use sequential orders.

package/docs/components/ToastViewport.md

@@ -0,0 +1,61 @@
+# `<ToastViewport>` + `toast` — transient notifications
+
+Imperative singleton + one portal. Fire from anywhere; no provider, no hook.
+
+```tsx
+import { ToastViewport, toast } from '@eocrm/design-system';
+
+// Mount once at app root
+<ToastViewport position="bottom-right" />;
+
+// Fire from anywhere
+toast.success('Saved');
+toast.error('Request failed', { description: err.message });
+toast.success('Item deleted', { action: { label: 'Undo', onClick: restore } });
+
+// Async sugar
+toast.promise(api.upload(file), {
+  loading: 'Uploading…',
+  success: (r) => `Uploaded ${r.name}`,
+  error: (e) => `Failed: ${e.message}`,
+});
+
+// Update in place
+const id = toast.loading('Saving…');
+await api.save();
+toast.success('Saved', { id });
+```
+
+Reusing an `id` updates that toast in place. If it is still animating out
+(dismissed less than 250ms ago), it is shown again as a new toast with a fresh
+timer. `toast.update` and `toast.promise` never bring back a dismissed toast.
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | no | Default position for toasts that don't specify one. Default: 'bottom-right'. All 6 positions are supported; a per-call `position` is an escape hatch — a single global position is the recommended UX. |
+| `duration` | `number` | no | Default duration (ms) for toasts without explicit duration. Default: 4000. |
+| `maxVisible` | `number` | no | How many toasts are fully visible per position bucket. Default: 3. |
+| `gap` | `'sm' \| 'md'` | no | Spacing between stacked toasts. Default: 'sm' (8px). |
+| `expand` | `boolean` | no | false (default): peek-collapsed stack, hover to fan out. true: always fanned. |
+
+<!-- props:end -->
+
+- **One viewport.** Mount exactly one `<ToastViewport>` at the app root. A second one logs a dev-warning and renders null.
+- **Five tones.** `info`, `success`, `warning`, `error`, `loading`. `error` is `role="alert"` (assertive); the rest are `role="status"` (polite).
+- **Auto-dismiss defaults to 4000ms.** Per-call `duration` (ms or `'persistent'`). `loading` defaults to `'persistent'`.
+- **Pause on hover / focus / hidden tab.** Hovering the toast or tabbing into its action pauses the timer; document `visibilitychange` to `hidden` pauses all timers globally.
+
+#### When NOT to use
+
+- ❌ For form validation feedback under the field. That's inline error text, not a toast.
+- ❌ For destructive confirmations. Use `<ConfirmationPopover>` or `<Modal>` — the user needs an explicit yes/no decision, not a transient banner.
+- ❌ For long-form messages. Toasts are 1–2 lines. If you need more, link to a page from the description.
+- ❌ As a substitute for in-page progress UI. A toast can announce "Upload started" but the persistent progress bar belongs in the page.
+
+- Toasts fired before the viewport mounts sit in the store and render the moment it mounts. When a second viewport mounts, only the first (in mount order) renders and the next takes over if it unmounts.
+- The portal target is `document.body`, so toasts aren't constrained by any parent overflow / transform / contain context.

package/docs/components/Tooltip.md

@@ -0,0 +1,63 @@
+# `<Tooltip>` — small floating label on hover / keyboard focus
+
+```tsx
+<Tooltip content="Save the record (⌘S)">
+  <Button onClick={save}>Save</Button>
+</Tooltip>
+
+<Tooltip content="Filter">
+  <Button variant="ghost" aria-label="Filter">⏷</Button>
+</Tooltip>
+
+<Tooltip content={<>Save&nbsp;<kbd>⌘S</kbd></>}>
+  <Button>Save</Button>
+</Tooltip>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `content` | `ReactNode` | yes | Tooltip body. ReactNode so you can include inline `<kbd>` or icons. If `null`, `undefined`, or `""`, the trigger renders as-is with no listeners and no `aria-describedby` — useful for conditional UIs. |
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one React element that accepts a ref. Cloned to inject the tooltip's ref + listeners + aria. `<Button>` and raw `<button>` both qualify; a custom component without `forwardRef` does not. |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | no | Preferred side. Default `'top'`. Auto-flips on collision via Floating UI. |
+| `align` | `'start' \| 'center' \| 'end'` | no | Edge alignment. Default `'center'`. |
+| `sideOffset` | `number` | no | Gap in px between trigger and tooltip. Default `6` (room for the arrow). |
+| `delay` | `number` | no | Delay in ms before hover opens the tooltip. Default `400`. Keyboard focus is always immediate (a11y). Close is always immediate. |
+| `open` | `boolean` | no | Controlled open state. Provide alongside `onOpenChange` to drive open externally. Omit both to let Tooltip own its state (the common case). |
+| `onOpenChange` | `((open: boolean) => void)` | no | Fired whenever Tooltip wants to change open state. Required when `open` is provided. |
+| `defaultOpen` | `boolean` | no | Default open state for uncontrolled usage. Defaults to `false`. |
+
+<!-- props:end -->
+
+- Wrapper API: `<Tooltip content="…">` cloneElement's its single child to inject the ref, listeners (`pointerenter` / `pointerleave` / `focus` / `blur`), and `aria-describedby`. Child must accept a ref — `<Button>` qualifies, as does a raw `<button>`.
+- Trigger MUST already have its own accessible name (visible text or `aria-label`). Tooltip is _supplementary description_ via `aria-describedby` — never the label.
+- Dismissal: `pointerleave`, `blur`, document `pointerdown`, `Escape`. Tooltip never owns focus. On `Escape` (WCAG 1.4.13) the tooltip registers as a floating surface, so inside a `Modal`/`Drawer` the dismiss press closes only the tooltip — the host survives; the next `Escape` closes the host.
+- Touch devices: a tap toggles the tooltip on a **non-interactive** trigger (`Text`, `Badge`, `IconTile`, a focusable `span`); a tap elsewhere closes it. A tap on a button/link/form control — or on anything inside one, e.g. a Badge in a row link — performs the action and opens nothing, so don't put supplementary info you want reachable on touch behind an interactive trigger's tooltip; rely on its accessible name.
+- Opens with a short scale-fade (140 ms) from the trigger side. Closes instantly. Respects `prefers-reduced-motion: reduce`.
+- Z-layer `--z-tooltip: 1300` is above modal and toast, so tooltips inside any host UI remain visible.
+
+```tsx
+// Controlled open (rare — usually let Tooltip manage state):
+const [open, setOpen] = useState(false);
+<Tooltip content="…" open={open} onOpenChange={setOpen}>
+  <Button>Edit</Button>
+</Tooltip>;
+```
+
+Opens on hover (after `delay`) or immediately on keyboard focus, with a directional arrow. Hand-rolled on `@floating-ui/react-dom`.
+
+**When NOT to use**
+
+- Content the user must click to interact with: use `<Popover>`. Tooltips are not hoverable; moving the pointer into the tooltip body does not keep it open.
+- Form-value selection: use `<Select>`.
+- As the only source of essential information: tooltips are progressive enhancement. Make it visible in copy or, for icon buttons, in the trigger's `aria-label`.
+- Multi-paragraph content: that is Popover territory.
+
+**Anti-patterns**
+
+- `<Tooltip><Button disabled>…</Button></Tooltip>`: disabled buttons fire no pointerenter or focus events in any browser. To explain _why_ a button is disabled, render it with `aria-disabled="true"` and intercept its click, or wrap the disabled element in a `<span>` and pass the span as the Tooltip child.
+- A trigger child that doesn't accept a ref (`cloneElement` needs the ref contract).