@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/Constrain.md

@@ -0,0 +1,39 @@
+# `<Constrain>` — size / flex constraint
+
+```tsx
+<Constrain maxWidth="sm"><Input placeholder="Search…" /></Constrain>
+
+<Constrain height="viewport-70" maxHeight="lg"><FlowCanvas /></Constrain>
+
+<Cluster wrap={false} gap="sm">
+  <Constrain flex="grow"><Progress value={x} max={y} /></Constrain>
+  <Button>Upgrade plan</Button>
+</Cluster>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `width` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | no | Fixed width — a named step (`xs` 200 / `sm` 320 / `md` 448 / `lg` 640 / `xl` 800px, via `--measure-*` tokens) or `'full'` (100%). |
+| `minWidth` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | no | Minimum width floor — a named step or `'full'` (100%). |
+| `maxWidth` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | no | Maximum width cap — the common case (e.g. a search input at `'sm'`). |
+| `height` | `'viewport' \| 'viewport-70' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xs' \| 'full'` | no | Fixed height — a named measure (same scale as the widths), `'full'` (100%), `'viewport'` (100dvh), or `'viewport-70'` (70dvh). `height="viewport-70"` with `maxHeight="lg"` makes a viewport-relative panel that never exceeds 640px. |
+| `minHeight` | `'viewport' \| 'viewport-70' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xs' \| 'full'` | no | Minimum height floor — a named measure, `'full'`, `'viewport'`, or `'viewport-70'`. |
+| `maxHeight` | `'viewport' \| 'viewport-70' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xs' \| 'full'` | no | Maximum height cap — a named measure, `'full'`, `'viewport'`, or `'viewport-70'`. |
+| `flex` | `'grow' \| 'shrink' \| 'auto' \| 'none'` | no | Flex behavior as a child of a flex row/column. - `'grow'` — fill remaining space (`flex: 1 1 0`) and shrink below content width (`min-width: 0`) so a truncating child (`<Text truncate>`) can clip. To opt a `Stack`/`Cluster` into that truncating chain WITHOUT also making it fill the row, use their `minWidth0` prop instead — and note Constrain renders a `<div>`, so it is invalid inside a `<button>`/`<a>`/`<label>`, where `<Cluster as="span" minWidth0>` is the only option. - `'auto'` — size to content, may grow/shrink (`flex: 1 1 auto`). - `'shrink'` — don't grow, may shrink (`flex: 0 1 auto`, the flex default). - `'none'` — fixed, never grow/shrink (`flex: 0 0 auto`). Omit for no flex class: the element behaves as its flex container dictates. |
+| `children` | `ReactNode` | yes | The content to size. Required — a Constrain with nothing inside has nothing to constrain. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- The one place width/height/flex sizing lives — `Stack`/`Cluster`/`Grid` are spacing-only (Rule 4). Constrain sizes its **own** box; it does not arrange children (put a `Cluster`/`Stack` inside).
+- No padding/border/background — for those use `<Card>`; for a full-bleed shell use `<Screen>`.
+
+#### Anti-patterns
+
+- ❌ Reaching for Constrain to add `margin` / `padding`. It carries size/flex only; spacing comes from the parent layout primitive.
+- ❌ Spacing or arranging children: use `<Stack>` / `<Cluster>` / `<Grid>`.

package/docs/components/CurrencySelect.md

@@ -0,0 +1,57 @@
+# `<CurrencySelect>`
+
+Currency picker over the DS `Select`: you pass the ISO 4217 `currencies` to offer (required, in display order); it renders `CODE — Name` rows with localized names (`Intl.DisplayNames`). Single mode is controlled on `value: string | null` / `onChange(code | null)`; `multiple` switches to `string[]` (with `triggerDisplay` `"chips"` / `"summary"`). `currencyDisplay` sets how the SELECTED currency shows in the trigger: `"code"` (default, `EUR`), `"symbol"` (`€`) or `"both"` (`EUR €`). Search turns on automatically above 7 currencies (`searchable` overrides) and matches code, name and symbol. Invalid codes are dropped with a dev warning. `size`/`invalid`/`disabled`/`clearable`/`name` etc. pass through to `Select`.
+
+```tsx
+const [cur, setCur] = useState<string | null>('EUR');
+<CurrencySelect
+  currencies={['EUR', 'USD', 'GBP']}
+  value={cur}
+  onChange={setCur}
+  aria-label="Currency"
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `currencies` | `string[]` | yes | ISO 4217 codes to offer, in display order (e.g. `['USD', 'EUR']`). Required; there is no "all currencies" default. Invalid codes are dropped with a dev warning. |
+| `currencyDisplay` | `'code' \| 'symbol' \| 'both'` | no | How the SELECTED currency renders in the trigger. Default `"code"`. - `"code"` — `EUR`. - `"symbol"` — `€`. - `"both"` — `EUR €`. Dropdown rows always read `CODE — Name` so they stay identifiable and searchable. |
+| `locale` | `string` | no | BCP-47 locale for currency names and symbols. Defaults to the active i18n locale (`useLocale()`). |
+| `searchable` | `boolean` | no | Show a search input. Default: on when more than 7 currencies are offered. |
+| `multiple` | `false \| true` | no | Single mode (default). |
+| `value` | `string \| null \| string[]` | yes | Controlled ISO code; `null` = nothing selected. |
+| `onChange` | `(code: string \| null) => void \| (codes: string[]) => void` | yes | Fires with the picked code, or `null` when cleared. |
+| `triggerDisplay` | `'summary' \| 'chips'` | no | How selections render in the trigger: `"chips"` (default) or `"summary"`. |
+| `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`. |
+| `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. |
+| `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. |
+| `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 HTML attributes |
+
+<!-- props:end -->
+
+**When NOT to use:** an amount plus its currency — use `MoneyInput`. A generic option list — use `Select`.
+
+**Anti-patterns**
+
+- ❌ Passing `options`, `renderOption` or `creatable` — options are derived from `currencies`.
+- ❌ Expecting an "all currencies" default — `currencies` is required; an empty list renders an empty picker.
+- ❌ Passing lowercase or made-up codes — they are dropped (dev warning).

package/docs/components/CursorPagination.md

@@ -0,0 +1,43 @@
+# `<CursorPagination>` — prev / next for streams without total
+
+```tsx
+<CursorPagination hasPrevious={hasPrev} hasNext={hasNext} onPrevious={loadPrev} onNext={loadNext} />
+
+// Activity feed with reversed direction labels
+<CursorPagination
+  hasPrevious={hasNewer}
+  hasNext={hasOlder}
+  onPrevious={loadNewer}
+  onNext={loadOlder}
+  previousLabel="Newer"
+  nextLabel="Older"
+/>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `hasPrevious` | `boolean` | yes | Whether a previous page exists. When `false`, the previous button is rendered as `disabled` (layout stays stable; consumer doesn't have to conditionally hide it). |
+| `hasNext` | `boolean` | yes | Whether a next page exists. |
+| `onPrevious` | `() => void` | yes | Called when the user clicks previous (not fired when disabled). |
+| `onNext` | `() => void` | yes | Called when the user clicks next (not fired when disabled). |
+| `previousLabel` | `ReactNode` | no | Label for the previous button. Defaults to the i18n value at `pagination.previous` (`'Previous'` in English). Override for domain phrasing (`'Newer'` in a reverse-chronological feed). An EMPTY string counts as unset, not as an explicit blank: this label is the button's only name source (the chevron is `aria-hidden`), so an empty one would leave the button anonymous rather than merely unlabelled. |
+| `nextLabel` | `ReactNode` | no | Label for the next button. Defaults to the i18n value at `pagination.next` (`'Next'` in English). An EMPTY string counts as unset, for the same reason as `previousLabel`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Visual size — `'sm'` / `'md'` (default) / `'lg'`. Shares the `<Pagination>` size scale so the two components match when used alongside each other. |
+| `disabled` | `boolean` | no | When `true`, both buttons are disabled regardless of has-prev/-next. |
+| `aria-label` | `string` | no | Accessible name for the wrapper `<nav>`. Defaults to the i18n value at `pagination.ariaLabel` (`'Pagination'` in English) when omitted OR empty — an empty string is not an explicit name, so it takes the default too. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- Two-button prev / next nav for keyset-paginated streams (activity feeds, infinite scroll, cursor-based APIs). Controlled — consumer owns the cursor + `has-prev` / `has-next` flags.
+- Buttons render as native `<button disabled>` when `hasPrevious` / `hasNext` is false — no layout shift; consumer doesn't have to conditionally hide them.
+- Shares the `<Pagination>` size scale (`sm` / `md` / `lg`).
+- Use `<Pagination>` (numbered) when you have a known total page count. CursorPagination is for streams.
+
+- A11y: the wrapper is `<nav aria-label="Pagination">` (overridable for disambiguation). Disabled buttons are native, so screen readers announce "dimmed" and skip them in Tab order.
+- Use `<Pagination>` (numbered, with jump-to-page and progress indication) when you have a total page count.

package/docs/components/DashboardCanvas.md

@@ -0,0 +1,79 @@
+# `<DashboardCanvas>` — 2D snap-grid dashboard
+
+Datadog-style 2D snap-grid dashboard. `value` is `{ items: DashboardPlacement[], sections: DashboardSection[] }` — top-level items plus an ordered array of full-width collapsible sections, each with its own sub-grid on the same column count (`columns` prop, default 24 — pass `columns={12}` for layouts saved against a 12-column schema like the eocrm layout-v2 spec; placements are NOT converted between column counts). Always controlled, no uncontrolled mode: `onChange(next)` fires once per completed gesture (a drop, a resize end, a collapse toggle, a band reorder, a cross-container move) with the whole engine-computed next value; omit it for a static layout — drags still preview live but nothing persists past pointerup. `renderItem(id)` renders every item's body — including items inside a COLLAPSED section, whose body stays mounted and `inert` rather than unmounting, so a widget that fetches on mount pays that cost even while collapsed — called once more for the drag ghost mid-gesture, so keep it pure. **The grid cell is chrome-less** (no background/border/radius/shadow, no minimum height beyond its `h` row-span) — wrap the return in `<Card>` for the boxed widget look, and size the content to the cell or accept bare (dotted, in edit mode) space showing below a shorter widget. `renderSectionHeader(id)` adds small extras (a title editor, a `DropdownMenu` trigger) to the right of a section's title, in the same `Accordion.Trigger` `actions` slot as the section's own band-reorder grip handle — neither ever starts a collapse toggle or a drag. `highlightedSectionId` highlights a section's band with a ring and outward waves (scrolls it into view first, works on collapsed bands, never moves focus) — set it to the id of a section you just added and clear it in `onSectionHighlightDone`; setting the same id again after that re-triggers. `constraints` — a `Record<id, { minW?, minH?, maxH? }>` or a `(id) => constraints | undefined` function — clamps resize gestures per item; unlisted items default to `minW: 1`, `minH: 1`, no `maxH`. Section bands compose the DS `Accordion` (`type="multiple"`) for their header/chevron/panel look; edit mode (not `readOnly`, not below `stackBelow`) also shows a snap-grid of dots on each container so a drag/resize's destination cell is visible before you commit.
+
+Gestures: drag-to-move with push-down collision + live compaction preview (dropping on the upper/lower half of another widget inserts before/after it, so stacked widgets reorder without gaps; during a move-drag each container gains trailing drop space the height of the dragged item, and the drag ghost stays inside the canvas), E/S/SE resize handles, cross-container drag (top level ↔ any expanded section), and vertical band reorder by dragging a section header. Full keyboard: Tab to an item, Enter/Space picks it up, arrows move it (crossing a container's edge moves it into the next band), Shift+arrows resize, Enter/Space drops, Escape cancels; Shift+arrows on a focused section header reorders bands.
+
+```tsx
+const [value, setValue] = useState<DashboardCanvasValue>(initialLayout);
+
+<DashboardCanvas
+  value={value}
+  onChange={setValue}
+  renderItem={(id) => <Card>{widgets[id].title}</Card>}
+  constraints={{ kpi: { minW: 2, maxH: 4 } }}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `DashboardCanvasValue` | yes | The controlled layout: top-level items plus an ordered array of collapsible sections. `DashboardCanvas` never mutates this value — every change flows out through `onChange`. |
+| `onChange` | `((next: DashboardCanvasValue) => void)` | no | Fires once per completed gesture — a drop, a resize end, a collapse toggle, a section reorder, or a cross-container move — with the whole next `value`. Omit for a read-only or fully static canvas; without it, drags preview live but nothing persists on drop. |
+| `renderItem` | `(id: string \| number) => ReactNode` | yes | Renders the body of an item by id. Called for every item on every render — including items inside a COLLAPSED section (its body stays mounted and `inert`, not unmounted, so Accordion's own collapse animation has real content to animate) — and once more for the dragged item mid-gesture (the cursor-following ghost). Keep it pure; a widget that fetches on mount pays that cost even while its section is collapsed. The cell itself is a bare positioned box with no background/border/radius/shadow of its own and no minimum height beyond its `h` row-span — that chrome belongs here, in whatever this returns (typically a `<Card>`); size the content to the cell, or accept that a shorter widget in a taller cell shows bare (dotted, in edit mode) space below it. |
+| `renderSectionHeader` | `((id: string \| number) => ReactNode)` | no | Optional extra controls in a section's header (a title editor, a `DropdownMenu` trigger) rendered by section id, to the right of the title. Keep it small — the header row is not a general-purpose toolbar. Pointer presses inside the slot never start a band-reorder drag. |
+| `highlightedSectionId` | `string \| number` | no | Id of a section whose band to highlight (scrolls into view, then a ring with outward waves, same as `Highlight`) — e.g. a section the user just added. Collapsed bands highlight too. Does not move focus. Clear it in `onSectionHighlightDone`; setting the same id again after that re-triggers. |
+| `onSectionHighlightDone` | `(() => void)` | no | Fires once the highlight run on `highlightedSectionId` has finished. |
+| `constraints` | `DashboardCanvasConstraintsProp` | no | Per-item size constraints, consulted when clamping resize gestures. |
+| `columns` | `number` | no | Column count of every container grid (top level and each section's sub-grid). All placement/resize bounds clamp against it. Minimum 1; fractional or sub-1 values are the consumer's bug, not validated. Layouts are NOT converted between column counts — a `value` saved at one `columns` renders at half width when the count doubles. Schemas written for the earlier 12-column grid (e.g. the eocrm layout-v2 spec) either pass `columns={12}` to match, or migrate their saved placements to 24. Default: `24`. |
+| `stackBelow` | `'sm' \| 'md' \| 'lg'` | no | Container width at (inclusive) and below which every container grid re-templates to one column and pointer + keyboard editing turns off: `sm` 480px / `md` 640px / `lg` 768px, measured against the canvas's OWN width (container query), not the viewport. Section collapse toggles keep working at any width. Default: `'md'`. |
+| `readOnly` | `boolean` | no | View-only mode: identical geometry, but no drag/resize wiring, no resize handles, and no keyboard editing — the canvas renders `value` and lets section collapse toggles keep working. The canvas also disables editing on its own, without this prop, once its own width drops to or below the `stackBelow` breakpoint (single-column stack) — `readOnly` is for a consumer-chosen view mode, the width gate is automatic. Default: `false`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+**Cells are SQUARE by default**: the row unit derives from the canvas's own width (`(width - (columns - 1) * gap) / columns`), so cell height == cell width at every size and the whole layout scales fluidly — override `--dashboard-canvas-row` with a fixed length for fixed-height rows (`--dashboard-canvas-row-stacked`, default 48px, is the row unit of the single-column stack, where the square unit would be uselessly tiny).
+
+`readOnly` turns off all editing (no handles, no keyboard editing) while section collapse toggles keep working — collapse is navigation, not editing. Independent of `readOnly`, at and below the `stackBelow` breakpoint (`'sm'` 480px / `'md'` 640px, the default / `'lg'` 768px) of the canvas's OWN width (a CSS container query, not the viewport) every container automatically re-templates to one column and editing turns off the same way — a `ResizeObserver` mirrors the breakpoint so a gesture can never half-start below it.
+
+When NOT to use: a single ordered list (priority queue, simple reordering) — use `Sortable`; fixed kanban-style columns — use `Kanban`; a free-form node/edge graph — use `FlowCanvas`. The canvas is ALWAYS a size container (named `dashboard-canvas`, unconditionally) — give it a parent with a concrete width; an intrinsic-width context (a `Cluster` item, `width: max-content`) renders it at width 0, same caveat as Grid's `collapseBelow`.
+
+A collapsed section's band is NOT a drop target — expand it first (no hover-to-expand). Escape or a pointer cancel mid-gesture restores the current `value` without firing `onChange`.
+
+#### Anti-patterns
+
+- ❌ Treating `value` as uncontrolled — passing it once with no `onChange`. Drags and resizes still preview live, but nothing persists past pointerup; the next render snaps the item back to the stale `value`.
+- ❌ Nesting a `DashboardCanvas` inside another one's `renderItem`: a nested canvas fights its parent for pointer capture and Escape handling.
+- ❌ Expecting the grid cell to draw a card-like surface. It is chrome-less by design so widgets with transparent bodies (charts, images) don't sit inside a redundant box — wrap `renderItem`'s output in `<Card>` for the boxed look.
+- ❌ Using it for a simple ordered list — see "When NOT to use" above.
+- ❌ Placing it in an intrinsic-width parent (a `Split` aside's default `auto` track, a `Cluster` item): the canvas is always a size container and renders at width 0. At and below `stackBelow` pointer + keyboard editing turns off (handles hidden, items not editing-focusable).
+
+#### More examples
+
+```tsx
+// Persist every completed gesture: keep the canvas controlled AND save.
+// Debounce / fire-and-forget is the caller's job.
+const handleChange = (next: DashboardCanvasValue) => {
+  setValue(next);
+  saveDashboardLayout(dashboardId, next);
+};
+
+// Read-only record view — same value shape, no editing affordances.
+<DashboardCanvas
+  value={savedLayout}
+  renderItem={(id) => <Card>{widgets[id].title}</Card>}
+  readOnly
+/>
+
+// Constraints computed from data, e.g. locking size for chart widgets.
+<DashboardCanvas
+  value={value}
+  onChange={setValue}
+  renderItem={(id) => <Card>{widgets[id].title}</Card>}
+  constraints={(id) => (widgets[id]?.kind === 'chart' ? { minW: 4, minH: 3, maxH: 6 } : undefined)}
+/>
+```

package/docs/components/DashboardWidget.md

@@ -0,0 +1,131 @@
+# `<DashboardWidget>` — card for a DashboardCanvas cell
+
+A widget card that fills its `DashboardCanvas` cell, in five presentations: `standard`, `list`, `kpi`, `chart` and `stats`. Owns the header (title, actions), the body chrome and a variant-matched loading skeleton. The app keeps data, error state, permissions and the overflow menu.
+
+```tsx
+import {
+  Card,
+  Chart,
+  DashboardCanvas,
+  DashboardWidget,
+  EmptyState,
+  ErrorState,
+} from '@eocrm/design-system';
+
+<DashboardCanvas
+  items={layout}
+  onItemsChange={setLayout}
+  renderItem={(id) => (
+    <DashboardWidget
+      variant="kpi"
+      title="Open deals"
+      actions={menu}
+      value="128"
+      trend={{ label: '+12% vs last month', direction: 'up' }}
+    />
+  )}
+/>;
+
+// kpi with a trend graphic: a Sparkline child renders under value/trend
+<DashboardWidget variant="kpi" title="Open deals" value="128">
+  <Sparkline label="Open deals per day" values={dailyCounts} />
+</DashboardWidget>;
+
+// kpi, where "up" is bad
+<DashboardWidget
+  variant="kpi"
+  title="Churned accounts"
+  value="14"
+  trend={{ label: '+3 vs last month', direction: 'up', sentiment: 'negative' }}
+/>;
+
+// list: Card.List bleeds edge to edge
+<DashboardWidget variant="list" title="Tasks due" actions={menu} loading={isLoading}>
+  <Card.List>{/* rows */}</Card.List>
+</DashboardWidget>;
+
+// chart: the plot fills the cell; a note under it goes in Chart's `footnote`
+<DashboardWidget variant="chart" title="Revenue">
+  <Chart
+    type="line"
+    label="Revenue per month"
+    categories={months}
+    series={revenue}
+    formatValue={formatCurrency}
+    footnote="3 deals in other currencies not included"
+  />
+</DashboardWidget>;
+
+// stats: a StatGroup KPI strip; compact padding leaves slack in a 3-row cell
+<DashboardWidget variant="stats" title="Key metrics">
+  <StatGroup aria-label="Key metrics">{/* StatTiles */}</StatGroup>
+</DashboardWidget>;
+
+// quiet view-mode header: actions appear on hover / focus
+<DashboardWidget title="Pipeline" actions={menu} actionsReveal="hover">
+  {/* body */}
+</DashboardWidget>;
+
+// standard (default), with error and empty states as children
+<DashboardWidget title="Recent activity" loading={isLoading}>
+  {error ? (
+    <ErrorState title="Could not load" headingLevel={4} />
+  ) : items.length === 0 ? (
+    <EmptyState title="Nothing yet" />
+  ) : (
+    <Feed items={items} />
+  )}
+</DashboardWidget>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `variant` | `'standard' \| 'list' \| 'kpi' \| 'chart' \| 'stats'` | no | Presentation variant. Default `'standard'`. - `'standard'` — header (title + actions) over a padded scrolling body. Today's widget card. - `'list'` — same fixed header as `standard`; flush scrolling body so `Card.List` bleeds edge to edge. - `'kpi'` — compact muted title, a large `value`, optional `trend`; optional `children` below. No scrolling. - `'chart'` — compact header; flush non-scrolling body that fills the cell (give the plot `height: 100%`). - `'stats'` — compact header and padding over a scrolling body, for a `StatGroup` KPI strip; unlike `standard` it leaves vertical slack in a 3-row cell. |
+| `title` | `ReactNode` | yes | Widget title, rendered as the heading at `headerLevel`. Required. |
+| `meta` | `ReactNode` | no | Secondary, non-interactive header text such as freshness ("Updated 3 minutes ago") or status. Sits before `actions` and yields first in a narrow cell: it truncates (then hides visually, still read by screen readers) before the title shrinks, while `actions` never shrinks. Also describes the body region (`aria-describedby`) for `standard` / `list` / `stats`. Repeat it in the refresh button's tooltip if it matters when truncated. |
+| `actions` | `ReactNode` | no | Header actions, e.g. the edit-mode overflow `DropdownMenu`. Never wraps. |
+| `actionsReveal` | `'always' \| 'hover'` | no | When `actions` are visible. Default `'always'`. - `'always'` — always shown. - `'hover'` — dimmed to invisible until the card is hovered or holds focus (they stay in the tab order, and Tab into the card reveals them); an open menu launched from an action keeps them shown. On touch / `(hover: none)` they stay visible. They keep their layout width. |
+| `headerLevel` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | no | Heading level of the title. Default `'h3'`. |
+| `value` | `ReactNode` | no | KPI value (`variant="kpi"` only), e.g. `"128"` or a formatted currency node. |
+| `trend` | `DashboardWidgetTrend` | no | KPI trend (`variant="kpi"` only). |
+| `loading` | `boolean` | no | Show a variant-matched loading skeleton instead of the body (and, for kpi, instead of `value`/`trend`); title and actions stay. Adds visually hidden "Loading…" body text and `aria-busy`. Deliberately NO live region: a dashboard loads many widgets at once, so per-widget announcements would flood screen readers — announce "dashboard loaded" once at page level if needed. Default `false`. |
+| `children` | `ReactNode` | no | Widget body. Pass `ErrorState` / `EmptyState` here for error and empty states. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Fills its cell.** It is a `<Card fill padding="none">`; `DashboardCanvas` sizes the cell, the widget fills it. The root is a `div` with a heading (no landmark; 20 regions on one dashboard is noise). Heading level is `headerLevel` (default `h3`).
+- **Variants.** `standard`: header + padded scrolling body. `list`: same fixed header as `standard`, flush scrolling body so `Card.List` bleeds edge to edge. `kpi`: compact muted title, large `value`, optional `trend`, optional `children` below; does not scroll. `chart`: compact header, flush body that does not scroll and fills the remaining height, so give the plot `height: 100%`. `stats`: compact header and padding over a scrolling body, for a [`StatGroup`](StatGroup.md) KPI strip; scrolls only on real overflow.
+- **Only `standard`, `list` and `stats` scroll.** `kpi` and `chart` bodies are non-scrolling (`Card.Body` without `scroll`).
+- **`value` / `trend` are kpi only** and ignored on other variants.
+- **Trend.** Direction icon plus a visually hidden "Increase / Decrease / No change" before `label`. Colour is by `sentiment`, which defaults from direction (up positive, down negative, flat neutral). Set `sentiment` explicitly when the direction is not the judgement (churn, overdue tasks up = `negative`).
+- **`loading`** swaps the body (for kpi, the value and trend) for a skeleton matching the variant (standard: lines, list: rows, kpi: value + trend, chart: bars, stats: kpi shape). Title and actions stay. For `stats`, prefer `StatGroup loading` (per-tile skeletons) over widget `loading`, which shows a single kpi blob; don't set both. The skeleton is `aria-hidden`; the body instead contains visually hidden "Loading..." text and the root gets `aria-busy` as a hint.
+- **No live region, on purpose.** A dashboard loads 10 to 20 widgets at once; a live region per widget would flood a screen reader. If you want an announcement, make one at page level ("Dashboard loaded") once all widgets settle. That is the app's job.
+- **Error and empty states** are the app's `ErrorState` / `EmptyState`, passed as `children` (for kpi, as `value` or `children`).
+- **`actions`** (e.g. an edit-mode `DropdownMenu`) sit at the header's end and never wrap.
+- **`actionsReveal="hover"`** (default `'always'`) is for quiet view-mode headers: the actions are transparent until the card is hovered or holds focus (`:focus-within`, so Tab into the card reveals them), and stay shown while a menu launched from them is open. They are hidden with opacity only: they keep their layout width (the title and meta do not jump) and stay in the tab order. On touch / `(hover: none)` they are always visible.
+- **`meta`** is secondary, non-interactive header text (freshness such as "Updated 3 minutes ago", or status). It sits just before `actions`, muted and on one line, and yields first in a narrow cell: it truncates with an ellipsis, then hides visually (screen readers still read it) once only a sliver is left, before the title gives up any width, while `actions` keeps its width. For `standard` / `list` / `stats` it also describes the body region (`aria-describedby`). If the text matters when truncated, repeat it in the refresh button's tooltip.
+
+#### When NOT to use
+
+- ❌ A generic content card outside a dashboard → `<Card>`.
+- ❌ A standalone stat with no grid cell → `<Card>` with your own layout.
+- ❌ A placeholder in a widget catalog → `<WidgetPreview>`.
+
+#### Anti-patterns
+
+- ❌ `actionsReveal="hover"` when the only way to reach an essential action is that header. Touch users see it, but mouse users get no visible cue; keep primary actions visible.
+- ❌ Wrapping `DashboardWidget` in another `Card`. It already is one.
+- ❌ Freshness or status text in `actions`. `actions` never shrinks, so the title gets crushed in a narrow cell; use `meta`.
+- ❌ Buttons or links in `meta`. They can be truncated out of reach; controls go in `actions`.
+- ❌ `standard` for a `StatGroup` KPI strip in a 3-row widget: the roomy padding leaves no slack and the strip scrolls. Use `stats`.
+- ❌ Passing `value` / `trend` to `standard`, `list`, `chart` or `stats`. They are ignored; put content in `children`.
+- ❌ Rendering your own `Skeleton` in `children` instead of `loading`. You lose the variant-matched shape, the hidden "Loading..." text and `aria-busy`.
+- ❌ Adding a live region (`role="status"`, `aria-live`) to each widget while loading.
+- ❌ Relying on direction-derived colour when up is bad. Set `sentiment`.
+- ❌ A scrolling or fixed-height wrapper inside a `kpi` / `chart` body. The cell is the size; size the plot at `height: 100%`.

package/docs/components/DataTable.md

@@ -0,0 +1,88 @@
+# `<DataTable>` — server-driven data table with column features
+
+- The table owns its polite live region; do not wrap it in another — two regions would fire for one event.
+
+```tsx
+const instance = useDataTable<Deal>({
+  data,
+  columns,
+  getRowId: (r) => r.id,
+  enableRowSelection: true,
+  sort,
+  onSortChange: setSort,
+});
+
+<Cluster>
+  <ColumnVisibilityTrigger instance={instance} />
+</Cluster>
+<DataTable instance={instance} aria-label="Deals" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `instance` | `DataTableInstance<T>` | yes |  |
+| `density` | `'comfortable' \| 'dense'` | no |  |
+| `striped` | `boolean` | no |  |
+| `hover` | `boolean` | no | Hover highlight on body rows. Defaults TRUE (DataTable rows are usually interactive). |
+| `bordered` | `boolean` | no |  |
+| `loading` | `boolean` | no | Marks the table busy. Empty tables show skeleton rows; populated tables keep their rows mounted during a refetch so focus and local row state are preserved. Defaults to `false`. Announced from a polite live region the table owns, gated on the SKELETON rather than on this prop: a load shorter than `skeletonDelay` shows nothing and so says nothing, and a refetch over rows already on screen is silent because nothing visibly changes. The resolution is announced too — "Rows loaded" or "No rows loaded". `aria-busy` is also set, but reaches no screen reader on its own. |
+| `loadingRowCount` | `number` | no | Number of skeleton rows when `loading`. Defaults 10. |
+| `skeletonDelay` | `number` | no | Milliseconds to wait before showing skeleton rows for an empty initial load. Defaults to `0`; fast loads that finish inside the delay never show a skeleton. |
+| `skeletonMinDuration` | `number` | no | Minimum milliseconds skeleton rows remain visible after appearing. Defaults to `0`. Arriving rows and the empty state remain hidden until the visual tail finishes. `aria-busy` still follows actual `loading`, not the skeleton's visual tail. |
+| `emptyState` | `ReactNode` | no | Element shown when `data` is empty and not loading. Defaults to a stock <EmptyState>. |
+| `collapseBelow` | `'sm' \| 'md' \| 'lg'` | no | Stacks responsive data cells below this container-query breakpoint: `sm` (480px), `md` (640px), or `lg` (768px). Selection, expansion, sorting, row actions, and column visibility remain usable. Column sizing, pinning, and ordering state is retained, but resize/reorder controls and sticky pin presentation are unavailable while stacked and return after widening. This adds a wrapper with `container-type: inline-size`, so the breakpoint measures the table's available container width, not the viewport. Avoid an intrinsic-width parent such as `width: max-content`: inline-size containment can make the wrapper contribute zero intrinsic width there. |
+| `aria-label` | `string` | no | Required for a11y when no caption is provided. |
+| `caption` | `ReactNode` | no |  |
+| `dragWholeColumn` | `boolean` | no | Drag the whole column while reordering, not just its header cell. Default `true` — the dragged column's body cells travel with its header, and every column the drag displaces shifts its body cells too, so the header row and the body never disagree mid-drag. Costs one CSS-variable write per shifted column per frame; the cells move on the compositor, so the table body is not re-rendered during pointer movement. It does cost two full body reconciliations per drag — one at drag start, one at drag end — because the drag-active flag is component state and body rows are not memoized; that is the number to weigh for a very large table. Set `false` for the cheaper preview: only the dragged header cell follows the pointer and the body stays put until drop. Worth it for very large tables on low-end hardware, or to restore the previous behavior. Pinned columns never move under either setting — they are excluded from reordering entirely. The two settings also differ on **what a release means when no unpinned slot is under the column** — over a pinned column, or off the table entirely. Default: the drop commits the slot the preview is showing. The opt-out: the drop is discarded, because dnd-kit's own preview retracts (the header snaps back home) in that situation, and a commit would contradict it. See `docs/components/DataTable.md`, the column-drag bullet. |
+| `className` | `string` | no |  |
+
+<!-- props:end -->
+
+- Config-driven via `columns: ColumnDef<T>[]`. Each column has a stable `id` used as the key for all per-column state.
+- **Column header names.** The `<th>` is named by the label span's content — the header text — so the resize handle is never folded into it. The one override: a header that renders no TEXT OF ITS OWN — a ReactNode, a render function, or `''` — is named by `visibilityLabel` when you set one. So `header: <strong>Revenue</strong>` announces "Revenue", and adding `visibilityLabel="Revenue (USD)"` makes it announce "Revenue (USD)". That is a name-vs-label mismatch, and a WCAG 2.5.3 one only when `sortable` makes the label a button — 2.5.3 is scoped to user interface components, and it is violated only when the label does not CONTAIN the visible text, so "Revenue (USD)" over "Revenue" passes. Accepted because the alternative — a runtime measurement deciding which source names the header — produced UNNAMED column headers ten separate times before it was deleted. A string header that renders text is always named by that text; `visibilityLabel` does not override it. `header: ''` is not such a string: it renders nothing, so the label wins, which is what the trailing row-actions column wants. `column.id` is used for nothing a user hears — not the header, not the drag grip, not the resize handle. What such a header announces, measured off Chromium's AX tree: an `aria-labelledby` resolving to no text is marked INVALID, not treated as a name, so naming falls through to the cell's contents — the drag grip, or under `collapseBelow` the resize handle's live pixel width. `header: ''` is special-cased to a generic "Unlabelled column" so the width cannot win; a ReactNode rendering nothing is indistinguishable from one that names itself, so it is not. Either way it is not a name you chose, so set `visibilityLabel` on every text-less header. That is a change from before the fix, where such a header WAS named — from content, which swept in the resize handle, so it announced the handle's label, `column.id` when the column had nothing better. That name was the bug, not a feature worth preserving. (The "Resize … column" wrapper came with that fix; before it the handle's label was the bare identifier.) There is no dev warning for it: nothing static can tell a node that names itself (`<strong>Revenue</strong>`) from one that does not (an icon), so a warning fired on the commonest valid shape and was removed. Give any non-text header a `visibilityLabel`.
+- **Responsive rows:** `collapseBelow="sm" | "md" | "lg"` re-templates rows as labelled cards based on the DataTable container. Labels use `visibilityLabel`, then a string `header`; give non-text headers a `visibilityLabel` when a visible card label is required. Plain non-sortable string headers leave the compact strip, while React-node and render-function headers remain because they may contain controls. Sorting, selection, expansion, row actions, and `ColumnVisibilityTrigger` remain available. Column sizing, pinning, and ordering state is retained while stacked, but resize/reorder controls and sticky pin presentation are unavailable until the table widens again. Give the table concrete available width because inline-size containment has no intrinsic-width contribution.
+- All state pieces (column order/sizing/visibility/pinning, row selection/expansion, sort) follow the Radix controlled/uncontrolled pattern: `value` + `onValueChange`, OR `defaultValue` only, OR neither.
+- Server-driven sort/search/pagination. DataTable does NOT transform data — `data` must be the server's pre-sorted, pre-paginated slice. `onSortChange` is your trigger to refetch.
+- `enableRowSelection: true` adds a leading checkbox column with select-all (indeterminate when partial). `toggleAllOnPage` ignores `pinnedRows`.
+- Drag-to-reorder is keyboard-accessible (Tab to grip → Space to pick up → ←/→ to move → Space/Enter to drop → Esc to cancel). The grip is hover-revealed on desktop.
+- Resize via the right-edge handle. Without `collapseBelow`, the legacy keyboard path stays on a focused sortable header label: `←`/`→` for −/+8px; Shift+`←`/`→` for ±32px. With `collapseBelow`, the wide presentation exposes a dedicated focusable resize separator with the same keys; the separator and resize interaction are unavailable while stacked and return after widening.
+- `ColumnVisibilityTrigger` is the only built-in companion. For column pinning UI (Phase 2 ships state, no built-in UI), wire your own using `instance.pinColumn(id, side)`.
+- **Phase 2 ships pinning rendering.** `columnPinning` now applies sticky CSS with cumulative offsets and an inside-edge shadow; `pinnedRows` renders in a separate `<tbody>` above the main body. The selection auto-column is auto-left-pinned at offset 0. Pinned columns are LOCKED in place — no drag grip, can't be reordered. Their sort still works. Declare initial pinning either on the hook (`defaultColumnPinning: { left: ['name'], right: ['actions'] }`) or directly on each column (`pin: 'left' | 'right'`); the hook prop wins when both are set. **Phase 3 ships expandable rows.** Pass `renderExpandedRow: (row) => ReactNode` to add a per-row chevron auto-column at the left edge. Clicking the chevron toggles a detail row beneath the main row, spanning all columns. ARIA-wired with `aria-expanded` + `aria-controls`. The chevron auto-column is sticky-left like the selection cell; when both are enabled, selection is first and expand is second. DataTable is now feature-complete per the original spec.
+- **Cell content is single-line + ellipsized by default.** DataTable's internal table uses `table-layout: fixed` so column widths from `ColumnDef.size` (or runtime `columnSizing`) are authoritative, and every cell gets `overflow: hidden; text-overflow: ellipsis; white-space: nowrap`. Wide content truncates with `…` at the column boundary; the column does NOT expand to fit. If you need multi-line cells, render `<Table>` directly — DataTable is opinionated here so pinning offsets stay pixel-correct.
+- **A column drag commits wherever the preview parked it** — however far the pointer roams, including over a pinned column or clear off the table. There is no "outside" to release into: the column is clamped to the unpinned band, so the preview is always showing a real slot and the drop honors it. This deliberately differs from `Kanban`, where releasing outside the columns cancels — there the pointer can genuinely aim somewhere else. **Escape is the only cancel.** The `dragWholeColumn={false}` opt-out is the exception: its preview is dnd-kit's own and RETRACTS (the header snaps home) when no unpinned slot is under the column, so a release there is discarded — matching what that preview shows.
+
+**When NOT to use:**
+
+- A static read-only table without column features — use `<Table>` directly.
+- Huge datasets (10k+ rows on screen at once): rows are not virtualized, so it gets slow.
+- Excel-like cell editing or cell selection — out of scope; compose it yourself.
+
+**Anti-patterns:**
+
+- ❌ Mutating `columns` array identity on every render. `useDataTable` captures `defaultColumnOrder` from `columns` once at mount — later identity changes don't trigger a re-derive of the default order. Use a stable reference (`useMemo` or module-level).
+- ❌ Client-sorting `data` AND passing `sort` controlled. Pick one — server is the canonical source. Spinning both means rows reorder twice and ghost-rows appear during fetches. `data` is the server's pre-paginated, pre-sorted slice.
+- ❌ Rolling your own column visibility UI when `ColumnVisibilityTrigger` does the job. The built-in handles the "last column" guard for you.
+- ❌ Using `<Table>` directly when you want any of: ordering, sizing, visibility, selection, sort indicator wiring. Compose `<DataTable>` instead — the primitive `<Table>` is for static read-only views.
+- ❌ Putting interactive controls in `renderExpandedRow` that need to participate in row selection or row click. The detail row is its own `<tr>`, not part of the main row — `onRowClick` doesn't fire from inside it (by design), and `rowSelection` only tracks main-row checkboxes.
+- ⚠ Pinned rows (passed via `pinnedRows`) ALSO render a chevron when `renderExpandedRow` is set — they're expandable just like main-body rows. Decide whether your starred/anchored rows should reveal detail; if not, omit `renderExpandedRow` or filter `expandedRows` state in the consumer to ignore pinned-row ids.
+
+#### `<ColumnVisibilityTrigger>`
+
+Companion for `<DataTable>`: a ghost Button trigger plus a DropdownMenu of CheckboxItems, one per column where `enableHide !== false`. When only one hidable column is visible its item renders disabled, so the table can never reach a zero-column state. Pass the same `instance` to both `<DataTable>` and `<ColumnVisibilityTrigger>` so visibility state stays in sync.
+
+```tsx
+// Custom label + right-aligned menu
+<ColumnVisibilityTrigger instance={instance} label="Manage columns" align="end" />
+
+// Icon-only trigger
+<ColumnVisibilityTrigger instance={instance} label={null} />
+```
+
+- When NOT to use: you want a different visibility UI (a settings drawer, a multi-select combobox, a Popover with column grouping) — build it against `instance.columns`, `instance.columnVisibility` and `instance.toggleColumnVisibility`; or every column has `enableHide: false` (the menu would be empty — don't render it).
+- ❌ Passing a different `instance` to the trigger than to `<DataTable>`: visibility changes in one won't reflect in the other.
+- ❌ Rendering it when every column has `enableHide: false` — check `instance.columns` first and suppress the trigger.

package/docs/components/DatePicker.md

@@ -0,0 +1,68 @@
+# `<DatePicker>` — single-date input + popover
+
+```tsx
+const [value, setValue] = useState<Date | null>(null);
+<DatePicker value={value} onChange={setValue} min={new Date()} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `Date \| null` | no | Selected date. `null` = no value. Pair with `onChange` for controlled use. |
+| `defaultValue` | `Date \| null` | no | Initial selected date for uncontrolled use. |
+| `onChange` | `((date: Date \| null) => void)` | no | Fires when the value changes. |
+| `locale` | `string` | no | Override locale (otherwise reads `useLocale()`). |
+| `min` | `Date` | no | Earliest selectable date (inclusive, day-granular). Gates both the grid and typed input. |
+| `max` | `Date` | no | Latest selectable date (inclusive). |
+| `isDateDisabled` | `((date: Date) => boolean)` | no | Per-date disable callback; applied per grid cell and to parsed typed input. |
+| `clearable` | `boolean` | no | Show the ✕ clear button when a value is set. Defaults to `true`. |
+| `invalid` | `boolean` | no | Toggle red border + focus ring + `aria-invalid="true"`. Pair with a visible error and `aria-describedby`. |
+| `name` | `string` | no | Form name. When set, renders a hidden mirror `<input>` with the ISO date so native `<form>` submission works. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Field height + type scale. Same scale as `<Input>`. Defaults to `'md'`. Affects only the trigger row; the popover month grid is fixed-size. - `'sm'` — 24px tall. - `'md'` — 32px tall (default). - `'lg'` — 40px tall. |
+| `granularity` | `'day' \| 'minute'` | no | Picker precision. - `'day'` (default) — date only; behavior unchanged from prior releases. - `'minute'` — adds a manual-entry time input below the calendar grid. The trigger text shows `HH:mm` after the date. The hidden form mirror (when `name` is set) emits ISO local datetime (`2026-05-28T14:30`). Time is preserved across date re-picks. Picking from a `null` value defaults the time to `00:00`. In `'minute'` mode picking a day keeps the popover open and moves focus to the time input; Enter there (or Escape / outside click) closes it. |
+| `timeStep` | `number` | no | Minutes step for the `<TimeField>` popover and for rounding typed time input on commit. Defaults to `15`. Set `1` to disable rounding. Only meaningful when `granularity='minute'`. |
+| `hourCycle` | `'12' \| '24' \| 'auto'` | no | Display cycle for the embedded `<TimeField>` + the trigger's time tail. - `'24'` — `"HH:mm"` in the trigger; 24h hour list in the time popover. - `'12'` — `"h:mm AM/PM"` in the trigger; 12h hour list + AM/PM column. - `'auto'` (default) — derives from the active locale via Intl. en-US → `'12'`; ru-RU / de-DE / fr-FR → `'24'`. Only meaningful when `granularity='minute'`. Typed input is lenient regardless of cycle — both `"14:30"` and `"2:30 PM"` parse on blur. |
+| …native | | | plus native `<input>` attributes |
+
+<!-- props:end -->
+
+- Single-date selection (date-only by default; opt into date+time with `granularity="minute"`). Range → `<DateRangePicker>`. Year-picker — out of scope for v1.
+- Looks like an `<Input>`. Click the input or press ArrowDown to open the popover. The 📅 button toggles and the ✕ button clears; clicking either never moves focus while it's in the field or the open popover, so half-typed trigger text survives the toggle and is discarded by clear. Reaching them by keyboard (Tab) leaves the input first, which commits the typed text. Toggling closed from inside the popover commits a time typed into the time input and returns focus to the input; clear from there wins over the typed time (one `onChange(null)`).
+- Typed input parses on Enter, or when focus leaves the field — ArrowDown into the open calendar, an outside click, or Tabbing away (Tab from the trigger goes ✕ → 📅 → the page; the portaled calendar is reached with ArrowDown) — using the active locale: en-US `M/D/YYYY`, ru-RU `D.M.YYYY`, ja-JP `Y/M/D`. ISO `YYYY-MM-DD` is always accepted as a paste fallback. Unparseable / out-of-range / disabled input reverts to the last committed value.
+- Locale-aware via `useLocale()`; override with `locale` prop. UI strings (previousMonth / nextMonth / openCalendar / clear) translate via `datePicker.*` keys — override with `<I18nProvider overrides={{ datePicker: { ... } }}>`.
+- ARIA: typed input has `aria-haspopup="dialog"` + `aria-expanded`. Popover wrapper is `role="dialog"` (labelled by `aria-label={t('datePicker.openCalendar')}`); the grid inside is `role="grid"` with `role="gridcell"` buttons that carry `aria-selected` / `aria-disabled` as appropriate.
+- Keyboard inside the grid: ←→↑↓ move focus by 1 day, Home/End to start/end of week, PageUp/PageDown step a month, Enter/Space selects, Escape closes and returns focus to the input. Tab / Shift+Tab out of the popover closes it and returns focus to the input (both granularities).
+- **Granularity.** Pass `granularity="minute"` to add a `<TimeField>` below the calendar grid; the trigger text becomes `MM/DD/YYYY HH:mm` (24h locales) or `MM/DD/YYYY h:mm AM/PM` (12h locales) and the hidden form mirror emits ISO local datetime (`2026-05-28T14:30`). Defaults to `'day'` (backward compat — date-only). Picking a different date re-uses the existing time-of-day, so the grid feels like it "just changes the date"; picking from `null` defaults to `00:00`. Picking a day does NOT close the popover in minute mode: focus moves to the embedded time input so the time is reachable; Enter in the time input (with its clock closed) or Escape closes it and returns focus to the trigger input; an outside click closes it and leaves focus where the user clicked; Tabbing out of the popover closes it and returns focus to the trigger input, so the next Tab continues in page order. Every close path keeps a date typed into the trigger and a time typed into the time input. The `<TimeField>` accepts free text (parsed on blur / Enter via `parseTime` — both 24h and AM/PM shapes) AND a chevron-toggled popover with hour + minute (+ AM/PM in 12h mode) lists, plus a "Now" footer button. `timeStep` (default `15`, in minutes) controls the minute-list row count AND rounds typed input in the time field on commit; set `timeStep={1}` to disable rounding. The trigger text-input parses exactly as typed — `timeStep` does not round trigger input. `hourCycle` (default `'auto'`) forwards to the embedded TimeField and controls the trigger text — `'12'` / `'24'` force a cycle, `'auto'` derives from locale (en-US → 12h, ru-RU → 24h).
+
+```tsx
+// Uncontrolled, today as the default
+<DatePicker defaultValue={new Date()} onChange={(d) => console.log(d)} />
+
+// Constrained
+<DatePicker
+  value={value}
+  onChange={setValue}
+  min={new Date()}
+  isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
+/>
+
+// Form integration via the hidden mirror
+<form action="/dates"><DatePicker name="dob" /></form>
+```
+
+The popover is portaled into `document.body`, so it escapes overflow-hidden ancestors.
+
+#### When NOT to use
+
+- Datetime with seconds precision: only `granularity="minute"` is supported; compose with a separate input.
+- Time-only fields (no date): out of scope.
+- Free-form date strings without a clear locale: use a plain `<Input>`.
+
+#### Anti-patterns
+
+- ❌ Wrapping the picker in `<label htmlFor={id}>` while also passing `aria-label` — pick one. The wrapper label is preferred.
+- ❌ Using `value` without `onChange` and expecting state to update on user input — the picker is fully controlled when `value` is passed.