@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/Screen.md

@@ -0,0 +1,37 @@
+# `<Screen>` — full-bleed / centered screen layout
+
+```tsx
+// Standalone (full viewport) — auth / 404 / error
+<Screen
+  backdrop="accent"
+  header={<Link to="/">← Home</Link>}
+  footer={<Cluster gap="lg"><Link>Privacy</Link><Link>Terms</Link></Cluster>}
+>
+  <ErrorState title="Page not found" actions={<Button>Go home</Button>} />
+</Screen>
+
+// In-app variant — fills the shell content area instead of the viewport
+<Screen fill="block">
+  <ErrorState title="Page not found" />
+</Screen>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | The centered main content. |
+| `header` | `ReactNode` | no | Pinned-top slot — a back link, wordmark, etc. Omit for none. |
+| `footer` | `ReactNode` | no | Pinned-bottom slot — legal / footer links. Omit for none. |
+| `fill` | `'viewport' \| 'block'` | no | Screen height. Defaults to `'viewport'`. - `'viewport'` — `min-height: 100vh`; a true standalone page (login, standalone 404 / error). - `'block'` — fills its container instead of the viewport; use when the Screen is embedded inside the app shell's content area (the in-app 404 / error variants). |
+| `backdrop` | `'none' \| 'plain' \| 'accent' \| 'danger'` | no | Backdrop behind the content. Defaults to `'none'` (transparent — inherits the surface; use with `fill="block"` inside the shell). - `'plain'` — solid subtle surface. - `'accent'` — accent-tinted radial (the login backdrop). - `'danger'` — danger-tinted radial (standalone error screen). |
+| `align` | `'center' \| 'start'` | no | Vertical placement of the main content. Defaults to `'center'`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Page-root layout for **chromeless** screens that render outside the app shell (sign-in, 404, error, onboarding). Three slots: pinned `header`, centered `children` (main), pinned `footer`.
+- Layout-owning primitive (the `<Page>` / `<Rail>` exception to "no layout properties"). Don't nest inside `<Page>` or another `<Screen>`. For a normal in-shell page use `<Page>`; to center a small element use `<Cluster>` / `<Stack>`.

package/docs/components/ScrollArea.md

@@ -0,0 +1,39 @@
+# `<ScrollArea>` — height-capped vertical scroll region
+
+```tsx
+<ScrollArea maxHeight="md" aria-label="Notifications">
+  <Stack gap="xs">{rows}</Stack>
+</ScrollArea>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `maxHeight` | `ScrollAreaMaxHeight` | no | Caps the area's height; past it, the content scrolls vertically. - `'sm'` — 240px. A short list inside a form or a card. - `'md'` — 400px. A popover feed (notifications, activity). - `'lg'` — 560px. A tall panel body. - `number` — px, for a one-off (`maxHeight={320}`). Prefer the scale. - `string` — any CSS length (`'50vh'`). Omitted: no cap of its own. The area fills the height its parent gives it, which is right as the flexible child of a bounded flex column. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Pads its content by the focus-ring extent (4px) so focused children's rings aren't clipped.
+- **Keyboard:** named (`aria-label` / `aria-labelledby`), it is always a `role="region"` landmark. It is a tab stop (`tabIndex=0`) only while it overflows AND holds nothing focusable (a dev warning fires if that happens unnamed). A feed of links adds no tab stop. Name the ones worth landmark navigation (feeds, logs), not decorative ones.
+- **In a Popover** it's what caps the popover at the viewport: the popover becomes a flex column where only the ScrollArea shrinks, so a header above it stays put. Keep it a direct child of `Popover.Content`, or inside one wrapper element that is a direct child (`Content > Stack > ScrollArea`). That one wrapper must lay its children out as a column: a `<Stack>`, or a plain element (div/form/Card), which the popover lays out as a column. A row wrapper such as `<Cluster>` is not supported (the popover caps but the feed overflows it) — put the ScrollArea in a Stack instead. Deeper nesting leaves the popover uncapped.
+- Not for whole-page scroll (AppLayout owns it), a Card body (`<Card fill>` + `<Card.Body scroll>`), or horizontal scrolling (wider content is clipped — wrap long lines). Don't nest them.
+
+```tsx
+// Plain-text log: overflowing with nothing focusable, so it becomes a named tab stop by itself.
+<ScrollArea maxHeight="sm" aria-label="Import log">
+  <Stack gap="xs">{lines.map((line, i) => <Text key={i} size="sm">{line}</Text>)}</Stack>
+</ScrollArea>
+
+// One-off height — prefer the scale.
+<ScrollArea maxHeight={320} aria-label="Members">{members}</ScrollArea>
+```
+
+**Anti-patterns**
+
+- A plain `overflow: auto` div via `className` instead: it loses the keyboard tab stop, the popover viewport cap, and overscroll containment.
+- Plain-text content with no `aria-label` / `aria-labelledby`: it becomes an unnamed tab stop.

package/docs/components/Select.md

@@ -0,0 +1,131 @@
+# `<Select>` — value picker (single, multi, searchable, async, creatable)
+
+```tsx
+// Form field — single:
+<Select
+  options={statuses}
+  value={status}
+  onChange={(v) => setStatus(v as Status)}
+  placeholder="Pick a status"
+/>
+
+// Table filter — multi, summary:
+<Select
+  multiple
+  triggerDisplay="summary"
+  searchable
+  options={owners}
+  value={selectedOwners}
+  onChange={(v) => setSelectedOwners(v as string[])}
+  placeholder="Filter by owner"
+/>
+
+// Tag input — multi, chips, creatable:
+<Select
+  multiple
+  searchable
+  creatable
+  options={existingTags}
+  value={tags}
+  onChange={(v) => setTags(v as string[])}
+  onCreate={api.tags.create}
+  placeholder="Add tags…"
+/>
+
+// Async with custom row render:
+<Select
+  searchable
+  loadOptions={async (q, signal) => {
+    const users = await api.searchUsers(q, { signal });
+    return users.map((u) => ({ value: u.id, label: u.name, data: u }));
+  }}
+  renderOption={(opt) => (
+    <Cluster gap="sm">
+      <Avatar name={opt.label} src={opt.data?.avatarUrl} size="sm" />
+      <span>{opt.label}</span>
+    </Cluster>
+  )}
+  value={assigneeId}
+  onChange={(id) => setAssigneeId(id as string)}
+/>
+```
+
+**Option descriptions.** `SelectOption.description` renders as a muted second line under the label in the default row and becomes the option's accessible description (the name stays the label). It is also matched by the searchable filter. A `renderOption` replaces the default label/description layout.
+
+**Panel width.** The option panel is never narrower than the trigger and grows to fit its widest option, up to `--select-listbox-max-width` (20rem) and the viewport. Labels wrap only past that cap. While the panel is open it never shrinks, so filtering doesn't make it jump. A narrow trigger is fine: don't widen it just to stop options wrapping. Height caps at `--select-listbox-max-height` (320px) or the space available in the viewport. The panel is portalled to `<body>`, so override either token at `:root` or through `AppProvider`'s `tokens` / `darkTokens` (see `docs/setup.md`). Setting it on a wrapper around the Select does not reach the panel.
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | no | Placed on the combobox trigger (the `<button>` / `<input>`), not the wrapper div, so a `<label for>` — Field / SettingRow wire one — focuses the control when clicked. Default: a generated id. Target the wrapper by `className` or a `data-*` attribute, not `#id`. |
+| `options` | `SelectOptions<T>` | no | Sync options — flat list or list of groups. Ignored when `loadOptions` is provided (dev warning fires if both are non-empty). For grouped input, every element must carry an `options` field; mixing flat options with groups at the same level is not supported. |
+| `loadOptions` | `((query: string, signal: AbortSignal) => Promise<SelectOptions<T>>)` | no | Async fetcher that returns the options for a given query. When set, the Select switches to async mode: the local substring filter is bypassed (the server filters), loading/error/empty rows replace the listbox body, and `options` is ignored (with a dev warning). The `signal` argument is aborted whenever a newer query supersedes this one — wire it through to `fetch` to cancel in-flight requests. |
+| `loadOnOpen` | `boolean` | no | When `true` (default), defers the first `loadOptions` call until the user opens the listbox. Set to `false` to fetch eagerly on mount. |
+| `searchDebounceMs` | `number` | no | Debounce window (ms) between the last query keystroke and the next `loadOptions` call. Default `250`. |
+| `multiple` | `boolean` | no | Enables multi-select. `value` / `defaultValue` become `string[]` and `onChange` emits arrays. Picking a row toggles it in/out of the selection instead of replacing-and-closing. |
+| `triggerDisplay` | `'chips' \| 'summary'` | no | How the trigger renders the selected value(s) in multi mode. Ignored in single mode. See `SelectTriggerDisplay`. Defaults to `'chips'`. Use `'summary'` for table-filter UIs where chips would crowd the toolbar. |
+| `searchable` | `boolean` | no | Renders the trigger as a combobox text input with substring filtering over the (sync) options. In async mode the filter is delegated to the server. Required by `creatable`. |
+| `selectOnOpen` | `boolean` | no | When the searchable combobox opens, select the current text so the user can immediately type to replace it (type-to-search). Default `false`. Only affects the single searchable trigger. |
+| `creatable` | `boolean` | no | Adds a "+ Create <query>" row when the trimmed query has no exact label match. Activating it fires `onCreate(label)` and folds the new value into the selection. Requires `searchable` (throws in dev otherwise). |
+| `onCreate` | `((label: string) => void)` | no | Fires when the user activates the "+ Create" row (creatable mode). The trimmed query string is passed as `label`. After this fires, the Select also calls `onChange` with the new value: in single mode the value replaces the current selection and the listbox closes; in multi mode the value is appended to the current selection and the query is cleared. Consumers typically use this hook to persist the new option upstream (e.g. POST to a backend) and reconcile their `options` array. |
+| `value` | `string \| string[]` | no | Controlled selection. `string` in single mode, `string[]` in multi. Provide alongside `onChange` to drive the value externally. `''` is NOT reserved for "nothing selected". If your `options` contain an option whose `value` is `''` — the common "one sentinel row plus N catalog ids" shape — that option renders and selects like any other, and the trigger shows its label. "Nothing selected" means simply "the value matches no option", which is what an untouched Select resolves to when the list has no `''` row. |
+| `defaultValue` | `string \| string[]` | no | Initial selection for uncontrolled usage. `string` in single mode, `string[]` in multi. Ignored when `value` is provided. |
+| `onChange` | `((value: string \| string[], option: SelectOption<T> \| SelectOption<T>[] \| null) => void)` | no | Fires when the selection changes. The first argument is the next value (`string` in single mode, `string[]` in multi). The second argument is the matched `SelectOption` (single), the matched array (multi), or `null` when the selection clears in single mode. For creatable rows not present in `options`, a synthetic `{ value, label: value }` is supplied. The match is a lookup, not an emptiness test: an emitted `''` yields the matching `SelectOption` when your `options` contain a `value: ''` row, and `null` only when they don't (a genuine clear). |
+| `open` | `boolean` | no | Controlled open state. Pair with `onOpenChange`. Omit both to let Select own its open state (the common case). |
+| `defaultOpen` | `boolean` | no | Initial open state for uncontrolled usage. Defaults to `false`. |
+| `onOpenChange` | `((open: boolean) => void)` | no | Fires whenever Select wants to change open state. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Trigger height + type scale. See `SelectSize`. Defaults to `'md'`. |
+| `invalid` | `boolean` | no | Marks the trigger as invalid — applies the error border + sets `aria-invalid="true"`. Pair with an external error message linked via `aria-describedby`. |
+| `placeholder` | `string` | no | Placeholder shown when nothing is selected. In searchable mode, also the input's `placeholder` until the user types. |
+| `clearable` | `boolean` | no | Shows a `✕` button in the trigger that clears the selection. Opt-in: defaults to `false`. Always forced `false` when `disabled` or `readOnly`. "Clear" means "reset to the empty value" (`''` / `[]`), so the button only appears when the current value differs from that. A Select whose selected option IS `value: ''` is already at the cleared value and shows no ✕; a value matching no option (a stale id) does show one. |
+| `disabled` | `boolean` | no | Disables the trigger entirely — non-interactive, dimmed, focusable only via assistive tech. Hidden form inputs are also disabled. |
+| `readOnly` | `boolean` | no | Read-only — trigger is focusable but cannot open or change the selection. Useful for displaying a value inside a form that's not yet editable. |
+| `name` | `string` | no | Name attribute for native form submission. In multi mode, one hidden `<input>` per selected value is emitted (so `FormData.getAll(name)` returns the array). |
+| `required` | `boolean` | no | Marks the field as required. The trigger exposes `aria-required="true"` to assistive technology. Hidden inputs still serialize named values, but they do not participate in native constraint validation; validate the selection in your form layer. |
+| `form` | `string` | no | `form` attribute forwarded to the hidden `<input>` elements. |
+| `renderOption` | `((opt: SelectOption<T>, state: { active: boolean; selected: boolean; }) => ReactNode)` | no | Custom renderer for a row inside the listbox. Receives the option and its current `{ active, selected }` state (active = keyboard-focused row, selected = part of the current value). The returned node replaces the default label / description layout — chrome (padding, background, `aria-*`) stays. |
+| `renderValue` | `((opt: SelectOption<T>) => ReactNode)` | no | Custom renderer for the selected value inside the single-mode trigger. Ignored in multi mode (see `renderTag`). |
+| `renderTag` | `((opt: SelectOption<T>, remove: () => void) => ReactNode)` | no | Custom renderer for a chip inside the multi-mode `chips` trigger. Receives the option and a `remove` callback that deselects it. Ignored in single mode and in `triggerDisplay='summary'`. |
+| `renderEmpty` | `((query: string) => ReactNode)` | no | Custom empty-state renderer. Fires when the filtered listbox has no rows. Receives the current trimmed query for use in messages like "No matches for 'foo'". |
+| `renderLoading` | `(() => ReactNode)` | no | Custom loading-state renderer for async mode. |
+| `renderError` | `((err: Error, retry: () => void) => ReactNode)` | no | Custom error-state renderer for async mode. Receives the thrown `Error` and a `retry` callback that re-invokes `loadOptions` with the current query. |
+| `aria-label` | `string` | no | Accessible name for the trigger. Use this when a visible `<label>` is not present. Mutually exclusive with `aria-labelledby`. |
+| `aria-labelledby` | `string` | no | ID of an element that labels the trigger. Use when the label is a sibling node (e.g. a `<Field>` label). |
+| `aria-describedby` | `string` | no | ID of an element that describes the trigger — e.g. an error message or helper hint paired with `invalid`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- One generalist; the mode matrix is `multiple` × `triggerDisplay: 'chips' | 'summary'` × `searchable`.
+- **Async**: pass `loadOptions(query, signal)`; debounce and `AbortSignal` cancellation are built in — do NOT debounce externally.
+- **Tag input pattern** = `multiple + searchable + creatable + triggerDisplay='chips'`. There is no separate `<Tags>` component.
+- **`''` is a normal option value, not a reserved "unset" sentinel.** The "one sentinel row plus N catalog ids" shape works directly — no `"__default__"` workaround:
+
+  ```tsx
+  <Select
+    options={[
+      { value: '', label: 'Use the default scheme' },
+      { value: 'scheme-a', label: 'Scheme A' },
+    ]}
+    value={boundSchemeId ?? ''}
+    onChange={(v) => setBoundSchemeId(v === '' ? null : (v as string))}
+  />
+  ```
+
+  The trigger shows "Use the default scheme" (not a blank or the placeholder), and `onChange` hands you that row's `SelectOption`. "Nothing selected" is resolved by lookup — the value matches no option — so a Select with no `''` row still shows its placeholder at `value=""`. Corollary for `clearable`: ✕ means "reset to the empty value", so it is hidden when the selected option already IS `value: ''`, and shown for a stale value that matches nothing.
+
+- For **action menus** (Edit/Delete/Duplicate buttons), use `<DropdownMenu>` — Select is for value selection, not actions.
+- For **free-form text**, use `<Input>`. Select always picks from a (possibly async) set.
+- Don't reach for `triggerDisplay='summary'` for tag input — chips communicate the active filter set at a glance.
+
+**Keyboard / ARIA:** implements the WAI-ARIA combobox 1.2 pattern with a `role="listbox"` popup: Arrow keys, Home/End, typeahead, Enter/Space to select, Escape to dismiss. In chips mode, Backspace on an empty input removes the trailing chip; chip-to-chip arrow navigation (ArrowLeft from the empty input into the chips, ArrowLeft/Right cycling them) is not implemented.
+
+**Anti-patterns**
+
+- For yes/no/maybe with strong defaults, use `<Tabs>` or radio buttons.
+- Embedding stale-closure logic in `loadOptions`: the fetcher runs on every debounced query, so read fresh props from a stable reference (e.g. `useCallback`) instead of capturing values that drift.
+- `triggerDisplay='summary'` collapses the active set into a comma-joined line and has no per-item remove affordance; chips do.

package/docs/components/SettingRow.md

@@ -0,0 +1,98 @@
+# `<SettingRow>` — one row of a settings screen
+
+```tsx
+<SettingRow.List dividers labelWidth="18rem">
+  <SettingRow
+    label="Seats"
+    labelAdornment={
+      <Badge tone="neutral" size="sm">
+        From plan
+      </Badge>
+    }
+    description="Member seats included for this tenant"
+    controlWidth="xs"
+    trailing={
+      <Constrain width="xs">
+        <Select options={modes} value={mode} onChange={setMode} />
+      </Constrain>
+    }
+    footer={
+      <Constrain maxWidth="sm">
+        <Progress value={used} max={included} aria-label="Seats usage" />
+      </Constrain>
+    }
+  >
+    <Input type="number" />
+  </SettingRow>
+</SettingRow.List>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `SettingRowProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | yes | Label text. Renders a `<label htmlFor>` that names the control. Required — an empty or falsy value (e.g. `0`, `''`, `[]`, `<></>`) renders no `<label>` at all; see the anti-pattern below. |
+| `labelAdornment` | `ReactNode` | no | Badges / chips on the label line, rendered as a SIBLING of the `<label>`. Deliberately outside it: label content becomes the control's accessible name, so a provenance badge placed inside makes the input announce "Seats From plan". |
+| `description` | `ReactNode` | no | Helper text under the label, in the label column. Linked via `aria-describedby`. |
+| `controlWidth` | `'auto' \| 'xs' \| 'sm' \| 'md'` | no | Width of the control only — `trailing` is not sized by it. Default `'auto'` — the control's intrinsic width. Every row using the same step gets the same control width (capped at the column, so a narrow container still shrinks it), which is what keeps controls aligned down a `<SettingRow.List>`. Intended for controls that stretch to `width: 100%` (`Input`, `Select`); a fixed-size control (`Switch`) does not grow — the slot just reserves the width. `trailing` stays on the control's line only while both fit: in a narrow column a wide step (`'md'`) plus `trailing` can wrap `trailing` onto a second line. Use a smaller step if that matters. |
+| `trailing` | `ReactNode` | no | Content after the control on the same line — a mode select, a state badge, a reset button. `controlWidth` does NOT apply here — it only sizes the main control. A control that sizes itself to `width: 100%` (`Select`, `Input`, `Textarea`) fills the ENTIRE trailing group and pushes any other adornment onto a second line; wrap it in `<Constrain width="xs">` (or another named step) to size it instead. Plain truthiness check: an empty array or fragment still renders an empty wrapper (a stray gap) — pass `undefined` for "none". |
+| `footer` | `ReactNode` | no | Block under the control column — a usage meter, a caveat, a preview. Fills the control column's full width; cap a meter with `<Constrain>` — safe here, `footer` is not the wired child. |
+| `error` | `ReactNode` | no | Error message. Takes over `aria-describedby` and flips the control to `invalid`. Unlike `<Field>`, the `description` stays VISIBLE alongside it — the two sit in different columns, so an invalid value is no reason to remove the explanation of what the setting is. **Not announced, deliberately** — `aria-describedby` is read on focus, so the form owns the submit-time summary. Same reasoning as `<Field error>`. |
+| `required` | `boolean` | no | Marks the row required: shows `*` and injects `required` onto the control. |
+| `id` | `string` | no | Explicit control id. The row owns the id by default so the label always matches. |
+| `children` | `ReactNode \| ((field: FieldRenderProps) => ReactNode)` | yes | A single control element (auto-wired) or a render-prop `(field) => ReactNode`. |
+| …native | | | plus native `<div>` attributes |
+
+### `SettingRowListProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `labelWidth` | `string` | no | CSS length for the label column, shared by every row in the list (e.g. `'18rem'`, `'240px'`). Default `'16rem'` via the `--setting-row-label-width` token. A LENGTH, not `max-content` — rows align because they each resolve the same value, with no subgrid. |
+| `dividers` | `boolean` | no | 1px border between rows. Default `false`, matching `<DefinitionList>`. |
+| `spacing` | `'sm' \| 'md' \| 'lg'` | no | Vertical padding per row. Default `'md'`. |
+| `collapseBelow` | `false \| 'sm' \| 'md' \| 'lg'` | no | Container width at or below which each row stacks its label column above its control column. `'sm'` 480px / `'md'` 640px / `'lg'` 768px, measured against the LIST's own box (a container query, like `<Grid>` and `<Split>`). Default `'sm'`. Pass `false` to opt out of containment entirely — e.g. inside a shrink-to-fit parent (a `width: max-content` flex item, an inline-block, a table cell), where `container-type: inline-size` would otherwise zero the List's intrinsic-width contribution. See the anti-pattern below. |
+| `children` | `ReactNode` | yes | The rows. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Label (+ `labelAdornment`) and `description` in a shared LEFT column; control (+ `trailing`) and `footer` in the right. Wiring is `<Field>`'s — same `id` / `aria-labelledby` / `aria-describedby` / `invalid`, same render-prop `field` object.
+- ❌ Don't wrap the control in `<Constrain>` to cap it, use `controlWidth` — `Constrain` becomes the element the row wires, silently stripping the control's `id` and `aria-*`.
+- ❌ Mixing control sizes in one row — a `size="sm"` adornment beside a default-`md` control renders two different heights on the same line.
+- `<SettingRow.List>` owns the shared label column (`labelWidth`, default `16rem`), `spacing` (`sm`/`md`/`lg`, default `md`), `dividers` (default `false`) and `collapseBelow` (`sm`/`md`/`lg`, default `'sm'` — a container query on the list's own box that stacks each row; pass `false` to opt out of containment entirely). **Collapse only works inside a List** — a standalone `<SettingRow>` never stacks at any width.
+- ❌ A `SettingRow.List` inside a shrink-to-fit parent (a `width: max-content` flex item, an inline-block, a table cell) with the default `collapseBelow` — the List is a size container by default, so its intrinsic-width contribution is zero and it collapses. Pass `collapseBelow={false}` there.
+- ❌ Read-only key/value → `<DefinitionList>`. ❌ An ordinary form field → `<Field>`. ❌ `margin` on a row to space rows → that is the List.
+
+```tsx
+// A plain setting — no adornments:
+<SettingRow label="Default currency" description="Currency preselected for new records">
+  <Select options={currencies} value={currency} onChange={setCurrency} />
+</SettingRow>
+
+// Render-prop for a wrapped or native control:
+<SettingRow label="Webhook URL" error={errors.url}>
+  {(field) => <input type="url" {...field} />}
+</SettingRow>
+```
+
+**Alignment:** rows align because the label column is a length shared via `--setting-row-label-width`; set it once on `<SettingRow.List>` (`labelWidth`), never on individual rows.
+
+**When NOT to use**
+
+- A form field in a normal form: use `<Field>`; the shared label column is wrong for a two-up `<FormRow>`.
+- A single self-labelling `<Checkbox>` / `<Switch>`: put it in a `<Cluster>`, or pass it as the row's control with the row's `label` as the only label (don't double-label).
+- Grouping rows under a heading: use `<FormSection>`, which can wrap a `<SettingRow.List>`.
+
+**Anti-patterns**
+
+- A badge inside `label` instead of `labelAdornment`: it joins the control's accessible name.
+- A bare `<Cluster justify="between">` or packed-left `<Cluster>` for a settings row: the first flings the control to the far edge of a wide card, the second leaves every row's control at a different x.
+- A `<Stack>` of rows with ad-hoc `gap` instead of `<SettingRow.List>`: no shared label-column owner and no divider rhythm.
+- Absent-value semantics: `label` / `error` / `description` treat `0`, `NaN`, `false`, `''`, an empty array and an empty fragment as ABSENT, so `description={remaining}` with `remaining === 0` or `error={errors.map(...)}` with no errors renders nothing (no `<label>`, no description, no error, no `invalid` flip). A labelless control falls back to its own `aria-label`, or is unnamed. A real but visually empty node (`label={<span />}`, `label="   "`) or an empty one-shot iterator (`Map.prototype.values()`, a generator) counts as present.
+- An absent `label` also removes the `required` `*` marker (it lives inside the `<label>`): `<SettingRow label={0} required>` shows no `*`.

package/docs/components/Skeleton.md

@@ -0,0 +1,68 @@
+# `<Skeleton>` — loading placeholder
+
+```tsx
+<Skeleton width={120} />                                    // text line
+<Skeleton variant="circular" width={32} />                  // avatar
+<Skeleton variant="rectangular" width="100%" height={120} /> // image
+<Skeleton loading={isFetching} delay={200} minDuration={300} /> // no flash
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `variant` | `'text' \| 'circular' \| 'rectangular'` | no | Shape preset. Defaults to `'text'`. - `'text'` — inline-block; `height` defaults to `1em` so it sits on text baselines. Use inside paragraphs / labels for word-shaped placeholders. - `'circular'` — `border-radius: 50%`; when only one of `width`/`height` is set, the other matches (square). Avatar / icon placeholder. - `'rectangular'` — block, small radius. Image / card / button placeholder. |
+| `width` | `string \| number` | no | Explicit width. Number → px, string → as-is (e.g., `'60%'`, `'12rem'`). |
+| `height` | `string \| number` | no | Explicit height. Number → px, string → as-is. Defaults: `text` → `1em`, `circular` → matches `width` (square), `rectangular` → no default (consumer must size). |
+| `animation` | `'pulse' \| 'none'` | no | Animation. Defaults to `'pulse'`. - `'pulse'` — opacity 1 → 0.6 → 1, 1.5s ease-in-out infinite. - `'none'` — static. Use when stacking many skeletons to avoid motion overload. Regardless of this prop, animation is suppressed when the user has `prefers-reduced-motion: reduce`. |
+| `loading` | `boolean` | no | Whether the loading placeholder is needed. Defaults to `true`. Keep Skeleton mounted and drive this prop when using `minDuration`, so the component can finish its visibility window after loading completes. |
+| `delay` | `number` | no | Milliseconds to wait before rendering the placeholder. Defaults to `0`. A load that finishes inside this window never displays the Skeleton. |
+| `minDuration` | `number` | no | Minimum milliseconds to remain visible after the placeholder renders. Defaults to `0`. Prevents a Skeleton that appears just after `delay` from disappearing again within a frame or two. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+For a mutually exclusive placeholder/content branch, use the public timing hook:
+
+```tsx
+const showPlaceholder = useSkeletonVisibility(isFetching, {
+  delay: 200,
+  minDuration: 300,
+});
+
+return showPlaceholder ? (
+  <Skeleton variant="rectangular" width="100%" height={120} />
+) : isFetching ? null : (
+  <ContactList contacts={contacts} />
+);
+```
+
+- Three variants: `text` (default, inline, `height=1em`), `circular` (avatar / icon, square when only one dim set), `rectangular` (image / card / button, block).
+- Timed visibility: keep Skeleton mounted, drive `loading`, and use `delay` to suppress fast-load flashes plus `minDuration` to prevent a just-shown placeholder from vanishing immediately. All three preserve legacy behavior by default (`loading=true`, both durations `0`). Do not conditionally unmount a timed Skeleton — unmounting bypasses `minDuration`.
+- `useSkeletonVisibility(loading, { delay, minDuration })` exposes the same timing semantics for composite components that must choose between placeholder and content. During the delay it returns `false`, so guard the content branch with `loading` when stale content must not render.
+- Pulse is **automatically suppressed** when the user has `prefers-reduced-motion: reduce`.
+- `aria-hidden='true'` by default — Skeleton is decorative. Communicate "loading" from a parent live region you own. Note `aria-busy` alone on the section will NOT do it — no mainstream screen reader speaks it on a non-live element; pair it with `role="status"` and text that changes. Skeleton is one of the few components where announcing is genuinely yours, because it has no state of its own to describe.
+- Composes — for a list-row placeholder, render `<Skeleton variant='circular' />` + 2–3 text skeletons + a button-shaped rectangular in a Cluster.
+- Use `<EmptyState>` for "nothing here yet" — Skeleton implies "loading," not "empty."
+
+```tsx
+// List-row loading: avatar + two text lines + button
+<Cluster gap="md" align="center">
+  <Skeleton variant="circular" width={32} />
+  <Stack gap="xs" style={{ flex: 1 }}>
+    <Skeleton width="60%" />
+    <Skeleton width="40%" />
+  </Stack>
+  <Skeleton variant="rectangular" width={80} height={32} />
+</Cluster>
+```
+
+**Anti-patterns**
+
+- Wrapping real content in a Skeleton: it is a leaf, don't pass children.
+- Omitting all dimensions on `rectangular`: with no `width` / `height` the box has zero size and renders invisibly. Always size it.
+- Showing an immediate placeholder for loads that resolve quickly: use `delay` so fast loads never display it.
+- Conditionally unmounting a timed Skeleton (`{loading && <Skeleton minDuration={300} />}`): React removes it before the minimum can finish. Keep it mounted and pass `loading={loading}`.

package/docs/components/Slider.md

@@ -0,0 +1,92 @@
+# `<Slider>` — controlled slider (single + range, horizontal + vertical)
+
+```tsx
+<Slider value={zoom} min={1} max={3} step={0.1} onChange={(v) => setZoom(v as number)} aria-label="Zoom" />
+
+<Slider
+  value={price}                                   // tuple → range mode
+  min={0} max={100000} step={1000}
+  label={(v) => `$${v.toLocaleString()}`}
+  onChange={(v) => setPrice(v as [number, number])}
+  aria-label="Price range"
+/>
+
+<Slider
+  value={volume}
+  orientation="vertical"
+  marks={[0, 25, 50, 75, 100]}
+  onChange={(v) => setVolume(v as number)}
+/>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `invalid` | `boolean` | no | Marks each thumb `aria-invalid` for Field / SettingRow composition. Default: `false`. |
+| `required` | `boolean` | no | Consumed for Field / SettingRow composition (they render the visible required marker). `role="slider"` does not support `aria-required` and a slider always has a value, so nothing is forwarded. |
+| `value` | `SliderValue` | yes | Current value. A single `number` for one-thumb mode; a `[min, max]` tuple for two-thumb (range) mode. The component type-discriminates internally. Required — Slider is controlled-only. |
+| `onChange` | `(value: SliderValue) => void` | yes | Called on every thumb-drag tick (high frequency). For server-side or expensive update logic, prefer `onChangeEnd` or debounce in the consumer. The argument has the same shape as `value`: `number` for single, `[number, number]` for range. |
+| `onChangeEnd` | `((value: SliderValue) => void)` | no | Called once when the user "commits" a value change — at pointerup after a drag, or at blur after keyboard-nav that actually changed the value. Does NOT fire on Tab-in / Tab-out without any value change. Use for committing the value to a server or running an expensive recalculation. Receives the final value with the same shape as `value`. |
+| `min` | `number` | no | Minimum allowed value (inclusive). Default `0`. |
+| `max` | `number` | no | Maximum allowed value (inclusive). Default `100`. |
+| `step` | `number` | no | Step granularity. Default `1`. Use fractional steps (e.g. `0.1`) for zoom / opacity-style controls. Values are snapped to `min + (n * step)`. |
+| `marks` | `number[] \| SliderMark[]` | no | Tick marks. Pass `number[]` for auto-labeled ticks (label = value) or `SliderMark[]` for custom labels (label = ReactNode). Marks render under the track (horizontal) or to the right (vertical). |
+| `label` | `boolean \| ((value: number) => ReactNode)` | no | Value bubble on the thumb. - `false` (default) — no bubble. - `true` — show the current value (formatted via `toString()`) on hover / focus / drag. Auto-hides otherwise. - `(value: number) => ReactNode` — custom formatter. For range mode, the formatter is called once per thumb. |
+| `thumbLabels` | `readonly [string, string]` | no | Explicit accessible names for the minimum and maximum thumbs in range mode. These win over a root `aria-label` or `aria-labelledby`; use them when the thumbs need domain-specific names such as `['Start date', 'End date']`. When an entry is omitted OR empty — an empty string is not an explicit name — that thumb falls back to a root label suffixed with the localized “minimum” or “maximum” name. The two entries are resolved independently, so `['', 'End date']` names only the maximum thumb. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Track + thumb sizing. Defaults to `'md'`. - `sm` — 4px track, 14px thumb. - `md` — 6px track, 18px thumb (default). - `lg` — 8px track, 22px thumb. |
+| `tone` | `'default' \| 'success' \| 'warning' \| 'danger'` | no | Fill color tone (the track segment between min and value). Defaults to `'default'` (accent). State-coded `success` / `warning` / `danger` for threshold-style sliders (e.g. disk usage approaching capacity). |
+| `orientation` | `'horizontal' \| 'vertical'` | no | Orientation. Defaults to `'horizontal'`. Vertical defaults to 200px tall; override via `style={{ height }}`. |
+| `disabled` | `boolean` | no | Disabled state. Defaults to `false`. Thumbs become non-interactive (`tabIndex=-1`, `aria-disabled`, `pointer-events: none`, `cursor: not-allowed`). |
+| `name` | `string` | no | Native form-input name. When set, a hidden `<input>` (or two for range, with `-min`/`-max` suffixes) is rendered with the current value(s) so the slider works inside uncontrolled HTML forms without consumer JS serialization. When the slider is `disabled`, the hidden input(s) are NOT rendered so the form does not submit a stale disabled value. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Controlled-only.** Always pass `value` + `onChange`. No `defaultValue`. Same architecture as FileUpload, Progress, and the rest of the controlled primitives.
+- **`value: number | [number, number]`** — discriminated union. `number` for single-thumb; tuple for range (two-thumb). `onChange` mirrors the shape.
+- **Range thumb names:** every range thumb must have a distinct accessible name. A root `aria-label="Price range"` produces “Price range, minimum” and “Price range, maximum” (localized); a root `aria-labelledby` is preserved and gets an appended localized suffix. Use `thumbLabels={['Lowest price', 'Highest price']}` when the names are domain-specific — explicit tuple labels win.
+- **`onChange` fires per pointer-move tick (high frequency).** Debounce in the consumer OR use `onChangeEnd` (fires at pointerup, or at blur when the value actually changed) for server-state / expensive logic.
+
+#### Keyboard
+
+- Arrow Left/Down: `-step`. Arrow Right/Up: `+step`.
+- Page Down/Up: `-10×step` / `+10×step`.
+- Home / End: jump to `min` / `max`.
+- All keys respect range-mode clamping (`value[0] ≤ value[1]`). `onChange` per key. `onChangeEnd` fires on blur ONLY if the value actually changed during the focus session — Tab-in / Tab-out without any nav does NOT fire.
+
+#### Hard rule
+
+- ❌ Raw `<input type="range">` — can't do range mode, doesn't theme cleanly across browsers. Use `<Slider>`.
+- ❌ Hand-rolling drag math per page. The pointer / keyboard handling is non-trivial; the primitive owns it.
+- ❌ Hitting a network endpoint inside `onChange` — fires on every pointer-move tick. Use `onChangeEnd` or debounce.
+- ❌ `<Slider role="region">` — `role="slider"` is locked on each thumb. The TypeScript `Omit` prevents the root override.
+- ❌ Passing `value[0] > value[1]` in range mode. The component clamps but the inverted tuple is a consumer bug — fix the state shape.
+
+Custom-painted rather than wrapping `<input type="range">`, because range mode needs two thumbs.
+
+```tsx
+// Tone-coded threshold (disk usage approaching capacity):
+<Slider
+  value={usage}
+  tone={usage > 90 ? 'danger' : usage > 75 ? 'warning' : 'default'}
+  onChange={(v) => setUsage(v as number)}
+  label
+/>
+
+// Form submission via `name` — renders hidden inputs the form picks up:
+<form action="/api/settings" method="post">
+  <Slider name="brightness" value={brightness} onChange={setB} />
+  <button type="submit">Save</button>
+</form>
+```
+
+**When NOT to use**
+
+- Binary state: use `<Switch>` or `<Checkbox>`.
+- Pick one of a small enumerated set: use `<RadioGroup>` or `<Select>`.
+- Continuous colour picking: that is a colour picker (not yet shipped).
+- Server-bound expensive updates on every move tick: use `onChangeEnd` or debounce.

package/docs/components/SlotGrid.md

@@ -0,0 +1,55 @@
+# `<SlotGrid>` — grouped time-slot tiles
+
+```tsx
+<SlotGrid
+  groups={[
+    {
+      label: 'Morning',
+      slots: [
+        { key: '09:00', label: '9:00' },
+        { key: '09:30', label: '9:30' },
+      ],
+    },
+    { label: 'Afternoon', slots: [{ key: '14:00', label: '14:00' }] },
+  ]}
+  value={slot}
+  onChange={setSlot}
+  empty={<Text tone="muted">No times this day — try another.</Text>} // optional
+/>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `groups` | `SlotGridGroup[]` | yes | Groups in display order. |
+| `value` | `string \| null` | yes | Selected slot `key`, or `null`. A key not in `groups` checks nothing. |
+| `onChange` | `(key: string) => void` | yes | Called with the chosen slot's `key`. Controlled — update `value` yourself. |
+| `empty` | `ReactNode` | no | Shown when no group has any slot. Default: the localized "No available times". |
+| `titleOrder` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | Heading level of each group label. Default `3`. |
+| `name` | `string` | no | Radio group `name` (also submitted with a form). Default: a generated id. |
+| `invalid` | `boolean` | no | Marks the group `aria-invalid` (the radios themselves do not support it). Field / SettingRow inject it. Default: `false`. |
+| `required` | `boolean` | no | Native `required` on the radios (the group then fails form validation until one is chosen). Field / SettingRow inject it; it used to land on the root as a stray attribute. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Slot `label`s are yours, formatted in the business's timezone. `key` is what `onChange` returns; keep it unique across ALL groups (one exclusive choice).
+- Native radios with one `name`: one Tab stop for the whole grid, arrows move AND select in reading order (↓ goes to the next slot, not the one below). Tiles are `role="radio"` named by their label; each group is a `<fieldset>` named by its heading (`titleOrder`, default 3).
+- Groups with no slots are skipped; if none has slots, `empty` renders (default: localized "No available times").
+- The root is `role="group"`: in `<Field>` / `<SettingRow>` the row label names it and the error describes it; `invalid` → `aria-invalid` on the group, `required` → native `required` on the radios.
+- 6 columns, 3 when the grid's own width ≤ 48rem (container query).
+- ❌ No per-slot `disabled` — pass only bookable slots. ❌ Don't wrap it in your own `role="radiogroup"`.
+- ❌ In an intrinsic-width context (`Split`'s default `auto` aside track, a `Cluster` item, `width: max-content`) it renders at width 0 — `container-type: inline-size` zeroes its intrinsic-width contribution; give the parent a concrete width (e.g. `asideWidth` on a Split). It is also the containing block for absolutely-positioned descendants (layout containment).
+- When NOT to use: free-form time → `<TimeField>`; a handful of options → `<ButtonGroup value>` / `<RadioGroup>`.
+
+```tsx
+// Booking time step: DateStrip picks the day, SlotGrid the time.
+<Stack gap="lg">
+  <DateStrip days={week} value={day} onChange={setDay} onPrevious={prev} onNext={next} />
+  <SlotGrid groups={slotsFor(day)} value={slot} onChange={setSlot} />
+</Stack>
+```

package/docs/components/SocialButton.md

@@ -0,0 +1,31 @@
+# `<SocialButton>` — provider sign-in button
+
+```tsx
+<SocialButton provider="google" label="Continue with Google" onClick={signIn} />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `provider` | `'google' \| 'yandex'` | yes | Which provider's brand mark to show. Tied to `<BrandIcon>`'s set, so it grows as BrandIcon does (today: `'google'` / `'yandex'`). |
+| `label` | `ReactNode` | yes | The button text — e.g. `"Continue with Google"`. Required (consumer-supplied). |
+| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'danger-outline' \| 'success'` | no | Button variant; the values are Button's. Defaults to `secondary`, not Button's `primary`. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | Control height (matches the shared `--size-*` scale used by Input and Avatar). - `xs` (20px) — icon-only or very dense inline actions (row controls, chip-adjacent buttons). Pass `aria-label` when icon-only. Below WCAG 2.5.5 Level AAA touch-target guidance; reserve for desktop-first surfaces. - `sm` (24px) — dense toolbars, tables, inline actions. - `md` (32px, default) — most contexts. - `lg` (40px) — marketing-style empty states or emphasized primary actions. |
+| `as` | `"button"` | no | Render a different element — the case that matters is `as="a"` with `href`, for a link that must LOOK like a button (an external console, a download, an IdP hand-off). The element named here is what actually renders, and its own attributes are typed: `href` is REQUIRED when `as="a"` (an anchor without one is neither focusable nor a link) and rejected otherwise; `target`/`rel`/`download` come through. Never navigate from `onClick`. Reach for `<Link>` first. `<Link>` is link-SHAPED navigation — inline text in a sentence, a table cell, a breadcrumb. `<Button as="a">` is for a destination that sits in a row of buttons and must carry their weight. Either way the element is a real anchor, so assistive tech announces a link and the browser gives middle-click, "open in new tab", and the status bar preview — none of which a `<button onClick={() => navigate()}>` has. `type="button"` is emitted only for a real `<button>`; an anchor never gets it. Everything else — variant, size, `iconOnly`, `selected`, the focus ring — is unchanged. Default: `'button'`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- A `<Button>` with the provider's `<BrandIcon>` mark + `label`. Spreads Button props (`onClick`, `size`, `disabled`, …); width comes from the parent.
+- The mark is decorative — `label` is the accessible name. For a non-SSO icon button use `<Button>` + a lucide icon.
+
+```tsx
+<Stack gap="sm">
+  <SocialButton provider="google" label="Continue with Google" onClick={signInWithGoogle} />
+  <SocialButton provider="yandex" label="Continue with Yandex" onClick={signInWithYandex} />
+</Stack>
+```