@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/EntityChip.md

@@ -0,0 +1,102 @@
+# `<EntityChip>` — inline entity-link chip
+
+```tsx
+// Inline, inside a sentence — canonically a link to its entity:
+<Text>
+  Reassigned <EntityChip href="/contacts/12" icon={<User size={14} />} label="Priya Shah" /> to this deal.
+</Text>
+
+// href, prefix + status:
+<EntityChip
+  href="/tasks/5"
+  prefix="ENG-5"
+  label="Fix login bug"
+  status={{ label: 'In progress', category: 'in_progress' }}
+/>
+
+// RouterLink via `as`, or a status color override:
+import { Link as RouterLink } from 'react-router-dom';
+<EntityChip as={RouterLink} to="/deals/9" label="Acme Corp" status={{ label: 'At risk', color: 'amber' }} />
+
+// Chip fill override (categorical, independent of status):
+<EntityChip href="/deals/9" label="Acme Corp" color="violet" />
+
+// One-line list row: only the label ellipsizes; adornments inside the chip:
+<EntityChip
+  truncate
+  href="/tasks/5"
+  icon={<CheckSquare size={14} />}
+  prefix="ENG-5"
+  label="Fix the login bug that only happens on Safari"
+  status={{ label: 'In progress', category: 'in_progress' }}
+  trailing={<ArrowUp size={14} aria-label="High priority" />}
+/>
+
+// Segmented task chip — coloured `before`/`after` parts, capped label:
+<EntityChip
+  as={RouterLink} to="/tasks/ENG-15"
+  prefix="ENG-15" label="Fix the login bug on Safari" labelMaxWidth={40}
+  before={[{ kind: 'icon', icon: <Bug />, label: 'Bug', color: 'red' }]}
+  after={[
+    { kind: 'icon', icon: <Equal />, label: 'Normal priority', color: 'slate' },
+    { kind: 'text', text: 'Reported', color: 'amber' },
+  ]}
+/>
+
+// `labelWeight="semibold"` — a heavier key + title:
+<EntityChip href="/tasks/ENG-15" prefix="ENG-15" label="Fix the login bug on Safari" labelWeight="semibold" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | no | Leading icon — consumer passes the element (e.g. a lucide icon). Rendered aria-hidden. |
+| `label` | `ReactNode` | no | Entity name. Optional at the type level only to satisfy the polymorphic `forwardRef` generic (same workaround `<Rail.Item>` documents on its `children`); in practice every chip needs a label. |
+| `prefix` | `ReactNode` | no | Muted leading run before the name (e.g. task key `ENG-5`). |
+| `status` | `EntityChipStatus` | no | Inline workflow status `{ label, category?, color? }`, separated by a small dot and rendered in the status's own color. `category` (`to_do`/`in_progress`/`open`/`done`/`won`/`lost`) resolves a default palette color (same mapping as `<PillMenu>`); `color` overrides it. The dot takes the resolved color too. |
+| `color` | `PaletteColor` | no | Optional categorical palette color for the chip fill. When set, takes precedence over the default accent chip tokens: the chip fills with the matching `--color-palette-<name>-bg/-fg` pair (same contract as `Badge color` — picking a readable pair is the consumer's call). Omit for the default fill, which matches RichText's `@mention` styling (`--color-accent-bg-subtle` / `--color-accent`) so a chip and a rendered mention read as the same visual object. The `status` run keeps its own resolved color independent of this prop, and `unavailable` still mutes the label/status text over any `color`. |
+| `href` | `string` | no | Renders `as="a"` with this href when `as` is omitted. |
+| `loading` | `boolean` | no | Loading placeholder: icon slot + `…` body, aria-busy; the label stays in the DOM visually hidden so the chip keeps its accessible name. Purely visual — with a link target (`href`/`as`) the chip stays a live, keyboard-reachable link while loading. The state is announced: a localized word is rendered visually hidden, so a linked chip's name becomes "Appointment (loading)". `aria-busy` alone did not do this. It is a GLOBAL ARIA state, so unlike `aria-disabled` it is perfectly valid on the chip's role-less span and browsers do expose it — but no mainstream screen reader conveys `busy` as a state on a non-live element, and the ellipsis is `aria-hidden`. The label reached the user fine; no signal of the LOADING STATE did. Know the trade: the accessible name CHANGES when loading resolves — and by more than this word. The loading branch renders neither `prefix` nor `status` (nor `before`/`after` segments), so a chip with both goes from "Fix login bug (loading)" to "ENG-5 Fix login bug In progress". That is unavoidable when announcing a transient state through the name, and it is why this was initially left alone. Note it also means a consumer query like `getByRole('link', { name: 'Appointment' })` no longer matches a LOADING chip. Measured, the mutation itself is benign: Chromium keeps the SAME accessibility node across the transition (same backendNodeId) and focus survives, so nothing is torn down and rebuilt — the name and `busy` simply change on the existing object. The alternative — an `aria-live` region — has to be owned by the consumer, because only the consumer knows whether a given chip resolving is worth interrupting someone for. To take that route, override this word to `''` at your TOP-LEVEL provider: the override is global to a provider subtree (there is no per-chip opt-out), `I18nProvider` requires a `locale`, and a nested provider replaces rather than extends its parent — so wrapping a single chip would silently discard every other override you have set. |
+| `unavailable` | `boolean` | no | Entity missing/no access: muted styling. With a link target (`href`/`as`) the chip remains a real link — unavailable is a visual state, not a disabling one. Only a target-less chip (bare span) becomes non-interactive with aria-disabled. The state is also announced: a localized word is rendered visually hidden inside the chip. A linked chip's accessible name becomes "Appointment (unavailable)"; a target-less chip is `role=generic`, which has no accessible name at all, so the word is announced as part of the chip's text in reading order. Either way it reaches the user. That matters because the canonical use is to withhold the entity's name and show a TYPE word instead — without the state, a masked reference is indistinguishable from a real entity that happens to be called "Appointment". Colour alone cannot carry it, and `aria-disabled` does not either: browsers do expose it, but it carries no meaning on a non-widget role such as `generic`, so no assistive tech conveys it. `loading` is announced the same way — see that prop for why `aria-busy` alone was not enough, and for the name-mutation trade it carries. Do NOT put an `aria-label` on the chip. It replaces the whole name and takes the state word with it; the state lives in the chip's contents. Override the word via the i18n provider (`entityChip.unavailable`); it carries its own punctuation so a locale can choose different marks. |
+| `truncate` | `boolean` | no | Single-line mode for list rows. The chip is capped at its container's width (`max-width: 100%`, `min-width: 0`, so it also shrinks as a flex item) and only the `label` ellipsizes — `icon`, `prefix`, `status` and `trailing` keep their full size. Default `false`: the label wraps, which is right for a chip inside running text. The full label stays in the DOM, so the accessible name is unchanged. A clipped label shows its full text in a tooltip on hover or keyboard focus — don't add a `title`, which would give a double tooltip. |
+| `trailing` | `ReactNode` | no | Extra adornments inside the chip, after `status` (e.g. a priority icon or a status `<Badge>`), kept at full size under `truncate`. Not rendered while `loading` (same as `prefix`/`status`). Non-interactive content only: the chip is itself a link, so a button or link here is invalid nested interactive content. Its text JOINS the chip's accessible name ("ENG-5 Fix login bug High") — give a decorative icon `aria-hidden`, and a meaningful one a short text alternative. |
+| `before` | `readonly EntityChipSegment[]` | no | Coloured segments before the chip's core, in order (e.g. the task type). Any segment turns the chip segmented: one line, only the outer corners rounded, only the label shrinks (as with `truncate`). Every segment's text joins the accessible name ("Bug ENG-15 Fix login bug Normal Reported"). Not rendered while `loading` or `unavailable`. |
+| `after` | `readonly EntityChipSegment[]` | no | Coloured segments after the core, in order (e.g. priority, status). See `before`. |
+| `labelMaxWidth` | `number` | no | Caps the label's width, a positive number of `ch`; past it the label ellipsizes on one line (also on a chip without `truncate`). For chips in running text, where the container edge is a whole paragraph away. The full label stays in the DOM and the accessible name; a clipped label shows it in a tooltip on hover or keyboard focus. |
+| `labelEllipsis` | `'end' \| 'start'` | no | Which end of a clipped label is cut. Applies only where the label can clip at all (`truncate`, segments, or `labelMaxWidth`); ignored on a wrapping chip. - `'end'` (default) — `Fix the login bu…`. Right for titles, whose distinctive part is the start. - `'start'` — `…/pull/1116`. For labels whose distinctive part is the tail, e.g. a URL path under a host `prefix`. The text keeps its order; `prefix` and segments stay whole, and the tooltip still shows it all. |
+| `labelWeight` | `'medium' \| 'semibold'` | no | Font weight for `label`. `'medium'` (default) matches a plain chip's fixed weight and the RichText `@mention` — most chips should leave this unset. `'medium'` does NOT apply to `prefix`: `.prefix` carries no font-weight rule of its own and simply inherits (normal), so a default chip's key is lighter than its title. `'semibold'` is the one value that touches BOTH — it sets `prefix` AND `label` to the same heavier weight (a task-chip design that wants its key heavier along with its title). Use `'semibold'` for a design that explicitly wants that. Don't reach for a styled `<Text weight="semibold">` around `label` to get a heavier title instead (see the clipped-label tooltip bullet in `docs/components/EntityChip.md`) — it buys nothing: the clipped-label tooltip reads the label's own `textContent` and always renders it plain, in the tooltip's own color, regardless of what the label node carries. Only this prop changes the rendered weight. |
+| `as` | `ElementType` | no |  |
+| …native | | | plus native attributes of the `as` element (default `<a>`) |
+
+<!-- props:end -->
+
+- Polymorphic inline chip: optional `icon` (rendered `aria-hidden`), optional muted `prefix` (e.g. a task key), the `label`, and an optional colored `status`. All inline `<span>`s inside one root — safe to drop directly inside a `<p>`/`<Text>`.
+- **An EntityChip is always a link to its entity**: pass `href` (renders `<a href>`) or `as` (`RouterLink`, `'button'`, any component — same polymorphic contract as `<Link>`). The bare `<span>` form (no target) is for rare non-navigable contexts only.
+- Default chip fill matches RichText's `@mention` styling (`--color-accent-bg-subtle` / `--color-accent`) — a chip and a rendered mention read as the same visual object in both themes. `color?: PaletteColor` overrides the fill (same inline-injection contract as `Badge color`) — independent of `status`, which keeps its own resolved color. `unavailable` still mutes the label/status/dot over any `color`.
+- ⚠️ **On a chip with a link target, both state words change the accessible name**, so a name-exact query stops matching: `getByRole('link', { name: 'Appointment' })` misses a chip that is loading or unavailable. If your tests select chips by name over lists that render placeholders, use a regex or query before the state applies.
+- **`loading` is announced too.** Same mechanism, and `aria-busy` alone did not do it either — it is a _global_ ARIA state so it IS valid on the role-less span and browsers expose it, but no mainstream screen reader reliably conveys `busy` on a non-live element, and the `…` is `aria-hidden`. The label reached the user; the state did not. A linked chip's name becomes `"Appointment (loading)"`. **The trade:** the accessible name changes when loading resolves. Announcing a transient state through the name always costs that; the alternative is a consumer-owned `aria-live` region, since only the consumer knows whether a chip resolving is worth interrupting for. Override the word to `''` **at your top-level provider** if you'd rather handle it yourself — a nested `I18nProvider` replaces its parent rather than extending it, so wrapping a single chip would discard every other override you have set.
+- **`unavailable` is announced, not just muted.** A localized word is rendered visually hidden inside the chip. A **linked** chip's accessible name becomes `"Appointment (unavailable)"`; a **target-less** chip is `role=generic`, which has no accessible name at all, so the word is announced as part of the chip's text in reading order. Either way it reaches the user.
+- Why `aria-disabled` was not enough: browsers do expose it, but it carries no meaning on a non-widget role such as `generic`, so no assistive tech conveys it. This matters because the canonical use is to withhold the entity's name and show a TYPE word instead — without the state, a masked reference is indistinguishable from a real entity that happens to be called "Appointment".
+- ❌ Don't put an `aria-label` on the chip — it replaces the whole name and takes the state word with it. The state lives in the chip's contents. Override the word via `<I18nProvider overrides={{ entityChip: { unavailable: '…' } }}>` instead; it carries its own punctuation so a locale can pick different marks.
+- **`truncate`** — single-line mode for list rows: the chip caps at its container (`max-width: 100%`, `min-width: 0`) and only `label` ellipsizes; `icon`/`prefix`/`status`/`trailing` keep full size. The accessible name keeps the full label. Default wraps — right for chips in running text, so don't set `truncate` there.
+- **`trailing`** — adornments inside the chip after `status` (a priority icon, a `<Badge>`), full size under `truncate`, not rendered while `loading`. Its text JOINS the link's name (`aria-hidden` a decorative icon). ❌ Never interactive content — the chip is a link; row actions go beside it.
+- Hover affordance on link/button chips: the background deepens a step plus a brightness dip. Never a weight change, never an underline, even under aggressive consumer link CSS.
+- Chip text inherits the surrounding font size — inside a heading it renders at heading size, by design (that's what keeps the chip box symmetric around the local text in any context).
+- **Segments** (`before` / `after`): coloured parts butted against the chip — `{ kind: 'icon', icon, label, color?, size? }` (label = accessible name + tooltip) or `{ kind: 'text', text, color?, tooltip?, size? }`; `size` is in em of the chip text, at most 1 (larger is clamped, so a segment never makes the chip taller or knocks its text off the label's baseline); glyph default 0.85em, text default 0.9em. The whole chip stays one link; every segment joins its name. Any segment makes the chip one line (only the label shrinks) with only the outer corners rounded. Not rendered while `loading`/`unavailable`. `labelMaxWidth` (ch) caps the label in running text; a clipped label shows its full text in a tooltip on hover or keyboard focus. That text is always plain; a non-string `label` is read when the tooltip opens, so it can show old text if the label changes while the tooltip is open. `labelEllipsis="start"` cuts a clipped label from its START (`…/pull/1116`) for labels whose tail is the distinctive part, e.g. a URL path under a host `prefix`; default `'end'`. Ignored on a chip whose label can't clip.
+- **A text segment's text sits on the label's baseline, not centred**: the segment's own box keeps the chip's font-size/line-height (so its box and first-line baseline match the core exactly); the smaller `--entity-chip-segment-text-size` lives on an inner span instead, which then sits on that baseline through normal inline layout. Icon (glyph) segments stay vertically centred, as before — only text segments changed.
+- **The clipped-label tooltip is always plain text**: it reads the label element's own `textContent` when it opens, not the `label` node itself — so a styled `label` (e.g. a `<Text tone="accent">`) never leaks its color/weight into the tooltip. No prop controls this; it's automatic.
+- **`labelWeight`**: `'medium'` (default, matches a plain chip / the RichText `@mention`) applies to `label` only — `prefix` has no weight rule of its own and stays inherited (normal). `'semibold'` is the one value that also touches `prefix`, setting BOTH `prefix` and `label` together (a heavier key + title, e.g. a segmented task chip). Backed by a component token (`--entity-chip-label-font-weight-semibold`), not by wrapping `label` in a styled `<Text>` — see the anti-pattern below.
+- **When NOT to use**: plain status with no linked entity → `<Badge>`/`<PillMenu>`; standalone navigation with no icon/prefix/status chrome → `<Link>`; removable filter pills → `<FilterChip>`.
+- **Anti-pattern**: nesting a `<Badge>` inside another `<Badge>` to fake an entity-with-status chip — `EntityChip` replaces that composition. `status.color` and the chip's own `color` are `PaletteColor` names, never raw hex strings. Omitting a link target (`href`/`as`) is also an anti-pattern — an EntityChip should link to its entity. Nesting `<IconTile>`/`<Badge>` in `icon`/`trailing` to fake coloured parts is also an anti-pattern — use `before`/`after` segments instead. Wrapping `label` in a styled `<Text weight="semibold">` to get a heavier title is also an anti-pattern — use `labelWeight="semibold"`; it buys nothing anyway, since the clipped-label tooltip always renders the label's plain text regardless of how `label` is styled.
+- ❌ Block-level children (e.g. a `<div>`) inside `label` / `prefix` — the inline-safety contract requires span-only content.
+- ❌ An icon segment without a meaningful `label` — it is the segment's accessible name; a decorative glyph belongs in `icon`, not a segment.
+
+```tsx
+// Loading / unavailable — still live links with a target
+<EntityChip href="/contacts/7" label="Contact" loading />
+<EntityChip href="/contacts/9" label="Deleted contact" unavailable />
+```

package/docs/components/ErrorState.md

@@ -0,0 +1,72 @@
+# `<ErrorState>` — page-level status / result screen
+
+```tsx
+// 404 — neutral
+<ErrorState
+  icon={<Compass size={48} aria-hidden="true" />}
+  title="Page not found"
+  description="The page you're looking for doesn't exist or has been moved."
+  actions={<Button>Go to homepage</Button>}
+/>
+
+// Error-boundary fallback — danger tone → role="alert"
+<ErrorState
+  tone="danger"
+  icon={<TriangleAlert size={48} aria-hidden="true" />}
+  title="Something went wrong"
+  actions={<Button>Try again</Button>}
+  extra={<Text size="sm" tone="muted">Error ID: a1b2-c3d4</Text>}
+/>
+
+// Page-level loading → error transition. This Card intentionally owns the
+// existing page-level status surface and stays mounted across both states.
+<Card role="status" aria-busy={!failed}>
+  {failed ? (
+    <ErrorState
+      tone="danger"
+      role={undefined}
+      size="md"
+      headingLevel={2}
+      title="We couldn't load the account"
+      actions={<Button onClick={retry}>Try again</Button>}
+    />
+  ) : (
+    <Text>Loading account details…</Text>
+  )}
+</Card>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | no | Icon rendered above the title. Pass a lucide icon (sized by the consumer — lg=48, md=32, sm=24), custom SVG, or any ReactNode. The icon's color is set by `tone`; pass `aria-hidden="true"` on it when purely decorative. |
+| `title` | `ReactNode` | yes | Required title, rendered as a semantic heading (default `<h1>` — it's usually the page heading). Accepts ReactNode for inline emphasis. |
+| `description` | `ReactNode` | no | Optional description rendered below the title. |
+| `actions` | `ReactNode` | no | Optional action(s) below the description — a `<Button>` or a `<Cluster gap="sm">` of buttons. Keep to ONE primary action. |
+| `extra` | `ReactNode` | no | Optional supplemental content rendered below the actions — e.g. an `Error ID: …` line or a "view status" link. Reads as metadata, not primary copy. Distinct from `description`, which sits above the actions. |
+| `tone` | `'neutral' \| 'danger'` | no | Status tone. Defaults to `'neutral'`. - `'neutral'` — informational (404 / not-found). Icon uses `--color-fg-muted`. - `'danger'` — an error (500 / crash). Icon uses `--color-danger`, and the wrapper gets `role="alert"` so an error-boundary fallback announces on mount. Override the role by passing your own `role`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Visual size. Defaults to `'lg'` (full-page hero). Use `'sm'` / `'md'` when the state is embedded in a smaller surface. |
+| `align` | `'center' \| 'start'` | no | Horizontal alignment of the stacked content. Defaults to `'center'`. Use `'start'` in a tight column where centering looks stranded. |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | Heading level for `title`. Defaults to `1` (page-level). Lower it when the screen is nested under an existing heading. Values outside `1–6` clamp to `1`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- Page-level sibling of `<EmptyState>` — the component EmptyState's docs point to for "page-level 404 / 500" and danger-tinted error states. Use `<EmptyState>` for "nothing here" inside a surface; use `<Alert tone="error">` for an in-flow banner.
+- `tone="danger"` makes the wrapper `role="alert"` (announces the whole subtree assertively on mount — ideal for an error-boundary fallback). For a _standalone_ error page, pass `role={undefined}` so it isn't read as a wall of text on load. Override via `role`.
+- **Loading → error in an existing page-level surface:** the example's Card is intentionally the stable page-level transition surface, not a recommendation to nest ErrorState in arbitrary cards. Keep that one `Card role="status" aria-busy={!failed}` mounted, with either loading content or `<ErrorState role={undefined}>` inside it. A live region mounted together with the error has no mutation to announce, and a page-sized assertive alert is inappropriate for this update.
+- For `tone="neutral"`, the `<section>` is not a screen-reader landmark unless it has an accessible name — pass `aria-label` / `aria-labelledby` when it IS the page's primary region (typical for a full-page 404).
+- No automatic `aria-hidden` on the icon — pass `aria-hidden="true"` for a decorative icon. No i18n — all copy is consumer-supplied.
+- Not for a status the tone scale doesn't cover (warning / success) — extend the `ErrorStateTone` union rather than repurposing `danger`.
+- ❌ Multiple primary buttons — one clear primary; secondaries are `variant="secondary"` / `ghost`. ❌ A long sentence as `title` — it is the page heading, keep it short.
+
+```tsx
+// Centered inside a Screen (standalone page)
+<Screen backdrop="accent">
+  <ErrorState title="Page not found" actions={<Button>Go home</Button>} />
+</Screen>
+```

package/docs/components/Field.md

@@ -0,0 +1,91 @@
+# `<Field>` — labeled-control unit
+
+```tsx
+<Field label="Work email" error={errors.email} required>
+  <Input type="email" />
+</Field>
+
+// wrapped / native control → render-prop, spread `field`:
+<Field label="Email" error={errors.email}>
+  {(field) => <input type="email" {...field} />}
+</Field>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `FieldProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | no | Label text. Renders a `<label htmlFor>` (or, in `asGroup`, a `role="group"` caption). An empty or falsy value (e.g. `0`, `''`, `[]`, `<></>`) renders no label at all; see the anti-pattern below. |
+| `description` | `ReactNode` | no | Helper text below the control. Hidden while `error` is present. |
+| `error` | `ReactNode` | no | Error message. Replaces `description`, flips the control to `invalid`, and links it with `aria-describedby`. **Not announced, deliberately.** `aria-describedby` is read on FOCUS, so an error that appears after a submit reaches nobody unless focus moves into the field. Hard rule 10 permits chosen silence provided it is written down; this is that note. The alternative — a live region per Field — is worse in the common case: a validate-on-change form would announce on every keystroke, and a submit failing N fields would fire N announcements over each other. The right owner of that announcement is the FORM, which knows how many fields failed and when the user asked for the answer. So: announce a summary yourself on submit, and leave the per-field message to `aria-describedby` for when focus arrives. (example below) |
+| `required` | `boolean` | no | Marks the field required: shows `*` and injects `required` onto the control. |
+| `optional` | `boolean` | no | Marks the field optional: shows `(optional)`. Mutually exclusive with `required`. |
+| `orientation` | `'vertical' \| 'horizontal'` | no | Label placement. Default `'vertical'`. `'horizontal'` puts the label beside the control. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Label/message type scale. Default `'md'`. Size primarily scales the label; the help/error message uses a compact fixed scale (`md` and `lg` both render the message at `sm`). |
+| `id` | `string` | no | Explicit control id. Field owns the id by default (auto-generated) so the label always matches. |
+| `asGroup` | `boolean` | no | Group mode for radio/checkbox sets: label becomes a `role="group"` caption (no `htmlFor`). |
+| `children` | `FieldChild` | yes | A single control element (auto-wired) or a render-prop `(field) => ReactNode`. |
+| …native | | | plus native `<div>` attributes |
+
+**`error`** example:
+
+<!-- prettier-ignore -->
+```tsx
+<div role="status" aria-live="polite">
+  {submitted && errorCount > 0 ? `${errorCount} fields need attention` : ''}
+</div>
+```
+
+### `FieldRenderProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `aria-describedby` | `string \| undefined` | yes |  |
+| `aria-labelledby` | `string \| undefined` | yes | Id of the label element to name the control — set only when a label is rendered. |
+| `aria-invalid` | `boolean \| undefined` | yes |  |
+| `invalid` | `boolean` | yes |  |
+| `required` | `boolean` | yes |  |
+| `labelId` | `string` | yes | Id of the label/caption element — for manual `aria-labelledby` wiring. |
+
+<!-- props:end -->
+
+- Wraps ONE control with its label + help/error + required marker, and auto-wires
+  `id` / `aria-labelledby` / `aria-describedby` / `invalid` (controls map `invalid → aria-invalid`).
+- When a `label` is present, Field injects `aria-labelledby` onto the cloned child, so
+  composite controls that forward ARIA props (`Select`, `Slider`, `ColorPicker`,
+  `IconPicker`, `FileUpload`, `TimeField`) get an accessible name for free. The render-prop `field`
+  object also carries `aria-labelledby` for wrapped/nested DOM.
+  `optional` shows `(optional)`. `orientation="horizontal"` = label beside control.
+- Field owns the control `id` — to set one, use `<Field id>`, not the control.
+- Groups: `<Field asGroup>` around `<RadioGroup>` → label becomes a `role="group"` caption.
+- ❌ Don't wrap a single `<Checkbox>`/`<Switch>` (they self-label). ❌ No validation/state — pass `error` from your form layer.
+
+```tsx
+// Radio/checkbox group — label becomes a role="group" caption
+<Field asGroup label="Notify me" error={errors.notify}>
+  <RadioGroup name="notify">
+    <Radio value="all" label="All activity" />
+    <Radio value="mentions" label="Only mentions" />
+  </RadioGroup>
+</Field>
+```
+
+#### When NOT to use
+
+- A single `<Checkbox>` / `<Switch>` — they carry their own inline `label`; use the control's `label` prop instead of double-labeling.
+- Read-only key/value display — use `<DefinitionList>`.
+- Arranging multiple fields — that is `<FormRow>` / `<FormSection>` / `<Stack>`.
+
+#### Anti-patterns
+
+- ❌ Auto-wiring a raw native `<input>` and expecting `aria-invalid`: auto-clone injects the DS `invalid` prop. For a native element use the render-prop and spread `field` (it includes `aria-invalid`).
+- ❌ Passing both `required` and `optional`.
+- ⚠️ `label` / `description` / `error` treat `0`, `NaN`, `false`, `''`, an empty array and an empty fragment (`<></>`) as ABSENT. `error={errors.map(...)}` with no errors, `label={<></>}` or `description={[]}` render nothing — no `<label>`, no description, no error text, no `invalid` flip — so the control falls back to its own `aria-label` or ends up unnamed. A real but visually empty node (`label={<span />}`, `label="   "`) or an empty one-shot iterator (`Map.prototype.values()`, a generator) still counts as present. Pass `undefined` explicitly for "none" rather than a container that might be empty.
+- ⚠️ An absent `label` also removes the `required` / `optional` marker, since both live inside the `<label>`: `<Field label={0} required>` shows no `*`.

package/docs/components/FileUpload.md

@@ -0,0 +1,109 @@
+# `<FileUpload>` — controlled file picker with dropzone
+
+```tsx
+<FileUpload
+  files={files}                                  // controlled FileEntry[]
+  onFilesAdded={(files) => /* wrap with id + status: 'pending' */}
+  onFileRemove={(entry) => /* remove from state */}
+  onFileReject={(file, reason) => toast.error(`${file.name}: ${reason}`)}
+  multiple
+  accept=".csv,application/vnd.ms-excel"
+  maxSize={10 * 1024 * 1024}
+  maxFiles={5}
+  validator={(f) => f.name.includes(' ') ? 'No spaces in filenames' : null}
+  dropzoneHint="CSV or Excel, up to 10 MB"
+/>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | no | Placed on the hidden native `<input type="file">`, not the root — it is the only labelable element, so a `<label for>` (Field / SettingRow wire one) opens the file picker when clicked. A `role="button"` div is not labelable, so the id on the dropzone would make the label click a no-op. While the dropzone is hidden (single mode with a file) the id falls back to the root, so scroll-to-id / focus-first-invalid still find the field. |
+| `invalid` | `boolean` | no | Marks the dropzone `aria-invalid` for Field / SettingRow composition. Default: `false`. |
+| `required` | `boolean` | no | Consumed for Field / SettingRow composition (they render the visible required marker). Not forwarded: `role="button"` does not support `aria-required`, and native `required` on the hidden input would block form submission with an invisible bubble — your state owns the files. |
+| `files` | `FileEntry[]` | yes | Controlled file list. The component renders this; consumer owns the state. |
+| `onFilesAdded` | `(files: File[]) => void` | yes | Called when the user drops or picks new files AND those files pass validation. The component does NOT mutate state — consumer is responsible for adding the returned `File[]` to `files` (typically wrapped in `FileEntry` shape with new IDs). |
+| `onFileRemove` | `(entry: FileEntry) => void` | yes | Called when the user clicks the X on a file row. Consumer removes from `files`. |
+| `onFileReject` | `((file: File, reason: FileRejectReason, message?: string) => void)` | no | Called when a file fails validation. `reason` is one of `FileRejectReason`; `message` is the custom message from `validator` (only present when reason='custom'). Use for toasts or inline error rendering. |
+| `multiple` | `boolean` | no | Allow multi-file selection. Default `false`. In single mode (default), `files` should have at most 1 entry; the dropzone hides once a file is present and re-appears after removal. |
+| `accept` | `string` | no | Accepted file types — MIME types and/or extensions, comma-separated. Forwarded to the native `<input accept>` attribute AND used for the built-in `invalid-type` validation. Default: no filter. Examples: - `accept="image/*"` — any image - `accept=".csv,application/vnd.ms-excel"` — CSV or Excel - `accept="application/pdf,image/png,image/jpeg"` — explicit MIME list |
+| `maxSize` | `number` | no | Per-file size cap in bytes. Default: no limit. Files exceeding this fire `onFileReject` with reason `'too-large'`. |
+| `maxFiles` | `number` | no | Total file count cap. Only meaningful when `multiple=true`. Counts existing entries in `files` PLUS new files being added. Default: no limit. Excess files fire `onFileReject` with reason `'too-many'`. |
+| `validator` | `((file: File) => string \| null)` | no | Custom validation hook. Return `null` for valid; return a string error message for invalid (fires `onFileReject` with reason='custom', message= the returned string). Runs LAST in the validation chain (after type, size, count, duplicate checks). |
+| `disabled` | `boolean` | no | Disable the entire component. Dropzone shows muted, drag/click handlers are no-ops, remove buttons disabled. Default `false`. |
+| `dropzoneLabel` | `ReactNode` | no | Override the dropzone's main label. Default: the i18n value at `fileUpload.dragHint`. Pass a ReactNode for richer content (e.g. with a `<Code>` for accepted extensions). **A11y note:** when `dropzoneLabel` is a plain string, the component uses it as `aria-label` on the dropzone. When it's a ReactNode, the component falls back to the i18n value at `fileUpload.upload` and the rich content is visible-only. To give screen readers the equivalent text, pass `aria-label` via the spread (e.g. `aria-label="Upload CSV or Excel files"`). An EMPTY string counts as unset, not as an explicit blank — it drives both the visible label and the dropzone's `aria-label`, so an empty one left a `role="button"` with no accessible name. |
+| `dropzoneIcon` | `ReactNode` | no | Override the dropzone icon. Default: lucide `CloudUpload` at 32px. Pass an SVG ReactNode or another icon component instance. |
+| `dropzoneHint` | `ReactNode` | no | Optional secondary line under the main label, typically describing accepted formats / size limits. Renders muted at `--font-size-sm`. Default: undefined (no secondary text). |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Pure UI shell.** Consumer owns the `files: FileEntry[]` state and the network code. The component handles drag/drop + click + validation + per-row rendering ONLY.
+- **Inside `<Field>` / `<SettingRow>`:** the wired `id` goes on the hidden `<input type="file">` (the only labelable element), so clicking the row's label opens the picker; `invalid` marks the dropzone `aria-invalid`; `required` only drives the row's visible marker (a hidden native `required` would block submit invisibly — your state owns the files).
+- `FileEntry`: `{ id: string, file: File, status: 'pending' | 'uploading' | 'done' | 'error', progress?: number, error?: string }`. Consumer assigns `id` (typically `crypto.randomUUID()`); File has no stable identity in JS.
+- **Status drives the row:** `uploading` renders `<Progress size="sm" value={progress}>`; `error` renders the error string in danger color and tints the row border; `done` renders a green check icon; `pending` is neutral. The remove button (X) is always visible regardless of status.
+- **Validation pipeline** (per file, in order): type (`accept`) → size (`maxSize`) → count (`maxFiles`, multi mode only) → duplicate (name + size) → custom (`validator`). First failure fires `onFileReject(file, reason, message?)`; passing files batch into ONE `onFilesAdded(File[])` call.
+- **Single mode (default):** implicit count cap of 1. Dropzone HIDES once `files.length === 1` and re-appears after the user removes the file. Multi-file drops in single mode → first valid file accepted, rest rejected as `'too-many'`.
+- **Defensive guards.** `NaN`, `Infinity`, and `max <= 0` on the underlying `<Progress>` fall back to indeterminate — covers the file-upload race condition where `bytes_uploaded / total_bytes` produces NaN before the total is known.
+- **Drag and click both open the same hidden `<input type="file">`.** Drag is mouse-only; keyboard users use the dropzone's `role="button"` + Enter/Space to open the picker.
+
+#### `FileRejectReason`
+
+- `'invalid-type'` — didn't match `accept`
+- `'too-large'` — exceeded `maxSize`
+- `'too-many'` — would exceed `maxFiles` (or the implicit cap of 1 in single mode)
+- `'duplicate'` — same name + size as an existing entry
+- `'custom'` — `validator` returned a non-null string (message passed as 3rd arg to `onFileReject`)
+
+#### Hard rule
+
+- ❌ Hand-rolling a `<input type="file">` + dashed-border div per page. Use `<FileUpload>`.
+- ❌ Wiring upload progress with a custom bar — use the `progress` field on `FileEntry`, which renders via `<Progress>` automatically.
+- ❌ Storing the file list in the component (it has no internal state). Always pass `files` + the two callbacks.
+- ❌ Setting `multiple=true` and showing only one file slot via custom CSS. The component decides dropzone visibility from `multiple` + `files.length`; don't fight it.
+- ❌ Calling `onFilesAdded` from inside `onFileReject` (or vice versa) in an attempt to "auto-retry." Reject is terminal for that file; the user has to re-drop.
+
+#### Examples and limits
+
+```tsx
+// Single-file picker (controlled)
+function ProfileImage() {
+  const [files, setFiles] = useState<FileEntry[]>([]);
+  return (
+    <FileUpload
+      files={files}
+      accept="image/*"
+      maxSize={2 * 1024 * 1024}
+      onFilesAdded={(added) =>
+        setFiles(added.map((f) => ({ id: crypto.randomUUID(), file: f, status: 'pending' })))
+      }
+      onFileRemove={(entry) => setFiles((prev) => prev.filter((e) => e.id !== entry.id))}
+    />
+  );
+}
+
+// Status walkthrough — the consumer moves each entry pending → uploading → done / error
+const upload = async (entry: FileEntry) => {
+  setFiles((prev) =>
+    prev.map((e) => (e.id === entry.id ? { ...e, status: 'uploading', progress: 0 } : e)),
+  );
+  try {
+    await uploadToS3(entry.file, (pct) =>
+      setFiles((prev) => prev.map((e) => (e.id === entry.id ? { ...e, progress: pct } : e))),
+    );
+    setFiles((prev) =>
+      prev.map((e) => (e.id === entry.id ? { ...e, status: 'done', progress: 100 } : e)),
+    );
+  } catch (err) {
+    setFiles((prev) =>
+      prev.map((e) => (e.id === entry.id ? { ...e, status: 'error', error: String(err) } : e)),
+    );
+  }
+};
+```
+
+- When NOT to use: a hidden file-picker button with no dropzone (use `<Button>` + a raw `<input type="file" hidden>`); paste-from-clipboard image upload; directory upload (`webkitdirectory` is not exposed); image thumbnails of the picked files (generic file icons only); component-owned upload state.

package/docs/components/FilterChip.md

@@ -0,0 +1,88 @@
+# `<FilterChip>` — dismissible "active filter" pill
+
+```tsx
+<FilterChip onDismiss={() => removeFilter('event')}>
+  <FilterChip.Label>Event</FilterChip.Label>
+  <FilterChip.Value tone="info">auth.* (3)</FilterChip.Value>
+</FilterChip>
+
+// Value-only chip (no label slot):
+<FilterChip onDismiss={() => removeFilter('tenant')}>
+  <FilterChip.Value>beta</FilterChip.Value>
+</FilterChip>
+
+// Read-only chip (no dismiss button):
+<FilterChip>
+  <FilterChip.Label>Status</FilterChip.Label>
+  <FilterChip.Value>Active</FilterChip.Value>
+</FilterChip>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `FilterChipProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `onDismiss` | `(() => void)` | no | Dismiss callback. When provided, the chip renders a trailing `×` button wired to this handler; the chip itself does NOT animate or unmount — the consumer's state update must remove the chip. Omit the prop to render a read-only chip with no dismiss button. |
+| `dismissLabel` | `string` | no | Override the dismiss button's `aria-label`. Defaults to the i18n value at `filterChip.dismiss` (`'Remove filter'` in English) when omitted OR empty — an empty string is not an explicit name, so it takes the default too. Pass a contextual label (e.g., `'Remove Event: auth.* filter'`) when the chip's filter category isn't obvious from the surrounding screen-reader context. |
+| `onActivate` | `(() => void)` | no | Makes the chip BODY interactive: when provided, the Label/Value content is wrapped in a `<button>` that fires `onActivate` on click and Enter/Space (native button keyboard). Use for *editable* filters — e.g. a date-range chip whose body re-opens its range-picker. Wire it to a controlled `<Popover open onOpenChange>` to open an editor popover. The dismiss ✕ stays a separate button whose click stops propagation, so removing the filter never fires `onActivate` (and never bubbles to an ancestor click handler). Omit for a read-only chip (current behavior). Controlled-only: FilterChip does NOT consume `Popover.Trigger`'s injected ref/ARIA, so wrapping it in `<Popover.Trigger>` won't auto-wire it — drive the popover's `open` yourself from this callback (see the example above). |
+| `expanded` | `boolean` | no | Open state of the disclosure the body opens (e.g. the editor popover), surfaced as `aria-expanded` on the body button (which also carries `aria-haspopup="dialog"`). Only meaningful with `onActivate`. Omit if the body doesn't toggle a disclosure. |
+| `children` | `ReactNode` | yes | One or two `FilterChip.Label` / `FilterChip.Value` subcomponents. Use both for `Label: Value` chips; pass just a Value for chips where the category is implicit (e.g., a tenant slug). |
+| …native | | | plus native `<div>` attributes |
+
+### `FilterChipLabelProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | The category text — typically a noun describing the filter dimension (`Event`, `Tenant`, `Stage`, `Owner`). Rendered muted so the Value is the visual anchor. |
+| …native | | | plus native `<span>` attributes |
+
+### `FilterChipValueProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `color` | `PaletteColor` | no | Optional full `PaletteColor` (one of the 30 named categorical colors) for the leading dot. Use when the 6 semantic tones aren't enough to distinguish filter categories (e.g., per-tenant or per-tag color coding that matches an `OptionsPicker` group). Takes precedence over `tone` when both are set. Renders a bare `<Dot>` in that color. |
+| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'purple'` | no | Optional dot tone. When set, prefixes a 6px colored circle before the value text — use to distinguish filter categories that share a screen (e.g., event filters get a tone-matched dot, tenant filters get no dot). Reuses Badge's tone palette: `neutral`, `info`, `success`, `warning`, `danger`, `purple`. Omit for plain text values. For a richer categorical color, use `color` instead. |
+| `children` | `ReactNode` | yes | The value text — what the filter is actually filtering by (`auth.*`, `beta`, `Won`). Pair with an optional `tone` / `color` dot to categorize. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- Compound API: `<FilterChip>` root + optional `<FilterChip.Label>` and `<FilterChip.Value>` children.
+- **Use for active-filter pills, not tags / status badges.** If it's a status or category, use `<Badge>`. If it's a clickable filter trigger that navigates or runs an action, use `<Button>` or `<OptionsPicker.Trigger>`.
+- Root carries `role="group"` so screen readers announce the chip as one unit. A read-only chip's only interactive target is the dismiss ✕; an _editable_ chip adds a body button via `onActivate`.
+
+```tsx
+// Editable chip — body re-opens an editor popover; ✕ removes the filter
+const [open, setOpen] = useState(false);
+<Popover open={open} onOpenChange={setOpen}>
+  <Popover.Trigger>
+    <FilterChip onActivate={() => setOpen((o) => !o)} expanded={open} onDismiss={remove}>
+      <FilterChip.Label>Range</FilterChip.Label>
+      <FilterChip.Value>Jun 1 – Jul 31</FilterChip.Value>
+    </FilterChip>
+  </Popover.Trigger>
+  <Popover.Content maxWidth={520}>{/* range picker */}</Popover.Content>
+</Popover>;
+```
+
+```tsx
+// Mixed content — Value accepts any ReactNode
+<FilterChip.Value tone="success">
+  <Avatar size="2xs" name="Sarah" /> Sarah
+</FilterChip.Value>
+
+// Palette-color dot (matches an OptionsPicker group color)
+<FilterChip.Value color="violet">Design</FilterChip.Value>
+```
+
+- `<FilterChip.Label>` is the muted category lead-in (`Event`, `Tenant`, `Stage`); omit it for value-only chips where the category is implicit.
+- Not for tags on an entity (deal labels) — use `<Badge>`; tags don't carry a `Label: Value` shape.
+- ❌ Interactive children inside `<FilterChip.Label>` / `<FilterChip.Value>` — the dismiss button (and the `onActivate` body button) are the only interactive targets; nesting a Button breaks the `role="group"` composition and confuses screen readers.
+- ❌ Expecting the chip to animate out on `onDismiss` — the consumer's state update unmounts it; wrap it in your own transition if you need one.

package/docs/components/FlowCanvas.md

@@ -0,0 +1,108 @@
+# `<FlowCanvas>` — pan/zoom canvas for directed node-edge diagrams
+
+Pan/zoom canvas for directed node-edge diagrams (workflow builders). Events-only: you own
+`nodes`/`edges`; the canvas emits intents (`onNodeCreate`, `onNodeMove`, `onNodeOpen`,
+`onNodeDelete`, `onEdgeCreate`, `onEdgeOpen`, `onEdgeDelete`, `onEdgeReconnect`) and never
+mutates data. Nodes
+without `position` auto-layout left → right and stay draggable for the session. Nodes with an
+explicit `position` are pinned and don't affect the auto-layout of the others (nodes without a
+`position` are auto-laid-out). `arrangeNodes(nodes, edges)` (exported) re-flows the whole graph
+and returns the nodes with fresh positions — wire it to your own "Re-arrange" button. Selection is
+single (`selection`/`defaultSelection`/`onSelectionChange`); `readOnly` disables editing but
+keeps select/open. Validation of new connections via `isValidConnection` (default: no
+self-loops, no duplicate pairs). **Rewire an existing edge:** select it, then drag either
+endpoint handle onto another node (or press `R` / `Shift+R`) → `onEdgeReconnect(id, from, to)`
+(reuses `isValidConnection`; reverts on empty/invalid drop). `allowConnections={false}` disables
+all create + rewire while keeping node drag/move/delete/select. `confineNodesToView` clamps a
+dragged node to the visible canvas area. `renderNodeActions(id)` / `renderEdgeActions(id)` return
+a `ReactNode` floated as a toolbar on the selected node/edge, tracking it through pan/zoom (e.g.
+a delete icon-button, or one behind a `ConfirmationPopover`). The canvas fills its parent — give
+the wrapper a height. Full keyboard: arrows rove nodes, E cycles a node's edges, C connect mode,
+R / Shift+R rewire the selected edge's target / source, Shift+arrows nudge, +/−/0 zoom/fit,
+Ctrl+arrows pan, Delete deletes, Enter opens. Inside a `Modal`/`Drawer`, an armed connect gesture
+(and a `Sortable`/`DataTable` reorder drag — keyboard or pointer) is an Escape-consuming **mode**:
+the first Escape cancels the mode and the host survives that press; a mere selection does NOT hold
+the host (Escape closes the host, deselect is incidental). Pass `controls` (a
+`ReactNode`) to render your own buttons top-left; a built-in Maximize toggle (top-right / `F`
+key, Escape to restore) expands the canvas in place to fill the viewport. `maximizeControl={false}`
+hides the toggle if you drive `maximized` yourself. The canvas fits-to-content once on mount; to
+re-center afterward — on a maximize toggle, a viewport resize, or a programmatic re-arrange that
+moves every node — change the **`refitKey`** prop (any `string | number | boolean`): a new value
+re-runs the fit **without a remount**, preserving viewport/selection/focus. Don't force a re-fit
+with a changing React `key` — that remounts and drops focus to `<body>`. Bind `refitKey={maximized}`
+to re-fit on maximize enter/exit, or bump a counter after a re-arrange.
+
+```tsx
+const [nodes, setNodes] = useState<FlowCanvasNode[]>([
+  { id: 'open', label: 'Open', color: '#0052CC', adornment: <Badge tone="info">Initial</Badge> },
+  { id: 'done', label: 'Done', color: '#1F845A' },
+]);
+const [edges, setEdges] = useState<FlowCanvasEdge[]>([
+  { id: 't1', from: 'open', to: 'done', label: <Badge tone="purple">Guard</Badge> },
+]);
+
+<div style={{ height: 480 }}>
+  <FlowCanvas
+    nodes={nodes}
+    edges={edges}
+    controls={
+      <Button size="sm" onClick={addNode}>
+        Add node
+      </Button>
+    }
+    onEdgeCreate={(from, to) => createTransition(from, to)}
+    onNodeOpen={(id) => openStateModal(id)}
+    onNodeDelete={(id) => confirmDeleteState(id)}
+  />
+</div>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `nodes` | `FlowCanvasNode[]` | yes | Nodes to render. The canvas never mutates this array. |
+| `edges` | `FlowCanvasEdge[]` | yes | Directed edges between nodes. Edges referencing unknown ids are skipped (dev warning). |
+| `onNodeCreate` | `((position: FlowCanvasPoint) => void)` | no | Called when the user requests a node at a canvas point (double-click empty canvas). |
+| `onNodeMove` | `((id: string, position: FlowCanvasPoint) => void)` | no | Called when a node's position is committed (drag end, keyboard nudge). |
+| `onNodeOpen` | `((id: string) => void)` | no | Called when a node is opened (Enter/Space or double-click). |
+| `onNodeDelete` | `((id: string) => void)` | no | Called when deletion of the selected node is requested (Delete/Backspace). |
+| `onEdgeCreate` | `((from: string, to: string) => void)` | no | Called when the user draws or confirms a connection between two nodes. |
+| `onEdgeReconnect` | `((id: string, from: string, to: string) => void)` | no | Called when the user drags an existing edge's endpoint onto a different node, or confirms a keyboard rewire (`R` / `Shift+R`). `id` is the edge; `from`/`to` are its NEW endpoints. The canvas never mutates the edge — apply this to your state. Not fired on revert (empty-canvas drop, invalid target, or no change). Disabled by `readOnly` and `allowConnections={false}`. |
+| `onEdgeOpen` | `((id: string) => void)` | no | Called when an edge is opened (Enter/Space or double-click). |
+| `onEdgeDelete` | `((id: string) => void)` | no | Called when deletion of the selected edge is requested (Delete/Backspace). |
+| `isValidConnection` | `((from: string, to: string) => boolean)` | no | Live validation while drawing a connection. Invalid targets can't be dropped on (pointer) and are skipped (keyboard). Default: `rejects self-loops and duplicate (from, to) pairs`. |
+| `selection` | `FlowCanvasSelection` | no | Controlled selection. Use with `onSelectionChange`. A selection whose id is not (or no longer) in `nodes`/`edges` acts as no selection — e.g. after applying a delete intent — until the id reappears in the graph. |
+| `defaultSelection` | `FlowCanvasSelection` | no | Initial selection when uncontrolled. Stale ids act as no selection. Default: `null`. |
+| `onSelectionChange` | `((selection: FlowCanvasSelection) => void)` | no | Fires whenever the selection changes (click, focus, Escape). |
+| `readOnly` | `boolean` | no | Render-only mode: create/move/connect/delete are disabled; selection and open still work. Default: `false`. |
+| `allowConnections` | `boolean` | no | When false, disables creating and rewiring connections — the node connect handle is hidden, pointer/keyboard connect (`C`, handle drag) and edge rewiring (`R`, endpoint drag) are inert. Node drag/move/delete/selection still work. `readOnly` overrides this (it disables everything). Default: `true`. |
+| `confineNodesToView` | `boolean` | no | When true, a dragged node is clamped so its whole card stays within the currently-visible canvas area (accounting for pan/zoom). Applies to pointer drag, the committed `onNodeMove`, and Shift+Arrow nudges. Default: `false`. |
+| `renderNodeActions` | `((id: string) => ReactNode)` | no | Render a floating toolbar anchored to the top-right corner of the selected NODE. Called with the node id; return `null` to show nothing for that node. The toolbar is a screen-positioned overlay (a sibling of the transformed stage, so it is not scaled) that follows pan/zoom. Pressing it never starts a pan or clears the selection. Only rendered for the current single selection. Default: `none`. |
+| `renderEdgeActions` | `((id: string) => ReactNode)` | no | Render a floating toolbar anchored near the midpoint of the selected EDGE. Called with the edge id; return `null` to show nothing for that edge. Same screen-positioned, pan/zoom-following overlay as `renderNodeActions`; safe to host a `ConfirmationPopover` here. Default: `none`. |
+| `controls` | `ReactNode` | no | Consumer-rendered controls shown in a top-left toolbar overlay. Put design- system `<Button>`s here (e.g. an "Add node" button wired to your own state). Stays pinned when the canvas is maximized. Default: `none`. |
+| `maximizeControl` | `boolean` | no | Show the built-in maximize / restore toggle (top-right). Set false to drive maximize entirely via the `maximized` prop. Default: `true`. |
+| `maximized` | `boolean` | no | Controlled maximize state. Use with `onMaximizedChange`. |
+| `defaultMaximized` | `boolean` | no | Initial maximize state when uncontrolled. Default: `false`. |
+| `onMaximizedChange` | `((maximized: boolean) => void)` | no | Fires whenever maximize is toggled (button, `F` key, or Escape). |
+| `refitKey` | `string \| number \| boolean` | no | Re-fit signal. Whenever this value CHANGES, the canvas re-runs its fit-to-content — the same fit as the Fit control / `0` key — re-centering and re-zooming to frame all content. It does this WITHOUT remounting, so the viewport, selection, keyboard focus, and the built-in maximize focus management are all preserved (unlike forcing a re-fit with a changing React `key`, which remounts and drops focus to `<body>`). Bind it to whatever should trigger a re-center: `refitKey={maximized}` to re-fit on maximize enter/exit (the container resizes), or bump a counter after a programmatic re-arrange that moves every node. The FIRST value never fits on its own — the mount fit handles the first frame — so any initial value is safe. Default: `none`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+When NOT to use: >100-node graphs (no virtualization); list/column reordering (use
+Kanban/Sortable); undirected/free-form drawing; as the only editing surface for complex
+attributes (anchor your own modals via the open callbacks — keep a form-based fallback).
+
+```tsx
+// Read-only diagram (record page): no editing intents, still zoomable
+<FlowCanvas nodes={nodes} edges={edges} readOnly aria-label="Deal workflow" />
+```
+
+- Not for undirected / free-form drawing (mind maps, whiteboards): edges are directed with arrowheads and the interaction model assumes a digraph.
+- The inline surface is selection + spatial arrangement only; editors belong to you (anchor modals / popovers via the open callbacks).
+- ❌ Hiding primary, always-needed actions solely behind Maximize or the `controls` slot — that is canvas chrome, not a substitute for the page's own toolbar.
+- ❌ Relying on maximize inside an ancestor that creates a containing block via `transform` / `filter` / `perspective` / `will-change`: in-page maximize uses `position: fixed`, so it anchors to that ancestor instead of the viewport and won't fill the screen.