# garn — full component reference

> The complete, machine-readable reference for every garn component, concatenated from the
> canonical ComponentInfo source. Each section is one component.

Generated for AI consumption. Components: accordion, activity-grid, alert-dialog, alert, app-shell, aspect-ratio, avatar, badge-select, badge, bar-list, board, breadcrumb, bullet, button-group, button, calendar, card, carousel, chart, checkbox, collapsible, combobox, command, context-menu, counter, data-list, date-picker, date-time-picker, dialog, drawer, dropdown-menu, empty, field, file-upload, filters, form, gallery, gantt, gauge, heatmap, hover-card, inline-edit, input-otp, input, kbd, label, list, menubar, multi-select, navigation-menu, number-field, pagination, popover, progress, radio-group, rating, resizable, scheduler, scroll-area, select, separator, sheet, skeleton, slider, sonner, sortable, sparkline, spinner, stat, stepper, switch, table, tabs, tag, textarea, time-field, time-picker, timeline, toggle-group, toggle, toolbar, tooltip, tracker, tree.

---
# Accordion

> Stacked, collapsible sections that show one panel's content at a time (or several).

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** disclosure
- **Import:** `import { Accordion } from "@garn/ui/accordion"`

## Overview
Accordion lets users expand and collapse stacked sections to manage long content — FAQs, settings groups, nested details. `Accordion` sets `type` (`single` for one-open-at-a-time, `multiple` for independent toggles); each `AccordionItem` pairs an `AccordionTrigger` header with a collapsible `AccordionContent`. Use it to tame a long single page; for switching between peer views use Tabs, and for one isolated show/more region use Collapsible.

## When to use
Let users expand/collapse sections to manage long content — FAQs, settings groups, nested details.

## When not to use
Switching between peer views where only one is ever relevant (use tabs); a single open/close region (use collapsible).

## Do / Don't
- ✅ Give every AccordionItem a unique `value`.
- ✅ Use `type="single" collapsible` for FAQ-style one-at-a-time; `type="multiple"` when several can stay open.
- ✅ Put the trigger text in the heading so it reads as a real section header.
- ❌ Don't nest the primary navigation in an accordion — it hides wayfinding.
- ❌ Don't use an accordion when all content should be visible at once.

## Guidelines
**Reach for an accordion only when content is genuinely long.** Collapsing a handful of short items adds clicks for no gain — show them outright. It shines when scanning headers first, then drilling into one section, is the natural flow (an FAQ).

**Choose `single` vs `multiple` deliberately.** `single` keeps focus on one section and a tidy page; `multiple` lets users compare sections side by side. Write headers that summarize their panel so the collapsed list is itself scannable.

**Keep triggers as headings and don't hide essentials.** The trigger sits in a real heading for navigation, and `aria-expanded` reflects state — don't bury required form fields or critical info inside a collapsed panel a user might never open.

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string | string[] — The open item id(s). `type="single"` ⇒ string (+ `collapsible` to allow closing all); `type="multiple"` ⇒ string[].

## Anatomy

**Parts**
- `Accordion` (`accordion`) · required: Root — sets `type` (single | multiple) and owns the open `value`.
- `AccordionItem` (`accordion-item`) · required: One section; needs a unique `value`.
- `AccordionTrigger` (`accordion-trigger`) · required: The header button that toggles its item (rendered inside a heading).
- `AccordionContent` (`accordion-content`) · required: The collapsible panel body.

## Accessibility
- **Role:** button (APG: accordion)
- **Enter / Space:** Toggle the focused section.
- **Tab:** Move between triggers and into open content.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- Each trigger is a <button> inside a heading; aria-expanded + aria-controls link it to its panel.
- **Focus:** Trigger shows a focus ring; reduced-motion softens the expand/collapse.

## Tokens
- `triggerMinHeight` → `--garn-control-h-lg` (air)
- `chevronMotion` → `--garn-motion-fast`

## Related
- **composes** → `utils`
- **alternativeTo** → `collapsible` (when there is only one independent open/close region)
- **alternativeTo** → `tabs` (when the sections are peers and only one should show at a time)

## Recipes
- **faq** — A frequently-asked-questions list — one answer open at a time. _(use when presenting Q&A or progressively-disclosed help)_

## Gotchas
- **TypeScript error or nothing toggles.** — `type` is required on the Accordion root, and each AccordionItem needs a unique `value`. → Set `type="single"` (with `collapsible`) or `type="multiple"`, and give each item a unique value.

## Examples
- **basic** (canonical): Single-open FAQ accordion.
- **multiple** (playground): Several panels open at once.

---

# Activity Grid

> A grid of intensity-shaded cells showing activity or frequency over time (a contribution graph).

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { ActivityGrid } from "@garn/ui/activity-grid"`

## Overview
Activity Grid is the contribution-graph widget — a compact grid where each cell's shade encodes how much happened that day (commits, logins, events). It bins values into a few intensity levels and lays cells out column-major (weeks as columns), giving the familiar at-a-glance density map. Pure CSS grid, so it renders on the server with no engine.

## When to use
Show activity/frequency density over time as a calendar-style grid (contributions, logins, streaks).

## When not to use
A labelled value matrix with row/column axes (use Heatmap); a numeric trend line (use Sparkline).

## Do / Don't
- ✅ Give it an `aria-label` summary; set per-cell `label` for the hover title.
- ✅ Tune `levels` and `max` to the data's range.
- ❌ Don't expect exact counts to be readable from shade alone.
- ❌ Don't use unrelated colours per cell — intensity is one hue.

## Guidelines
**Bin, don't scale precisely.** The grid shows relative intensity across a few `levels`, not exact counts — pair it with a total or a hover `title` for the real number.

**One hue, stepped opacity.** Cells tint a single `--garn-chart-*` token at increasing opacity; empty cells are muted. That keeps the density readable; don't map cells to unrelated hues.

**Summarise for assistive tech.** It's one `role=img` — give it an `aria-label` stating the span and takeaway; per-cell detail lives in the `title`.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string` | — | no | Cell tint (token ref); empty cells use `bg-muted`. |
| `items` | `ActivityCell[]` | — | yes |  |
| `levels` | `number` | — | no | Intensity buckets incl. the empty level (default 5 → empty + 4 shades). |
| `max` | `number` | — | no | Value mapped to the highest intensity (default: the largest value). |
| `rows` | `number` | — | no | Grid rows; cells fill column-major (default 7 — days of a week). |

_Plus 278 inherited native `<div>` attributes._

## Anatomy
- `activity-grid`: The grid (role=img); cells fill column-major over `rows` rows.
- `activity-cell`: One day/bucket; `data-level` + a hover `title`. Empty = `bg-muted`; higher levels = stepped opacity of the token.

## Accessibility
- **Role:** img
- **WCAG:** 1.1.1 Non-text Content (A)
- role=img with an `aria-label` summary (e.g. "Activity — last 13 weeks").
- Each cell carries a hover `title` and reflects its bucket via `data-level`.
- Intensity is stepped opacity of a `--garn-chart-*` token; empty cells use `bg-muted`.

## Related
- **composes** → `utils`
- **alternativeTo** → `heatmap` (when the data needs labelled row/column axes (a value matrix))

## Gotchas
- **Everything looks the same shade.** — `max` too low/high, or too few `levels` for the range. → Omit `max` to auto-scale to the peak; raise `levels` for more contrast.

## Examples
- **basic** (canonical): 13 weeks of activity in stepped intensities.

---

# Alert Dialog

> A modal that interrupts to force an explicit confirm/cancel decision.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { AlertDialog } from "@garn/ui/alert-dialog"`
- **Polymorphism:** `asChild`

## Overview
AlertDialog forces an explicit decision before continuing — confirming a destructive or irreversible action like delete, discard, or sign out. Unlike Dialog, `AlertDialogContent` has no dismiss-X and ignores outside-click: the only way out is the `AlertDialogAction` (confirm) or `AlertDialogCancel` (which takes initial focus). Use it sparingly, only when proceeding has real consequences; for a routine form or message, a Dialog is right, and for a non-blocking confirmation a Sonner toast with Undo is often kinder.

## When to use
Force an explicit decision before continuing — confirming a destructive or irreversible action (delete, discard, sign out).

## When not to use
A non-blocking message or a routine form (use dialog); a transient status (use a toast); contextual info near a control (use popover).

## Do / Don't
- ✅ Always include an AlertDialogTitle and an AlertDialogDescription that states the consequence.
- ✅ Use AlertDialogAction for the confirm and AlertDialogCancel for the safe out; let Cancel keep initial focus.
- ✅ Style a destructive confirm's Action with the destructive intent.
- ❌ Don't use an alert-dialog for ordinary, non-destructive tasks — that's a dialog.
- ❌ Don't make Escape or overlay-click silently confirm — closing must be Cancel-safe.
- ❌ Don't omit the description; 'Are you sure?' alone doesn't state the stakes.

## Guidelines
**Reserve it for consequential, irreversible actions.** If the action is easily undone, prefer an optimistic update with an Undo toast over interrupting the user. Overusing alert dialogs for harmless steps trains people to confirm on reflex.

**Name the consequence, not the mechanism.** The `Title` + `Description` should state what will happen ("Delete 3 files? This can't be undone"), and the action button should name the act ("Delete", not "OK"). Match the button's tone to the risk — destructive confirms read as `danger`.

**Make Cancel the safe default.** Initial focus lands on Cancel and Escape cancels, so an accidental Enter never destroys anything. Keep the choice binary and the copy short — this is a decision point, not a place for extra fields.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen` (or just an AlertDialogTrigger).
- Selection: single.

## Anatomy

**Parts**
- `AlertDialog` · required: Root — owns the open state. No DOM of its own.
- `AlertDialogTrigger` (`alert-dialog-trigger`): Opens the dialog (asChild to wrap your own button).
- `AlertDialogContent` (`alert-dialog-content`) · required: Focus-trapped surface (portals its own overlay). No dismiss-X — closing is explicit.
- `AlertDialogTitle` (`alert-dialog-title`) · required: Accessible name for the dialog (required; sr-only if visually hidden).
- `AlertDialogDescription` (`alert-dialog-description`): The consequence text, wired to aria-describedby.
- `AlertDialogHeader` (`alert-dialog-header`): Layout wrapper for title + description.
- `AlertDialogFooter` (`alert-dialog-footer`): Layout wrapper for the actions (right-aligned on ≥sm).
- `AlertDialogAction` (`alert-dialog-action`) · required: The confirm button (styled primary via buttonVariants).
- `AlertDialogCancel` (`alert-dialog-cancel`) · required: The cancel button (styled outline); initial focus lands here.

## Accessibility
- **Role:** alertdialog (APG: alertdialog)
- **Escape:** Cancel and close (treated as the Cancel action).
- **Tab / Shift+Tab:** Cycle focus within the dialog (focus is trapped).
- **Enter:** Activate the focused action button.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.3 Focus Order (A); 4.1.2 Name, Role, Value (A)
- role=alertdialog + aria-modal; labelled by AlertDialogTitle and described by AlertDialogDescription.
- Initial focus lands on Cancel; focus returns to the trigger on close.
- Unlike dialog, clicking the overlay does NOT dismiss it — the choice is explicit.
- **Focus:** Focus trapped inside the content, initially on Cancel; returns to the trigger on close.
- **Contract (warn):** Every AlertDialogContent must contain an AlertDialogTitle (wrap it in sr-only to hide it visually). — _when AlertDialogContent has no AlertDialogTitle_

## Tokens
- `padding` → `--garn-pad-surface` (air)
- `gap` → `--garn-gap-stack` (air)
- `headerGap` → `--garn-gap-field` (air)
- `motion` → `--garn-motion-fast`

## Related
- **composes** → `utils`
- **composes** → `button`
- **alternativeTo** → `dialog` (when the task isn't a forced, consequential choice)
- **pairsWith** → `button` (when as the trigger that opens it)

## Recipes
- **destructive-confirm** — An irreversible action gated behind an explicit confirmation. _(use when irreversible || bulk-delete, unless trivially-undoable)_

## Gotchas
- **Screen readers can't name the dialog / a console warning about a missing title.** — AlertDialogContent without an AlertDialogTitle (Radix requires it). → Add an AlertDialogTitle (sr-only if you don't want it visible) and an AlertDialogDescription.
- **Users dismiss the prompt by clicking outside and nothing is confirmed — as intended, but surprising if you expected dialog behavior.** — alert-dialog deliberately does not close on overlay click; only Action/Cancel/Escape resolve it. → If you want overlay-click dismissal, you want a dialog, not an alert-dialog.

## Examples
- **basic** (canonical): Destructive delete confirmation.

---

# Alert

> An inline banner that calls out a status or important message.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** feedback
- **Import:** `import { Alert } from "@garn/ui/alert"`

## Overview
Alert calls out a persistent, inline status or message in the page flow — a form-level error, an info notice, a success summary. The `tone` sets the intent (info / success / warning / danger), with an optional leading icon, an `AlertTitle` headline, and an `AlertDescription` body. It stays in the layout where the user can re-read it; for a transient confirmation that auto-dismisses use a Sonner toast, and for a blocking decision use an AlertDialog.

## When to use
Call out a persistent, inline status or message in the page flow — a form-level error, an info notice, a success summary.

## When not to use
A transient, auto-dismissing notification (use sonner/toast); a blocking confirm (use alert-dialog); a per-field validation message (wire it to the field via form).

## Do / Don't
- ✅ Pair a status tone with a text label and an icon — never color alone.
- ✅ Use AlertTitle for the headline and AlertDescription for detail.
- ✅ Reserve `danger` for genuine errors; use info/success/warning for non-error status.
- ❌ Don't use an Alert for transient toasts — that's sonner.
- ❌ Don't rely on the icon/color to carry meaning without text.
- ❌ Don't leave an empty Alert mounted (role=alert announces on change).

## Guidelines
**Match the tone to the real severity.** Reserve `danger` for genuine errors and `warning` for things that need attention before proceeding; crying wolf with red banners makes people tune them out. One alert per concern beats a stack of competing ones.

**Say what happened and what to do.** A useful alert names the problem and the next step ("Card declined — try another payment method"), not just "Error". Put a recovery action right in the alert when there's an obvious one.

**Place it where the cause is, and announce it.** Form-level errors belong at the top of the form or beside the field; the `role=alert` means it's announced when it appears, so don't render it pre-emptively. Pair color with an icon and text so the meaning survives without color.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tone` | `"danger" \| "info" \| "neutral" \| "success" \| "warning"` | `neutral` | no |  |

_Plus 280 inherited native `<div>` attributes._

## Variants
- **tone** (default `neutral`): `neutral`, `info`, `success`, `warning`, `danger`

## Anatomy

**Parts**
- `Alert` (`alert`) · required: The banner (role=alert); carries the `tone`. An optional leading <svg> is absolutely positioned.
- `AlertTitle` (`alert-title`): The short headline (an <h5>).
- `AlertDescription` (`alert-description`): The supporting body text.

## Accessibility
- **Role:** alert
- **WCAG:** 1.4.1 Use of Color (A); 1.4.3 Contrast (Minimum) (AA); 4.1.3 Status Messages (AA)
- The container is role=alert — assistive tech announces its text when it appears, so render it when there's something to say (don't keep an empty one mounted).
- Don't encode status by color alone — keep a clear text label; pair the icon with AlertTitle/AlertDescription.

## Related
- **composes** → `utils`
- **alternativeTo** → `sonner` (when the message is transient and should auto-dismiss)
- **alternativeTo** → `alert-dialog` (when the user must stop and make an explicit choice)

## Gotchas
- **A screen reader doesn't announce the alert.** — role=alert announces when the node appears/changes — mounting it empty and filling it later (or keeping it always present) can swallow the announcement. → Render the Alert at the moment there's a message, with its text already inside.

## Examples
- **basic** (canonical): Default alert with icon, title, and description.
- **variants** (playground): Status tones.

---

# App Shell

> The page-level application frame — a tinted canvas with a sidebar, content panel, and optional detail aside.

- **Status:** beta
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** layout
- **Import:** `import { AppShell } from "@garn/ui/app-shell"`

## Overview
AppShell is the top-level frame of an application screen — a dashboard, console, inbox, or records view that needs a persistent sidebar, header, and content area. `AppShell` is the root + provider (owns the `appearance`, collapse state, and the adaptive `size` class); `AppShellSidebar` holds primary nav (built from `AppShellNav` groups + `AppShellNavItem`s — collapsible rail/offcanvas inline, a drawer at the compact tier), and `AppShellContent` groups `AppShellHeader` / `AppShellToolbar` / main / footer. By default it's **adaptive**: it measures its own width and auto-rails the sidebar at medium and floats the sidebar + aside as Sheets at compact — no consumer media queries. It's the scaffold for a whole app view — for grouping content *within* a page, use Card.

## When to use
The top-level frame of an application screen — a dashboard, console, inbox, or records view that needs a persistent sidebar, header, and content area.

## When not to use
A bounded content surface inside a page (use card); a marketing/landing page (use plain layout); a single overlay task (use dialog/sheet).

## Do / Don't
- ✅ Use `appearance="framed"` for the tinted-canvas inset look; keep at most three surface levels on screen (canvas → raised → overlay).
- ✅ Put a real <nav> inside AppShellSidebar; place the AppShellTrigger in the header.
- ✅ Seed `defaultOpen` from the `app-shell:sidebar` cookie server-side to avoid a collapse flash.
- ✅ Compose ordinary garn components inside — Card, Table, Breadcrumb — they render identically in framed and flush.
- ❌ Don't bake the float into leaf components (cards, tables, tiles) — geometry lives in the shell `appearance`.
- ❌ Don't add a 4th nested surface; the hierarchy collapses.
- ❌ Don't reach for shadow to create the float — tonal step + hairline is the point.
- ❌ Don't give the sidebar its own landmark role on top of the detail Aside — keep one complementary region.

## Guidelines
**Use AppShell for the app frame, not for page sections.** It's the one persistent chrome around an authenticated product surface; don't nest shells or reach for it to box a widget (that's a Card). Keep one sidebar and one header per shell.

**Make navigation survive collapse and mobile.** When the sidebar collapses to a rail or moves into a drawer, keep nav items reachable and labelled (icons need accessible names); preserve the user's collapse preference. Provide the skip-link the shell ships so keyboard users can jump to main.

**Keep the header and toolbar earning their rows.** Put wayfinding (breadcrumb/title) and global actions in `AppShellHeader`, and view-scoped controls (filters, saved views, bulk actions) in `AppShellToolbar` — don't crowd both into one bar. Let the content area scroll independently of the chrome.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"flush" \| "framed"` | `flush` | no |  |
| `collapsible` | `"icon" \| "none" \| "offcanvas"` | `none` | no |  |
| `placement` | `"docked" \| "floating"` | `docked` | no |  |
| `adaptive` | `boolean` | — | no | Adapt the layout to the shell's own width — auto-rail the sidebar and float the aside/sidebar as Sheets on narrow. `false` pins the shell `expanded` (the pre-adaptive static behavior). Default `true`. |
| `asideOpen` | `boolean` | — | no | Controlled detail-aside open state (e.g. for a Peek that opens on row click). |
| `defaultAsideOpen` | `boolean` | — | no | Initial detail-aside open state (uncontrolled). Default open. |
| `defaultOpen` | `boolean` | — | no | Initial sidebar intent (uncontrolled). `undefined` = **auto**: the size class decides (expanded desktop, rail at medium). Seed from the `app-shell:sidebar` cookie server-side for an SSR no-flash restore. |
| `defaultSize` | `"compact" \| "expanded" \| "medium"` | — | no | Initial size class before measurement (uncontrolled). Seed from the `app-shell:size` cookie server-side to avoid a first-paint flash. |
| `mainId` | `string` | — | no | Skip-link target; must match the `id` on AppShellMain (shared default). |
| `onAsideOpenChange` | `(open: boolean) => void` | — | no |  |
| `onOpenChange` | `(open: boolean) => void` | — | no |  |
| `onSizeChange` | `(size: "compact" \| "medium" \| "expanded") => void` | — | no |  |
| `open` | `boolean` | — | no | Controlled desktop sidebar open state. Always honored (explicit intent). |
| `size` | `"compact" \| "expanded" \| "medium"` | — | no | Controlled size class — mostly observed; set it to force a tier (tests, docs). |

_Plus 280 inherited native `<div>` attributes._

### `AppShellSidebar` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `collapsible` | `"icon" \| "none" \| "offcanvas"` | — | no | Desktop collapse behavior. `icon` shrinks to a rail; `offcanvas` hides it. |

_Plus 281 inherited native HTML attributes._

### `AppShellNav` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `React.ReactNode` | — | no | Optional section heading rendered above the items; hidden on the rail. |

_Plus 280 inherited native HTML attributes._

### `AppShellNavItem` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean` | — | no | Marks the current destination: soft fill + `aria-current="page"`. |
| `count` | `React.ReactNode` | — | no | Trailing count — wrapped in a soft neutral Badge; hidden on the rail. |
| `icon` | `React.ReactNode` | — | no | Leading icon; stays centered when the sidebar collapses to a rail. |

_Plus 301 inherited native HTML attributes._

### `AppShellSelectionBar` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `clearLabel` | `string` | — | no |  |
| `count` | `number` | — | yes |  |
| `onClear` | `() => void` | — | no |  |

_Plus 281 inherited native HTML attributes._

## Variants
- **appearance** (default `flush`): `framed`, `flush`
- **collapsible** (default `none`): `none`, `icon`, `offcanvas`
- **placement** (default `docked`): `docked`, `floating`

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Desktop sidebar expanded/collapsed. Persisted to the `app-shell:sidebar` cookie; seed `defaultOpen` server-side for an SSR no-flash restore.
- `asideOpen` (controlled) / `defaultAsideOpen` (uncontrolled), `onAsideOpenChange` · boolean — Detail-aside open/closed — drives Peek (open it on a row click) and AppShellAsideTrigger. At the compact tier the aside floats as an overlay Sheet.
- `size` (controlled) / `defaultSize` (uncontrolled), `onSizeChange` · AppShellSize — The adaptive size class (compact | medium | expanded). Measured from the shell's own width (container, not viewport); mostly observed, but controllable to force a tier. Seed `defaultSize` from the `app-shell:size` cookie for an SSR no-flash restore.

## Anatomy

**Parts**
- `AppShell` (`app-shell`) · required: Root + provider: owns `appearance` (framed | flush) and the collapse state (useAppShell); renders the skip-link and the canvas.
- `AppShellSidebar` (`app-shell-sidebar`): Primary navigation region (holds a consumer <nav>). Token-mapped surface `appearance` — flush (on canvas, default) / raised (card) / recessed (dimmer) / contrast (dark, scoped) — shared with AppShellAside; `collapsible` rail/offcanvas on desktop; floats as a drawer Sheet at the compact tier.
- `AppShellNav` (`app-shell-nav`): A sidebar navigation group — the <nav> landmark that stacks AppShellNavItems. Optional `label` renders a muted section heading that hides on the rail and names the landmark (aria-labelledby) when no aria-label is given.
- `AppShellNavItem` (`app-shell-nav-item`): A sidebar nav item — composes Button with rail-collapse baked in: leading `icon` (stays centered on the rail), trailing `count` (soft neutral Badge, hidden on the rail), and `active` (soft fill + aria-current="page" + data-active). `variant`/`tone`/`asChild` pass through, so it also serves a prominent sidebar action (e.g. a brand Compose).
- `AppShellContent` (`app-shell-content`): The single panel grouping header/toolbar/main/footer — the floating raised surface in framed.
- `AppShellHeader` (`app-shell-header`): Top bar of the content panel — breadcrumb/title/actions and the AppShellTrigger.
- `AppShellToolbar` (`app-shell-toolbar`): Secondary strip under the header — saved-view tabs, filters, bulk actions.
- `AppShellMain` (`app-shell-main`): The scroll region and skip-link target (tabIndex -1).
- `AppShellFooter` (`app-shell-footer`): Optional footer of the content panel.
- `AppShellAside` (`app-shell-aside`): Right contextual region — record detail, activity, or an assistant dock; the page's single complementary landmark.
- `AppShellTrigger` (`app-shell-trigger`): Toggle button for the sidebar (aria-expanded); composes Button.
- `AppShellCommand` (`app-shell-command`): A ⌘K command palette — composes `command` in a Dialog with an accessible name; optional `/` open.
- `AppShellToolbarSpacer` (`app-shell-toolbar-spacer`): A flex-1 spacer for declarative start/end alignment inside a toolbar or header.
- `AppShellSelectionBar` (`app-shell-selection-bar`): A contextual bulk-action bar (count + actions + clear) shown when rows are selected. `placement="docked"` is a full-width strip in place of the toolbar; `placement="floating"` is a centered Floating Action Bar pill that rises in over the nearest positioned ancestor (give the content region `relative`). The count is an aria-live region.
- `AppShellAsideTrigger` (`app-shell-aside-trigger`): Toggle button for the detail Aside (aria-expanded); composes Button. Enables Peek.

## Accessibility
- **Meta / B:** Toggle the sidebar (Ctrl+B on Windows/Linux).
- **Meta / K:** Open the command palette, when AppShellCommand is used (Ctrl+K).
- **Tab:** Skip link (first stop) jumps focus to the main region.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.4.1 Bypass Blocks (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA)
- AppShell renders a visually-hidden skip-link to the main region (its id defaults to `app-shell-main`; override `mainId` + the Main `id` together).
- Landmark roles: AppShellHeader=<header>, AppShellMain=<main>, AppShellFooter=<footer>, AppShellAside=<aside> (complementary). The sidebar is a layout container — its inner <nav> is the navigation landmark — so the detail Aside stays the page's single complementary region.
- AppShellTrigger exposes aria-expanded; give it (or rely on its default) an accessible name. AppShellAsideTrigger's aria-expanded reflects the effective aside visibility (inline pane or compact overlay).
- AppShellNav is a <nav> landmark: name it with `aria-label`, or pass a `label` heading and it wires `aria-labelledby` to that heading automatically. AppShellNavItem sets aria-current="page" when `active`; an icon-only rail keeps the accessible name from the (visually hidden on rail) label.
- At the compact tier the sidebar AND the detail aside render inside Sheets/dialogs with visually-hidden titles; the aside's overlay uses a separate open state so it doesn't auto-open, while a controlled Peek still drives it.
- **Focus:** Skip-link reveals on focus and targets Main (tabIndex -1); focus-visible rings on controls are preserved.

## Tokens
- `gutter` → `--garn-space-8` (air)
- `regionPadding` → `--garn-pad-panel` (air)
- `headerGap` → `--garn-gap-inline` (air)
- `radius` → `--garn-radius` · brandable
- `canvas` → `--garn-background`
- `raised` → `--garn-card`
- `hairline` → `--garn-border`

## Related
- **composes** → `utils`
- **composes** → `button` (when AppShellTrigger / AppShellNavItem)
- **composes** → `badge` (when AppShellNavItem count)
- **composes** → `command` (when AppShellCommand (⌘K))
- **composes** → `dialog` (when AppShellCommand wrapper)
- **composes** → `sheet` (when the mobile sidebar drawer)
- **pairsWith** → `breadcrumb` (when in the header)
- **pairsWith** → `tabs` (when saved-view tabs in the toolbar)
- **slotAccepts** → `card` (when as content tiles in main)
- **slotAccepts** → `table` (when as the primary content of main)
- **slotAccepts** → `list` (when as the selectable master pane driving the detail Aside (master-detail))
- **slotAccepts** → `empty` (when as the empty-detail state in the Aside until a record is selected)
- **pairsWith** → `resizable` (when to make the panes drag-resizable (composition))

## Recipes
- **master-detail** — The three-pane master–detail: a single-select List (or Table) in Main drives the detail Aside. Selecting a row peeks the Aside open (controlled `asideOpen`) and swaps its contents; an Empty fills the Aside until a row is chosen; at the compact tier the Aside floats as an overlay Sheet — no consumer media queries. The reusable capture of the email / CRM-record / settings / file-browser layout. _(use when selecting a row or item in a list should reveal its detail in a side pane within the same view, collapsing to a single column on mobile (email client, CRM record, settings, file browser), unless the detail is a transient quicklook floated over the list (use the `peek` recipe) or a full separate route)_
- **peek** — Open a list row's detail in a sheet without leaving the list (a quicklook). _(use when a row needs an inline detail preview)_
- **command-palette** — A ⌘K command palette wired into the shell. _(use when the app has more than a handful of destinations/actions)_
- **workspace-switcher** — A workspace switcher on the sidebar brand row. _(use when the user belongs to more than one workspace/team)_

## Gotchas
- **The framed panel doesn't stand out / the canvas looks the same as the panel.** — In light mode the canvas→card step is gentle by design — the hairline border carries the separation. → Keep the `border-border` hairline; don't darken --garn-background. Use appearance="recessed" for a dimmer sidebar.
- **Skip link focuses nothing / jumps nowhere.** — The skip-link href and AppShellMain id must match. → Leave both at the default, or set `mainId` on AppShell and the same `id` on AppShellMain.
- **Two `complementary` landmarks flagged by a11y tooling.** — Making the sidebar an <aside> duplicates the detail Aside's role. → The sidebar is a layout container; put a <nav> inside it for the navigation landmark.
- **The floating selection bar sits at the page bottom instead of over the content.** — `placement="floating"` positions the pill absolutely against the nearest positioned ancestor. → Give the content/main region `relative` so the bar floats within it (the demo wraps the showcase table in a relative container).
- **At tablet width the sidebar's nav icons center but the sidebar stays full-width (a wide half-rail).** — The medium auto-rail relies on the sidebar's own rail width, which only shrinks when `collapsible="icon"` (or `offcanvas`). With `collapsible="none"` the nav items still center on the collapsed state but the panel doesn't narrow. → Give an adaptive AppShellSidebar `collapsible="icon"` so it rails cleanly at medium.
- **The layout flashes from desktop to rail/drawer on first load.** — The size class is measured on the client, so the first server paint has no width yet. → Seed `defaultSize` from the `app-shell:size` cookie server-side (the shell writes it on resize), the same way `defaultOpen` restores collapse. Or set `adaptive={false}` to pin the static desktop layout.
- **A tablet-width uncontrolled sidebar starts railed even though I expected it open.** — Adaptive default-on: with no explicit `open`/cookie, the size class decides — medium defaults to the rail. This is intended. → Pass `defaultOpen`/`open` to set an explicit intent (honored at medium/expanded), or `adaptive={false}` for the pre-adaptive always-open behavior.
- **Clicking a master-list row selects it but the detail Aside never opens, or opens empty.** — The Aside's open state and the selected record are two separate pieces of state; a bare List/Table selection updates neither the shell's `asideOpen` nor your selected-item state, and the Aside starts collapsed. → Control `asideOpen` on AppShell and, in the master list's `onSelectionChange` (or row `onClick`), set BOTH the selected record AND `asideOpen=true`; render an Empty in the Aside while nothing is selected. This is the `master-detail` recipe — copy the master-detail example rather than re-deriving the wiring.

## Examples
- **framed** (canonical): The framed/inset look: tinted canvas + one floating content panel.
- **flush** (playground): Edge-to-edge layout (the default appearance).
- **with-aside** (playground): Three-pane: a recessed sidebar, the content panel, and a detail aside.
- **resizable** (edge-case): Multi-pane composed with resizable drag handles (a pattern, not shell API).
- **adaptive** (playground): The adaptive layout: `size` pinned to medium so the sidebar auto-rails to icons (on a real compact screen the sidebar + aside float as Sheets). Composed with AppShellNav / AppShellNavItem.
- **master-detail** (playground): Three-pane master–detail: a single-select List drives the detail Aside — selecting a row peeks it open (controlled `asideOpen`) and swaps its contents, an Empty fills it until then, and on a real compact screen the aside floats as a Sheet. `size` pinned to expanded for a deterministic three-pane in the lab.

## Source map

Regions in `app-shell.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–17 (16 lines) — React, Radix, icons, shared hooks
- `utils` L18–47 (30 lines) — config constants + adaptive size resolver
- `context` L48–91 (44 lines) — lifted state context + useAppShell
- `root` L92–326 (235 lines) — AppShell: measure, reconcile intent, provide
- `sidebar` L327–435 (109 lines) — shared side-panel variants + collapsible Sidebar
- `nav` L436–546 (111 lines) — sidebar nav landmark + rail-aware items
- `aside` L547–619 (73 lines) — contextual detail Aside (overlay on compact)
- `trigger` L620–653 (34 lines) — sidebar toggle
- `aside-trigger` L654–686 (33 lines) — detail-aside toggle
- `command` L687–712 (26 lines) — ⌘K palette pass-through
- `content` L713–736 (24 lines) — framed/flush content panel
- `header` L737–751 (15 lines) — top header bar
- `toolbar` L752–781 (30 lines) — secondary strip + spacer
- `selection-bar` L782–860 (79 lines) — bulk-action bar variants + component
- `main` L861–884 (24 lines) — scroll region + skip-link target
- `footer` L885–899 (15 lines) — bottom footer bar
- `exports` L900–922 (23 lines) — public component surface

---

# Aspect Ratio

> Constrains content to a fixed width:height ratio that scales with its container.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** layout
- **Import:** `import { AspectRatio } from "@garn/ui/aspect-ratio"`

## Overview
AspectRatio constrains media — an image, video, embed, or map — to a fixed width:height ratio that scales with its container, so the box reserves its space before the content loads and never reflows. Give it a `ratio` (16/9, 1, 4/3) and drop the media inside. It's a layout primitive for *ratio-locked* media; for free-flowing content use normal sizing, and to clip a too-tall element use overflow instead.

## When to use
Constrain media (image, video, embed, map) to a fixed width:height ratio that scales with its container.

## When not to use
A box whose height should follow its content (just let it flow); a single fixed pixel size (set width/height directly).

## Do / Don't
- ✅ Give the AspectRatio a width (or let it fill its container) — the height is computed from `ratio`.
- ✅ Use it for responsive media so it reserves space and avoids layout shift.
- ❌ Don't set an explicit height on the child — the ratio computes it.
- ❌ Don't wrap text whose height should grow naturally.

## Guidelines
**Use it to prevent layout shift on media.** Wrapping an image/video in a locked ratio reserves the slot up front, so the page doesn't jump when it loads — the main reason to reach for it. Pick the ratio that matches the asset's native shape to avoid letterboxing.

**Let the media fill, and crop deliberately.** Have the child cover the box (object-fit) so it fills without distortion, and accept that covering crops — frame the asset so the important part survives. Don't stretch content to a ratio it wasn't made for.

**Keep accessibility on the media, not the wrapper.** The ratio box is purely presentational; put `alt` text on the image and captions/labels on the video. Reserve it for genuinely ratio-bound content rather than as a generic spacer.

## Anatomy
- `aspect-ratio` — accepts image | video | iframe | map | any single media child: The ratio box; give it a width and the height is derived from `ratio`.

## Accessibility
- **WCAG:** 1.1.1 Non-text Content (A)
- AspectRatio is presentational — it adds no role. The semantics belong to the child (e.g. an <img> needs `alt`).

## Related
- **pairsWith** → `card` (when framing a media thumbnail inside a card)
- **pairsWith** → `skeleton` (when reserving the media's box while it loads)

## Examples
- **basic** (canonical): A 16:9 media box.

---

# Avatar

> An identity avatar — circle / square / hexagon, with presence & status indicators, a name + detail AvatarItem, and overlapping AvatarGroups.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Avatar } from "@garn/ui/avatar"`
- **Polymorphism:** `asChild` (default element `<span>`)

## Overview
Avatar represents a person or entity with their photo, gracefully falling back to initials or a glyph when the image is missing or still loading. `AvatarImage` + `AvatarFallback` are the core; `AvatarStatus`/`AvatarPresence` add a status dot, `AvatarSkeleton` holds the shape while loading, and an AvatarGroup stacks several with a "+N" overflow. It's an identity marker — not a button — so pair it with a name and wrap it in a control when it should be clickable.

## When to use
Represent a person or entity with their photo, falling back to initials or a person glyph — with optional presence/status, a name + detail AvatarItem, or an AvatarGroup that stacks many.

## When not to use
A decorative or content image (use img / aspect-ratio); a standalone status dot or unread count (use a badge / counter); a large hero image.

## Do / Don't
- ✅ Always include an AvatarFallback (initials or the default glyph) for the loading/missing-image case.
- ✅ Give AvatarImage a meaningful `alt`; give an interactive (asChild) avatar an `aria-label`.
- ✅ Use the fixed `size` scale — avatars are identity geometry, not density-driven.
- ✅ Use AvatarPresence (bottom-end) for presence and AvatarStatus (top-end) for status; give every AvatarGroup a `label`.
- ❌ Don't ship an Avatar with no fallback.
- ❌ Don't wrap the avatar in an overflow-hidden box if it carries presence/status — that clips the indicator.
- ❌ Don't shrink avatars with density; the size scale is intentional.

## Guidelines
**Always provide a real fallback.** Photos fail, lag, or simply don't exist; give every avatar initials (or a glyph) so it never renders empty. Derive initials from the person's name and keep them to one or two characters.

**Give it an accessible name, not just a picture.** Set meaningful `alt`/label text (the person's name) — a decorative-only avatar leaves screen-reader users with nothing. In a group, summarize the overflow ("+5 more") rather than hiding who's there.

**Use the status dot for presence, sparingly.** A green/idle/offline dot communicates availability at a glance, but don't overload the corner with multiple indicators. Keep sizes on the avatar's own scale and pair small avatars with a name when identity matters.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `shape` | `"circle" \| "hexagon" \| "square"` | `circle` | no |  |
| `size` | `"2xl" \| "2xs" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `asChild` | `boolean` | — | no | Render the consumer's element (an `<a>`/`<button>`) as the root — interactive. |

_Plus 280 inherited native `<span>` attributes._

### `AvatarSkeleton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `shape` | `AvatarShape` | — | no |  |
| `size` | `AvatarSize` | — | no |  |

_Plus 280 inherited native HTML attributes._

### `AvatarPresence` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | — | no | Accessible label; defaults to the capitalized state word. |
| `type` | `AvatarPresenceType` | — | yes |  |

_Plus 279 inherited native HTML attributes._

### `AvatarStatus` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | — | no | Accessible label; defaults to the capitalized state word. |
| `type` | `AvatarStatusType` | — | yes |  |

_Plus 279 inherited native HTML attributes._

### `AvatarItem` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no | Promote the row to the consumer's interactive element (a `<button>`/`<a>`). |
| `avatar` | `React.ReactNode` | — | no | The leading Avatar. |
| `primaryText` | `React.ReactNode` | — | yes |  |
| `secondaryText` | `React.ReactNode` | — | no |  |
| `selected` | `boolean` | — | no | Reflected as `data-selected` and styled as the active row. |

_Plus 280 inherited native HTML attributes._

### `AvatarGroup` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"grid" \| "stack"` | — | no | `stack` overlaps the avatars; `grid` lays them out with even gutters. Default `stack`. |
| `label` | `string` | — | no | Accessible name for the group (required — the group is a labelled list). |
| `max` | `number` | — | no | Show at most this many avatars before collapsing the rest into "+N". Default 5 (stack) / 11 (grid). |
| `moreLabel` | `string` | — | no | Accessible label for the "+N" chip (default: "N more"). |
| `onAvatarClick` | `(index: number) => void` | — | no | Fires with the avatar's index when a stacked avatar is clicked. |
| `onMoreClick` | `() => void` | — | no | Fires when the "+N" chip is clicked. When set, it replaces the default popover. |
| `shape` | `AvatarShape` | — | no | Shape applied to every avatar + the chip. |
| `size` | `AvatarSize` | — | no | Size applied to every avatar + the chip. |
| `total` | `number` | — | no | Total people represented when not all are passed as children — the surplus is added to "+N". |

_Plus 279 inherited native HTML attributes._

## Variants
- **size** (default `md`): `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`
- **shape** (default `circle`): `circle`, `square`, `hexagon`

## Anatomy

**Parts**
- `Avatar` (`avatar`) · required: The frame; carries the `size` + `shape` variants. Not overflow-hidden, so indicators can sit past the edge. `asChild` makes it an interactive <a>/<button>.
- `AvatarImage` (`avatar-image`): The photo; needs `alt`. Rounds/clips itself to the frame shape. Hidden until it loads, then revealed over the fallback.
- `AvatarFallback` (`avatar-fallback`) · required: Initials shown while the image loads or if it fails. With no children it renders a neutral person glyph — never a blank disc.
- `AvatarSkeleton` (`avatar-skeleton`): A pulsing loading placeholder matching the avatar's size + shape (hexagon self-clips). Reduced-motion-safe.
- `AvatarPresence` (`avatar-presence`): A presence dot anchored bottom-end (online / busy / focus / offline) with a surface-color cutout ring and an sr-only state label.
- `AvatarStatus` (`avatar-status`): A status glyph anchored top-end (approved / declined / locked) with a surface-color cutout ring and an sr-only state label.
- `AvatarItem` (`avatar-item`): An avatar + primaryText (+ optional secondaryText) row for lists and menus. `asChild` promotes the whole row to a button/link; supports selected / disabled.
- `AvatarGroup` (`avatar-group`): A labelled list of avatars — `stack` (overlapping, surface-ring separated) or `grid` (even gutters) — capped at `max`, with a '+N' overflow chip.

## Accessibility
- **WCAG:** 1.1.1 Non-text Content (A); 1.4.1 Use of Color (A); 4.1.2 Name, Role, Value (A)
- AvatarImage is an <img> — give it a meaningful `alt` (the person/entity name), or alt="" if it is purely decorative beside a text label.
- AvatarFallback (initials or the default person glyph) is what assistive tech reads before/if the image loads.
- An interactive avatar (asChild) needs its own accessible name — put aria-label (the person's name) on the <a>/<button>; a meaningful AvatarImage alt or AvatarFallback text also counts. A dev-time warning fires when none is found.
- AvatarPresence / AvatarStatus convey their state in text via an sr-only label (e.g. 'Online', 'Approved') and a distinct glyph shape — never by color alone.
- AvatarGroup is a labelled list (role=list) — give it an accessible name via `label`; a dev-time warning fires when missing. The '+N' chip is a button labelled 'N more'.
- **Contract (warn):** Give the interactive avatar an accessible name — aria-label (the person's name) on the <a>/<button>, or a meaningful AvatarImage alt / AvatarFallback text. — _when an Avatar is interactive (asChild) but the link/button, the AvatarImage alt, and the AvatarFallback text are all empty_
- **Contract (warn):** Give the AvatarGroup an accessible name via `label` (e.g. "Project team"). — _when an AvatarGroup has no `label` or `aria-label`_

## Tokens
- `presence-online` → `--garn-avatar-online` · brandable
- `presence-busy` → `--garn-avatar-busy` · brandable
- `presence-focus` → `--garn-avatar-focus` · brandable
- `presence-offline` → `--garn-avatar-offline` · brandable
- `status-locked` → `--garn-avatar-locked` · brandable
- **Internal (never externalize):** `--avatar-hex`

## Related
- **composes** → `utils`
- **composes** → `popover` (when AvatarGroup's '+N' overflow opens a Popover of the remaining people)
- **composes** → `scroll-area` (when the overflow Popover scrolls a long list of AvatarItems)
- **pairsWith** → `counter` (when Counter.Indicator can anchor a count or dot onto an avatar (vs the built-in presence))
- **pairsWith** → `hover-card` (when an avatar triggers a profile preview)
- **pairsWith** → `tooltip` (when a tooltip names the person on hover)
- **alternativeTo** → `badge` (when you need a standalone status/label, not a person's identity)

## Recipes
- **avatar-profile-preview** — An avatar that reveals a profile card on hover/focus. _(use when previewing a user's profile from their avatar)_

## Gotchas
- **The avatar is blank when the image URL is missing or slow.** — No AvatarFallback was provided. → Always render an AvatarFallback (initials, or leave it empty for the default person glyph) as a child.
- **A screen reader doesn't announce a clickable avatar.** — An interactive (asChild) avatar has no accessible name on its <a>/<button>. → Add aria-label (the person's name) to the link/button, or give AvatarImage a meaningful alt.
- **The presence/status dot is clipped or cut off.** — The avatar (or a wrapping container) was given overflow-hidden — the indicator sits past the frame edge. → Don't add overflow-hidden to the Avatar or its wrapper; the image/fallback already clip themselves.
- **AvatarGroup shows fewer avatars than expected, or the '+N' count looks off.** — `max` reserves the last slot for the '+N' chip; the chip counts everything beyond the shown avatars. → Raise `max`, or pass `total` when the group represents more people than the children you render.
- **Editing dark-mode presence/status colors in the component has no effect.** — They resolve through the --garn-avatar-* component tokens; the dark values live in the token layer. → Adjust dark mode in the garn theme CSS (.dark block) — never with raw ramps in avatar.tsx.

## Examples
- **basic** (canonical): Image with an initials fallback.
- **sizes** (playground): The full ladder — 2xs · xs · sm · md · lg · xl · 2xl (16→128px).
- **shapes** (edge-case): circle · square · hexagon.
- **fallback** (edge-case): Initials, or the default person glyph when empty.
- **presence** (edge-case): online · busy · focus · offline (bottom-end, cutout ring).
- **status** (edge-case): approved · declined · locked (top-end).
- **interactive** (edge-case): asChild link with hover/press/focus + a presence dot.
- **item** (edge-case): AvatarItem — name + secondary line; static and interactive/selected.
- **group** (edge-case): AvatarGroup stack with a '+N' overflow popover.
- **grid-group** (edge-case): AvatarGroup grid appearance + `total` (surplus tallied into '+N').
- **skeleton** (edge-case): AvatarSkeleton loading placeholders (circle / square / hexagon).

---

# BadgeSelect

> A single-value pick-to-change control styled as a Badge — a tinted lozenge whose tone follows the selected option, opening a single-select list to change the value.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { BadgeSelect } from "@garn/ui/badge-select"`

## Overview
BadgeSelect is a single value you pick that reads as a badge — a status / priority / category / assignee cell you edit in place on a table, board, or detail view. The trigger is a tinted lozenge whose tone follows the chosen value; opening it reveals `BadgeSelectItem`s (each with a tone dot), optionally organized with `Group`/`Label`/`Separator`. It's the editable cousin of Badge: use it when the badge's value is *set by the user*, Select when the control is a normal field, and Badge when the value is read-only.

## When to use
A single value you pick to change, displayed as a badge: a status / priority / category / assignee cell in a table, board, or inline-edit field. The trigger reads as a tinted lozenge whose tone follows the chosen value.

## When not to use
A static, non-interactive label (use Badge); a numeric count (use Counter); removable or multi-select chips (use Tag / TagGroup); a few mutually-exclusive choices shown at once (use RadioGroup); a long searchable list (use Select or a Command popover); a menu of actions/transitions (use a Button/Badge trigger + DropdownMenu).

## Do / Don't
- ✅ Give the trigger an accessible name (aria-label / aria-labelledby, or a <label>).
- ✅ Set a `tone` on each option so the trigger colour follows the selected value.
- ✅ Use the badge family tone vocabulary so a status reads the same across Badge / Counter / Tag / BadgeSelect.
- ✅ Use `count` for a per-option tally (a tone-matched Counter), shown in the row and mirrored to the trigger.
- ✅ Use `name` for form submission, and `loading` for a pending async change.
- ❌ Don't use it for multi-select or removable chips — that's Tag / TagGroup.
- ❌ Don't rely on the placeholder as the accessible name.
- ❌ Don't reach for raw colors; tone resolves through the --garn-badge-* tokens (edit dark mode in the token layer).
- ❌ Don't use it for a long list that needs search — compose Select / Command instead.

## Guidelines
**Use it where a badge needs to become editable in place.** It shines as an inline-edit cell — a status or priority you click to change without leaving the row. If the field belongs in a form with a label, a normal Select reads better.

**Let the chosen tone mirror its meaning.** Give each option a tone that matches its semantics (done = success, blocked = danger) so the resting lozenge communicates state at a glance, and keep that mapping consistent across the app.

**Keep the option set short and named.** It's a pick-one from a small, known set; for a long or searchable list use a Combobox. Ensure the trigger has an accessible name and that selection is fully keyboard-operable.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"framed" \| "outline" \| "soft"` | `soft` | no |  |
| `shape` | `"pill" \| "rounded" \| "sharp"` | `rounded` | no |  |
| `size` | `"md" \| "sm"` | `md` | no |  |
| `tone` | `"brand" \| "danger" \| "discovery" \| "info" \| "neutral" \| "success" \| "warning"` | `neutral` | no |  |
| `"aria-label"` | `string` | — | no |  |
| `"aria-labelledby"` | `string` | — | no |  |
| `children` | `React.ReactNode` | — | no | BadgeSelectItem children. |
| `className` | `string` | — | no | Applied to the trigger (the visible root). |
| `contentClassName` | `string` | — | no | Applied to the popup content. |
| `id` | `string` | — | no |  |
| `loading` | `boolean` | — | no | Pending state: a spinner replaces the trigger leading and the control is disabled. |
| `options` | `BadgeSelectOption[]` | — | no | Data-driven options — an alternative to compound children (one or the other). |
| `placeholder` | `React.ReactNode` | — | no | Shown when nothing is selected. |
| `ref` | `React.Ref<HTMLButtonElement>` | — | no |  |

_Plus 14 inherited native `<button>` attributes._

### `BadgeSelectItem` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | no |  |
| `count` | `number` | — | no | A trailing count, rendered as a tone-matched Counter. Row only. |
| `leading` | `React.ReactNode` | — | no | Leading content — icon / avatar / badge / dot. Mirrors into the trigger when selected. |
| `tone` | `BadgeSelectTone` | — | no | Tone the trigger mirrors when this option is selected; also colours the row dot. |
| `trailing` | `React.ReactNode` | — | no | Trailing content (Counter / Badge / Kbd …). Shown in the row only, not the trigger. |
| `value` | `string` | — | yes | Stable value for this option (required). |

_Plus 282 inherited native HTML attributes._

## Variants
- **tone** (default `neutral`): `neutral`, `brand`, `info`, `success`, `warning`, `danger`, `discovery`
- **appearance** (default `soft`): `soft`, `outline`, `framed`
- **size** (default `md`): `sm`, `md`
- **shape** (default `rounded`): `sharp`, `rounded`, `pill`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The selected option's value. Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`.
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Whether the listbox popover is open.
- Selection: single.

## Anatomy
- `badge-select-trigger`: The badge-styled combobox trigger (a Radix Select.Trigger). Renders the selected option's leading + label + its tone + a trailing chevron; a neutral placeholder when nothing is selected.
- `badge-select-trigger-leading`: The selected option's leading content (icon / avatar / badge) mirrored into the trigger.
- `badge-select-trigger-label`: The selected option's label (or the placeholder).
- `badge-select-trigger-count`: The selected option's `count`, mirrored into the trigger as a solid, contrast-popping Counter.

**Parts**
- `BadgeSelectItem` (`badge-select-item`) · required: A single option (a Radix Select.Item). Props: value (required), tone (the trigger mirrors it when selected; also colours the row dot), leading (icon/avatar/badge — mirrored to the trigger), trailing (row-only meta), count (a tone-matched Counter, row-only), disabled. A leading tone dot is shown by default when `tone` is set.
- `BadgeSelectGroup` (`badge-select-group`): Wraps related options into a labelled section (a Radix Select.Group).
- `BadgeSelectLabel` (`badge-select-label`): A section heading inside a BadgeSelectGroup.
- `BadgeSelectSeparator` (`badge-select-separator`): A divider between option groups.

## Accessibility
- **Role:** combobox
- **WCAG:** 1.4.1 Use of Color (A); 1.4.3 Contrast (Minimum) (AA); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The trigger is a combobox (Radix Select.Trigger) that conveys the current value in its collapsed state — listbox, not menu, semantics — so it suits a control whose job is to display a value.
- Opening exposes a role=listbox of role=option items; the selected option carries aria-selected and a trailing check. Single-select only.
- Keyboard (inherited from Select): Enter / Space / ArrowUp / ArrowDown and typeahead open and move; Enter / Space pick; Esc closes; Home / End jump.
- Give the trigger an accessible name via `aria-label`, `aria-labelledby`, or a <label htmlFor> matching the trigger `id` — the placeholder is not a name. The selected value is the trigger's text content.
- Setting `name` submits the value via a hidden native <select> (form integration, inherited from Select).
- **Focus:** 2px ring in --garn-ring on the trigger; focus and the listbox roving are managed by Radix Select.
- **Contract (warn):** Give the trigger an accessible name (aria-label / aria-labelledby, or a <label htmlFor> matching the trigger id). The placeholder doesn't count. — _when the BadgeSelect trigger has no `aria-label`, `aria-labelledby`, or `id` (for an external <label htmlFor>)_

## Tokens
- `fill` → `--garn-badge-brand-bg` · brandable
- **Internal (never externalize):** `--t-soft-bg`

## Related
- **composes** → `select`
- **composes** → `counter`
- **composes** → `spinner`
- **composes** → `utils`
- **slotAccepts** → `avatar` (when an option's leading can be an avatar (an assignee picker))
- **slotAccepts** → `counter` (when an option's `count` renders a Counter tally)
- **alternativeTo** → `badge` (when the value is a static, non-interactive label (not pick-to-change))
- **alternativeTo** → `tag` (when the chips are removable or multi-select, not a single value)
- **alternativeTo** → `select` (when the control is a standard form field, not a badge-styled value cell)
- **alternativeTo** → `dropdown-menu` (when the options are actions/transitions (a menu), not a value to display)

## Gotchas
- **The trigger colour doesn't follow the selected value.** — The options have no `tone`. → Set a `tone` on each BadgeSelectItem — the trigger always mirrors the selected option's tone.
- **A dev console warns the trigger has no accessible name.** — No `aria-label`, `aria-labelledby`, or `id` (for a <label htmlFor>) on BadgeSelect; the placeholder is not a name. → Pass `aria-label` (or wire a <label htmlFor> to the trigger `id`).
- **Trying to make it multi-select or removable.** — BadgeSelect is single-value only (listbox semantics). → Use Tag / TagGroup for removable or multi-select chips.
- **A count shows in the row but you expected it everywhere — or vice versa.** — `count` (and `trailing`) render in the option row; only `count` is also mirrored into the trigger. Generic `trailing` is row-only. → Use `count` for a value mirrored into the trigger; use `trailing` for row-only secondary meta.
- **An avatar overflows the trigger.** — An Avatar larger than the 20–28px trigger was used in the leading slot. → Use the Avatar `xs` size (24px) in the leading slot.
- **Editing dark-mode trigger colours in the component has no effect.** — Tones resolve through the --garn-badge-* component tokens; dark values live in the token layer. → Adjust dark mode in the garn theme CSS (.dark block) — never with raw ramps in badge-select.tsx.

## Examples
- **basic** (canonical): A status picker — the trigger tone follows the selected value.
- **tones** (edge-case): The trigger adopts each tone from its selected option.
- **appearances** (edge-case): soft · outline · framed (no solid — a filled trigger reads as a button).
- **shapes** (edge-case): sharp · rounded · pill.
- **sizes** (edge-case): sm · md.
- **leading** (edge-case): Custom leading icons (priority) mirrored into the trigger.
- **count** (edge-case): Per-option `count` tallies (tone-matched Counters), mirrored into the trigger.
- **assignee** (edge-case): Avatars as leading content — an assignee picker.
- **grouped** (edge-case): Sectioned options (BadgeSelectGroup / Label / Separator).
- **loading** (edge-case): A pending change — a Spinner in the trigger, disabled until done.
- **options-prop** (edge-case): Data-driven options via the `options` prop.
- **placeholder-disabled** (edge-case): A placeholder (unset), a disabled control, and a disabled option.
- **data-rich** (edge-case): A status cell per row in a data-rich table — the core use case.

---

# Badge

> A static, inline label for a status, count, or short piece of metadata.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Badge } from "@garn/ui/badge"`
- **Polymorphism:** `asChild` (default element `<span>`)

## Overview
Badge tags or categorizes inline — a status, a short label, a count beside content. Its look is orthogonal: `tone` sets the meaning color (neutral / brand / success / warning / danger / info), `appearance` sets the fill (solid / soft / surface / outline), and `size` the scale — the same vocabulary across the whole chip family. It's a read-only marker; for a removable/selectable chip use Tag, for a value the user changes use BadgeSelect, and for a pure number use Counter.

## When to use
Tag or categorize inline — a status, count, or short label next to content.

## When not to use
An interactive control (use a button or toggle); a removable or selectable chip, or a value-changing dropdown — those belong to Tag / SelectBadge; large notification counts belong to Counter.

## Do / Don't
- ✅ Keep the text to one or two words.
- ✅ Use a tone for state (success/warning/danger) with a readable label — not color alone.
- ✅ Reach for `framed` when a soft chip needs more definition; `solid` for the highest emphasis.
- ❌ Don't make a badge clickable — its only interaction is optional copy-to-clipboard.
- ❌ Don't pack sentences into a badge; only the label truncates — keep leading/trailing to glyphs.

## Guidelines
**Let tone carry meaning, consistently.** Map each status to one tone and reuse it everywhere (success = done, danger = error); a rainbow of tones for decoration trains people to ignore them. Keep the label to a word or two — a badge is a marker, not a sentence.

**Don't make a badge do a control's job.** It isn't clickable, focusable, or dismissible by contract; if users need to remove or toggle it, reach for Tag or BadgeSelect. Place it adjacent to what it describes so the association is obvious.

**Mind contrast and redundancy.** Pair tone with text (or an icon) so meaning survives for color-blind users and in forced-colors mode. Use `soft`/`surface` for quiet metadata and reserve `solid` for the one status that must stand out.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"framed" \| "outline" \| "soft" \| "solid" \| "subtle"` | `soft` | no |  |
| `shape` | `"pill" \| "rounded" \| "sharp"` | `rounded` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xs"` | `md` | no |  |
| `tone` | `"brand" \| "danger" \| "info" \| "neutral" \| "success" \| "warning"` | `neutral` | no |  |
| `asChild` | `boolean` | — | no |  |
| `avatar` | `React.ReactNode` | — | no |  |
| `color` | `string` | — | no | Custom token reference or hex/rgb value; overrides `tone`. |
| `copyable` | `boolean` | — | no |  |
| `copyValue` | `string` | — | no |  |
| `count` | `number` | — | no | A trailing count, rendered by the Counter component (not a plain number): it caps at 99+, rolls its digits on change, and announces the true count to screen readers. Tone and size follow the badge; the count's appearance inverts against the badge's so it always contrasts. |
| `dot` | `boolean` | — | no |  |
| `leading` | `React.ReactNode` | — | no |  |
| `loading` | `boolean` | — | no |  |
| `maxWidth` | `number \| string` | — | no |  |
| `progress` | `number` | — | no | 0–100; snaps to a check at 100. |
| `pulse` | `boolean` | — | no |  |
| `trailing` | `React.ReactNode` | — | no |  |
| `truncate` | `boolean` | — | no |  |

_Plus 280 inherited native `<span>` attributes._

## Variants
- **tone** (default `neutral`): `neutral`, `brand`, `info`, `success`, `warning`, `danger`
- **appearance** (default `soft`): `solid`, `soft`, `outline`, `subtle`, `framed`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`
- **shape** (default `rounded`): `sharp`, `rounded`, `pill`

## Anatomy
- `badge`: The badge element (a <span>, or the asChild target).
- `badge-leading` — accepts icon | dot | spinner | progress ring | avatar: Fixed-width content before the label; never truncates.
- `badge-label`: The text label — the only part that truncates.
- `badge-trailing` — accepts icon | count | copy button: Fixed-width content after the label.
- `badge-separator`: Decorative divider between inline segments (e.g. a status label and a composed action). variant="dot" is a typographic middot (default, overridable via children); variant="line" is a currentColor hairline. aria-hidden — never in the accessible name. Reflects data-variant.
- `badge-dot`: Status dot (optional pulsing ring) in the leading slot.
- `badge-copy`: Copy-to-clipboard button — Badge's only interactive affordance.
- `badge-count`: Trailing count, rendered by Counter (99+ overflow cap, digit roll, true-count announce); tone/size match the badge, appearance inverts for contrast.

## Accessibility
- **WCAG:** 1.4.1 Use of Color (A); 1.4.3 Contrast (Minimum) (AA); 2.4.7 Focus Visible (AA)
- Badge is a plain <span> with no implicit role — keep a readable text label; don't encode status by color alone.
- loading sets aria-busy. copyable renders a real <button> with an aria-label and announces via an aria-live=polite region.
- Badge.Separator is aria-hidden and select-none — purely decorative, so it never enters the badge's accessible name. A composed action (e.g. an inline link) keeps its own name and focus ring; Badge itself stays non-interactive.
- **Focus:** 2px ring in --garn-ring on the asChild anchor and the copy button.
- **Contract (warn):** Provide aria-label (or aria-labelledby / title / sr-only text). — _when no text label (icon/dot/avatar only) && !asChild && no aria-label/labelledby/title_

## Tokens
- `fill` → `--garn-badge-success-bg` · brandable
- `ring` → `--garn-ring` · brandable
- **Internal (never externalize):** `--b-soft-bg`, `--b-soft-fg`, `--b-solid-bg`, `--b-solid-fg`, `--b-line`, `--b-text`, `--badge-c`, `--badge-fg`

## Related
- **composes** → `utils`
- **composes** → `spinner` (when loading renders the Spinner in the leading slot)
- **composes** → `counter` (when the `count` sugar renders a Counter in the trailing slot)
- **slotAccepts** → `avatar` (when as a leading avatar)
- **pairsWith** → `table` (when as a status cell)
- **pairsWith** → `avatar` (when as a status / label beside a person)

## Gotchas
- **A custom-colored solid badge has unreadable (assumed-white) text.** — getReadableForeground parses hex/rgb; design tokens / oklch can't be parsed synchronously and fall back to white. → Pass `color` as a hex/rgb value for auto-contrast, or set an explicit foreground.
- **Editing dark-mode badge colors in the component has no effect.** — Tones resolve through the --garn-badge-* component tokens; the dark values live in the token layer. → Adjust dark mode in the garn theme CSS (.dark block) — never with raw ramps in badge.tsx.
- **An icon-only badge isn't announced by screen readers.** — No text label and no aria-label (the dev build warns). → Pass aria-label (or aria-labelledby / title / sr-only text).
- **A Badge.Separator with variant="line" shows nothing where you passed content.** — The line variant is a pure hairline and discards children by design; only variant="dot" renders text (the middot, or your override). → Use the default dot variant when you need a visible glyph/character; keep line for a plain divider between labels.

## Examples
- **basic** (canonical): Tone + appearance defaults.
- **appearances** (playground): tone × appearance matrix.
- **tones** (edge-case): The semantic palette — neutral for metadata, the rest for intent.
- **sizes** (edge-case): xs · sm · md · lg — scales font, padding, and slot icons together.
- **shapes** (edge-case): sharp · rounded · pill.
- **status** (edge-case): Dot, pulse, loading, and progress affordances.
- **count** (edge-case): A trailing count, rendered by Counter (caps at 99+).
- **icons** (edge-case): Leading/trailing icons; an icon-only badge needs an aria-label.
- **custom-color** (edge-case): A custom color with automatic foreground contrast.
- **truncation** (edge-case): Only the label ellipsizes; the full text stays in the title.
- **compound** (edge-case): Explicit Badge.Leading / .Label / .Trailing for full control.
- **as-child** (edge-case): Renders as a link via asChild, keeping the badge styling.
- **plan-badge** (edge-case): Badge.Separator (dot / line) divides inline segments — a status·action pill and a metadata divider. The action is a composed link; Badge stays non-interactive.

---

# Bar List

> A ranked list of label/value rows, each backed by a bar sized to its share of the max.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { BarList } from "@garn/ui/bar-list"`

## Overview
Bar List is the ranked-breakdown widget every dashboard needs — top pages, top referrers, top errors — a compact list where each row's bar shows its share of the largest value. It's not a bar chart: there are no axes and the emphasis is the ordering. Pure markup means it renders on the server and reads cleanly as a list to assistive tech.

## When to use
Show a ranked breakdown — the top N items by a metric (pages, referrers, products, errors).

## When not to use
Comparing categories on a shared axis (use a Bar chart); one measure vs a target (use Bullet); a trend over time (use Sparkline/Line).

## Do / Don't
- ✅ Provide a `valueFormatter` for large/compact/currency values.
- ✅ Let it sort descending; set `href` to link rows.
- ❌ Don't use it as a substitute for an axis-based bar chart.
- ❌ Don't hand-pre-sort unless `sortOrder="none"` (input order) is intended.

## Guidelines
**Rank, don't plot.** Bar List answers "what are the biggest N", not "how do these compare on an axis". For an axis comparison across categories use a Bar chart; for one value vs a target use Bullet.

**Keep the value truthful and formatted.** Pass a `valueFormatter` (compact, currency) so the number is legible, and let the bar carry the relative sense. It sorts descending by default — override with `sortOrder` only when input order is meaningful.

**Tint from a token.** The bar uses a `--garn-chart-*` token at low opacity so the label stays readable on top; set per-row `color` to distinguish categories when useful.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string` | — | no | Default bar tint (token ref) when a row has no `color`. |
| `items` | `BarListItem[]` | — | yes |  |
| `max` | `number` | — | no | Scale bars to this max (default: the largest value). |
| `sortOrder` | `"asc" \| "desc" \| "none"` | — | no | Sort rows by value. Default "desc" (ranking). |
| `valueFormatter` | `(value: number) => React.ReactNode` | — | no | Format the displayed value. |

_Plus 281 inherited native `<ol>` attributes._

## Anatomy
- `bar-list`: The ordered list (`<ol>`).
- `bar-list-item`: A row: a decorative tinted bar (width = value/peak) behind the label + value.

## Accessibility
- **Role:** list
- **WCAG:** 1.3.1 Info and Relationships (A)
- An ordered list (`<ol>`) of `label, value` rows — the ranking order is conveyed structurally.
- The bar is decorative (`aria-hidden`); the value is read as text.
- Rows with an `href` render as links.

## Related
- **composes** → `utils`
- **alternativeTo** → `chart` (when you need a category axis rather than a ranking)

## Gotchas
- **Bars all look full.** — `max` is below the largest value, or all values are equal. → Omit `max` to auto-scale to the peak, or pass a max ≥ the largest value.

## Examples
- **basic** (canonical): Top pages by views, ranked.
- **links** (edge-case): Linked rows with compact-formatted values.

---

# Board

> A Kanban / column board — records grouped into ordered columns where a drag is a field mutation (onCardMove). Composes the `sortable` primitive for all drag (pointer, keyboard, touch, cross-column, overlay ghost, announcements) and adds column headers with a live count + accent tone, WIP limits, collapse-to-rail, swimlanes, an inline card composer, and empty/loading states. Data-driven or composable, controlled or uncontrolled.

- **Status:** beta
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Board } from "@garn/ui/board"`

## Overview
Board is a **Kanban / column board** — records grouped into ordered columns (a status/stage field), where a drag *is a mutation*: move a card and it fires `onCardMove(id, { fromColumn, toColumn, index })`. It is the one renderer where reordering means changing data, not just order. Every drag behaviour — pointer, keyboard (Space lifts · arrows move across columns · Esc cancels), touch long-press, edge auto-scroll, the portal overlay ghost and the screen-reader announcements — is delegated to the `sortable` primitive (a `Sortable.Group` hoists one drag machine across the per-column `Sortable`s). On top of that engine Board adds what makes it a board: column headers with a live count + accent `tone`, **WIP limits** with an over-limit warning, **collapse-to-rail**, **swimlanes**, an **inline card composer**, and empty/loading states — with the structural a11y (a labelled region whose columns are labelled regions with the count in their name) sitting over sortable's drag a11y. Author it **composable** (`Board.Column` children, each owning its `value`) or **data-driven** (`columns` + `items` + `renderCard`), controlled or uncontrolled. It is the named CollectionView `.Board` renderer.

## When to use
A Kanban / status board where cards move between ordered columns and the move writes back a field: a sprint / project board (To do → In progress → Done), a CRM pipeline, a content workflow, an agent task board. Reach for it with `Board.Column` children, or drive it from data with `columns` + `items` + `renderCard`. Add WIP limits, swimlanes, collapse-to-rail and an inline composer as needed.

## When not to use
A single reorderable list with no columns (use `sortable` or `list`'s `reorderable`). A row/column data grid or a spreadsheet (use `table`). A read-only chronological feed (use `timeline`). Work laid out against a horizontal time axis with dependencies (use `gantt`) or an hour-grid calendar (use `scheduler`). The raw drag mechanism with no column/card presentation (use `sortable` directly).

## Do / Don't
- ✅ Give the board an accessible name (`aria-label` / `aria-labelledby`) — it's a required contract.
- ✅ Own the write-back: apply `onCardMove` (and data-driven `onItemsChange`) to your state; a drag doesn't persist until you do.
- ✅ Pick one authoring path — composable `Board.Column` children (each owns its `value`) or data-driven `columns`/`items`/`renderCard`.
- ✅ Add a `Board.CardHandle` when a card has its own buttons/links, so only the grip drags.
- ✅ Use `limit` for WIP discipline, `swimlanes` (keyed per `Board.cellKey`) for a second axis, and `Board.CardAdd` for low-friction capture.
- ✅ Keep a `Board.Overlay` in the tree (the data-driven path renders one) so the dragged card isn't clipped by a column's overflow.
- ❌ Don't reimplement drag on top of Board — pointer, keyboard, touch, auto-scroll, the overlay and announcements all come from `sortable`.
- ❌ Don't make a card with interactive content the bare drag activator — nest a `Board.CardHandle`, or its clicks start a drag.
- ❌ Don't hardcode a column colour or a card padding — use `tone` on the column and `size`; geometry rides `--garn-board-*` tokens.
- ❌ Don't expect a drag to persist by itself — Board reports the move; you apply it (drag = mutation, but you own the data).
- ❌ Don't type the swimlane cell key by hand — compose it with `Board.cellKey(laneId, columnId)` (it folds an internal separator).

## Guidelines
**Pick a path: composable or data-driven.** For a fixed, hand-laid board use `Board.Column` children — each column owns its ordered `value`/`onValueChange` (exactly the `sortable` recipe it packages). For a model-driven board (or the CollectionView adapter), pass `columns` + `items` + `renderCard`; Board maps the model onto the same parts and applies each move atomically in one `onDragEnd`.

**A drag is a mutation — own the write-back.** `onCardMove` (and, data-driven, `onItemsChange`) hand you the committed move; apply it to your source of truth. Nothing persists until you do.

**Reach for the built-ins.** `limit` for WIP discipline (soft-warn: the count turns amber → red, a danger ring, and the status is announced); `collapsed`/`collapsible` for collapse-to-rail; `swimlanes` (keyed per `Board.cellKey(lane, col)`) for a second grouping axis; `Board.CardAdd` / `onCardAdd` for the inline composer. Style only through `tone` on the column and the `card` surface; size via `size`, never hand-padding.

**Keep it operable.** Give the board an accessible name, add a `Board.CardHandle` when a card has its own buttons/links, and always render a `Board.Overlay` (the data-driven path does this for you) so the dragged card escapes a column's overflow. Don't strip the focus rings or silence the announcements.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autoScroll` | `boolean` | — | no | Auto-scroll the nearest scroll container near an edge (default true). |
| `columns` | `BoardColumnDef[]` | — | no |  |
| `defaultItems` | `Record<string, string[]>` | — | no |  |
| `getCardLabel` | `(cardId: string) => string` | — | no | Map a card id to the label screen readers announce during a drag. |
| `items` | `Record<string, string[]>` | — | no | Ordered card ids per column (or per `lanecolumn` cell when swimlaned). |
| `loading` | `boolean` | — | no | Show skeleton columns instead of content. |
| `onCardAdd` | `(columnId: string, text: string, laneId?: string) => void` | — | no | Enable an inline composer per column; receives the target column (+ lane). |
| `onCardMove` | `(cardId: string, meta: BoardCardMoveMeta) => void` | — | no | Fired once per committed move — the write-back contract (drag = mutation). |
| `onItemsChange` | `(items: Record<string, string[]>) => void` | — | no |  |
| `renderCard` | `(cardId: string, ctx: { columnId: string; laneId?: string; }) => React.ReactNode` | — | no | Render one card's content by id (data-driven). |
| `size` | `BoardSize` | — | no |  |
| `swimlanes` | `BoardSwimlaneDef[]` | — | no |  |
| `touchDelay` | `number` | — | no | Long-press (ms) before a touch drag begins. |

_Plus 276 inherited native `<div>` attributes._

### `Board.Column` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `collapsed` | `boolean` | — | no |  |
| `collapsible` | `boolean` | — | no | Show the collapse affordance (default true). |
| `columnId` | `string` | — | yes | Stable column key — the group value (drag write-back is keyed on it). |
| `defaultCollapsed` | `boolean` | — | no |  |
| `defaultValue` | `string[]` | — | no |  |
| `laneId` | `string` | — | no | Internal — set by the swimlane renderer so the container id folds (lane, column). |
| `limit` | `number` | — | no | WIP limit — soft-warns at/over it. |
| `onCollapsedChange` | `(collapsed: boolean) => void` | — | no |  |
| `onValueChange` | `(value: string[]) => void` | — | no |  |
| `tone` | `BoardTone` | — | no |  |
| `value` | `string[]` | — | no | Ordered card ids (controlled). |

_Plus 278 inherited native HTML attributes._

### `Board.ColumnHeader` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `actions` | `React.ReactNode` | — | no | Trailing slot — an add button, overflow menu, etc. |

_Plus 280 inherited native HTML attributes._

### `Board.Card` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `cardId` | `string` | — | yes | The card's stable key — its identity in the column's ordered value. |
| `disabled` | `boolean` | — | no | Make this card non-draggable (a pinned card). |
| `hasHandle` | `boolean` | — | no | Declare that a `Board.CardHandle` lives somewhere in this card's rendered output. Handle auto-detection only walks the JSX passed as children — a handle rendered inside one of your own components is invisible to it, which would silently make the whole card the drag activator. |

_Plus 280 inherited native HTML attributes._

### `Board.CardAdd` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | — | no | The collapsed trigger label. |
| `onAdd` | `(text: string) => void` | — | no | Called with the trimmed text when a card is added. |
| `placeholder` | `string` | — | no |  |

_Plus 279 inherited native HTML attributes._

### `Board.Swimlane` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `defaultCollapsed` | `boolean` | — | no |  |
| `laneId` | `string` | — | yes |  |
| `title` | `React.ReactNode` | — | no |  |

_Plus 279 inherited native HTML attributes._

## Anatomy
- `board`: The board region — a horizontal, scrollable `Sortable.Group` of columns (role=group, requires an accessible name). Reflects `data-size`. Data-driven via `columns`/`items` or composable via `Board.Column` children.
- `board-column`: One column = one droppable `Sortable` + a group value. A framed lane surface (role=group, labelled by its header). Reflects `data-tone` / `data-size` / `data-collapsed` / `data-over-limit`.
- `board-column-header`: The soft-tone-tinted header — an uppercase title + the live count badge + a trailing `actions` slot + the collapse toggle. Collapsed, it becomes the vertical rail (title + count + expand button).
- `board-count`: The card-count pill (aria-hidden) — soft neutral normally, amber at the WIP `limit`, red `N/M` over it. The full phrase is spoken via the header's sr-only text.
- `board-card`: A `cardId`-keyed card surface (composes `card`'s hairline elevation) nested inside a `Sortable.Item` activator. `renderCard` (data-driven) or children (composable) fill the content; the Item keeps the drag + a11y wiring.
- `board-empty`: The dashed 'No cards' drop-zone shown when a column is empty (aria-hidden — the column region's name already announces '0 cards').
- `board-card-add`: The inline card composer in a column footer — a collapsed 'Add a card' button that opens a textarea (Enter commits and keeps composing, Esc cancels). Reflects `data-open`.
- `board-swimlane`: A horizontal grouping band (role=group) crossing every column, collapsible per lane via an aria-expanded toggle. The data-driven renderer composes these under a shared column-header row.
- `sortable-overlay`: `Board.Overlay` — the `Sortable.Overlay` portal ghost that follows the pointer (clip-free, so a dragged card escapes a column's overflow). The data-driven path renders one automatically; composable consumers place their own.

**Parts**
- `Board.Column` (`board-column`) · required: One column — a droppable Sortable keyed by `columnId`, owning its ordered `value` (controlled/uncontrolled), an optional WIP `limit`, accent `tone`, and `collapsed`/`collapsible` state. Routes its children into header / cards / composer regions.
- `Board.ColumnHeader` (`board-column-header`): The column header — title + live count + accent tone, a trailing `actions` slot (add / overflow), and the collapse toggle. Reads the column context; must render inside a `Board.Column`.
- `Board.Card` (`board-card`): A card — keyed by `cardId` (its identity in the column's order); `disabled` pins it (non-draggable). Composes `card` for the surface and nests a Sortable.Item for the drag/a11y wiring.
- `Board.CardHandle` (`sortable-handle`): An optional grip that makes only itself the drag activator, so the card's own buttons/links stay clickable and semantic. Carries the sortable-handle marker so the engine detects it however deeply nested in the card's JSX — but a handle rendered inside one of your own components is invisible to that walk; declare it with `hasHandle` on Board.Card. Defaults to a grip icon.
- `Board.CardAdd` (`board-card-add`): The inline composer — `onAdd(text)` appends, `label` names the collapsed trigger, `placeholder` the textarea. Enter commits and re-focuses (rapid add); Esc cancels.
- `Board.Swimlane` (`board-swimlane`): A horizontal grouping band keyed by `laneId`, with a `title` and `defaultCollapsed`; collapsible via an aria-expanded toggle. Exported for hand-composition; the data-driven `swimlanes` prop composes these.

## Accessibility
- **Role:** group (APG: Drag-and-Drop (keyboard-operable reorder))
- **Tab:** Move into the cards; one card is tabbable per column (sortable's roving activators).
- **Space / Enter:** On a card (or its Board.CardHandle): pick it up; press again to drop it at the chosen position.
- **ArrowUp / ArrowDown:** Move the lifted card within its column.
- **ArrowLeft / ArrowRight:** Move the lifted card to the previous / next column (RTL-aware).
- **Home / End:** Send the lifted card to the first / last position in its column.
- **Escape:** Cancel the drag and restore the card to its original column and position.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 2.5.7 Dragging Movements (AA); 4.1.2 Name, Role, Value (A); 4.1.3 Status Messages (AA)
- The board is a role=group region that REQUIRES an accessible name (`aria-label` / `aria-labelledby`); a dev-only warning fires if neither is set.
- Each column is a labelled role=group whose accessible name carries the live count and WIP status — e.g. "To do, 3 cards", "In progress, 3 of 2 cards, over the limit" — composed from the header title + an sr-only phrase (the visible count pill is aria-hidden).
- Cards inherit sortable's drag a11y: the activator is a real button with an accessible name, aria-roledescription and an aria-describedby pointing at the keyboard instructions; Space/Enter lifts, arrows move (cross-axis hops between columns), Esc cancels; a polite live region announces pick-up / move / drop / cancel. `getCardLabel` names each card for those announcements.
- Collapse toggles (column and swimlane) are real buttons with aria-expanded and a name ("Collapse/Expand {title}"); a collapsed column's header becomes the rail and keeps the count + expand button.
- A `Board.CardHandle` makes only the grip the drag activator, so the card body's own buttons/links stay clickable and semantic — required when a card carries interactive content.
- The empty-column drop-zone is aria-hidden (the labelled column region already announces "0 cards"); swimlane bands are labelled role=group rows.
- **Focus:** Focus follows the card through a keyboard drag (via sortable's roving activators); focus-visible rings are preserved on cards, handles and collapse toggles. Don't strip them.
- **Contract (error):** The board root has an accessible name via `aria-label` or `aria-labelledby` (a dev warning fires otherwise). — _when always_
- **Contract (warn):** Each column region's accessible name includes its live card count (and WIP status when a `limit` is set), spoken via an sr-only phrase — the visible count pill stays aria-hidden. — _when a column is rendered_
- **Contract (warn):** Add a `Board.CardHandle` so only the grip drags and the card content stays clickable; a bare card is the drag activator and would swallow the clicks. — _when a card carries interactive content (buttons, links, inputs)_
- **Contract (warn):** The collapse control is a button with aria-expanded and a label naming the column/lane. — _when a collapsible column or swimlane is rendered_

## Tokens
- `columnWidth` → `--garn-board-col-w` (identity)
- `columnWidthSm` → `--garn-board-col-w-sm` (identity)
- `railWidth` → `--garn-board-rail-w` (identity)
- `headerTint` → `--garn-badge-brand-bg`
- `overLimitEdge` → `--garn-badge-danger-edge`
- `surface` → `--garn-muted`
- `hairline` → `--garn-border`
- **Internal (never externalize):** `--garn-board-col`

## Related
- **composes** → `sortable` (when ALL drag — pointer/keyboard/touch, cross-column moves, the overlay ghost, auto-scroll and announcements — is delegated to Sortable.Group + Sortable.Item + Sortable.Overlay)
- **composes** → `card` (when each card surface uses card's hairline elevation)
- **composes** → `button` (when the inline composer's submit control)
- **composes** → `skeleton` (when the loading state renders skeleton columns)
- **composes** → `utils`
- **composes** → `use-controllable-state` (when items / column value / collapsed are controlled or uncontrolled)
- **pairsWith** → `badge` (when a card carries a status / label chip (see the examples))
- **pairsWith** → `avatar` (when a card shows its assignee)
- **pairsWith** → `dropdown-menu` (when a column's `actions` slot or a card's overflow menu)
- **alternativeTo** → `sortable` (when you need the raw reorder mechanism with no column/card/swimlane presentation)
- **alternativeTo** → `table` (when the data is a row/column grid rather than cards flowing between status columns)
- **alternativeTo** → `gantt` (when work is laid out against a horizontal time axis with dependencies rather than status columns)

## Recipes
- **kanban-board** — A status board — cards reorder within a column and move between columns (a drag writes back the status field); a portal overlay follows the pointer. _(use when moving cards between ordered status/stage columns where the move changes data, unless there are no columns (use sortable/list) or the data is a row grid (use table))_
- **wip-limited-board** — A Kanban board with per-column WIP limits — the count turns amber at the limit and red over it, with a danger ring and a spoken status (soft-warn). _(use when enforcing (or surfacing) work-in-progress discipline per column)_
- **swimlane-board** — A board with swimlanes — horizontal bands crossing every column (by assignee / priority / epic); a card moves across columns AND lanes on one drag machine. _(use when you need a second grouping axis (class-of-service, by-owner) beside the columns)_
- **inline-composer-board** — A board with an inline card composer per column — add a card without leaving the board (Enter commits and keeps composing, Esc cancels). _(use when capturing new cards inline (the rapid-add flow))_

## Gotchas
- **A card's button / menu isn't clickable, or clicking it starts a drag.** — A bare Board.Card is the drag activator (via the nested Sortable.Item), so interactive card content conflicts with the drag. → Add a `<Board.CardHandle>` to the card — only the grip starts a drag, and the rest of the card (buttons, links) stays interactive and semantic.
- **A card gets clipped when it's dragged out of its column.** — Cross-column drags need a portal ghost; a column's overflow clips the self-translated card. → Keep a `Board.Overlay` in the tree. The data-driven path renders one automatically; in the composable path add `<Board.Overlay>{(id) => <Card/>}</Board.Overlay>` inside `<Board>`.
- **Dragging a card does nothing — it snaps back.** — A drag is a mutation, but Board doesn't change your data for you — it reports the move. → In the composable path apply each column's onValueChange (use functional setState so a cross-column move doesn't stale-overwrite); data-driven, apply onItemsChange (or read onCardMove). Nothing persists until you do.
- **The board dev-warns about a missing accessible name, or a screen reader can't tell the columns apart.** — The board region has no name, or a column has no header to label it. → Set `aria-label` / `aria-labelledby` on `<Board>`, and give each `Board.Column` a `Board.ColumnHeader` (its count is folded into the column region's name). Headerless swimlane cells get an aria-label instead.
- **Over-limit doesn't block the drop the way I expected.** — WIP is soft-warn in v1 — the count pill turns red and data-over-limit fires, but the drop is still allowed. → That's intended (soft-warn). A hard block (`strictWip`) needs a canDrop/veto hook sortable doesn't yet expose; it's on the backlog. Enforce the block in your onCardMove if you need it now.
- **Swimlane cards land in the wrong cell, or items keys don't match.** — The swimlaned `items` map is keyed per (lane, column) cell with an internal separator, not by column id. → Key each cell with `Board.cellKey(laneId, columnId)` (also exported as `boardCellKey`) — never type the separator yourself. onCardMove meta then carries fromLane/toLane too.

## Examples
- **composable** (canonical): The composable path — `Board.Column` children each own their ordered `value`; cross-column moves fire both columns' onValueChange plus one onCardMove, with a hand-placed Board.Overlay.
- **data-driven** (playground): The data-driven path — `columns` + `items` + `renderCard`; the board maps the model onto the parts and applies each move atomically. `onCardAdd` turns on the inline composer.
- **wip-limit** (playground): WIP limits — a column soft-warns (count amber → red, a danger ring) at and over its `limit`; 'In progress' starts over a limit of 2.
- **collapsible** (playground): Collapse a column to a rail — the header rotates, keeps its count, and flips its toggle to expand ('Done' starts collapsed).
- **card-handle** (edge-case): A rich card with an explicit grip (`Board.CardHandle`) — only the grip drags, so the card's own menu button stays clickable and semantic.
- **swimlanes** (playground): Swimlanes — horizontal bands crossing every column; cards move across columns AND lanes on one machine, cells keyed by Board.cellKey. Shared column headers sit once on top.
- **loading** (playground): The loading state — skeleton columns while cards stream in.
- **empty** (playground): An empty column still renders a labelled 'No cards' drop-zone.

## Source map

Regions in `board.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L3–25 (23 lines) — deps + primitives
- `types` L50–97 (48 lines) — model + prop shapes
- `utils` L99–169 (71 lines) — id folding, move math, node text
- `variants` L171–231 (61 lines) — column width, header tint, count badge
- `context` L233–262 (30 lines) — board + column providers
- `root` L264–431 (168 lines) — Board (composable + data-driven)
- `column` L433–574 (142 lines) — Board.Column + empty placeholder
- `column-header` L575–669 (95 lines) — Board.ColumnHeader
- `card` L670–846 (177 lines) — Board.Card / CardHandle / CardAdd
- `swimlane` L847–980 (134 lines) — Board.Swimlane + data-driven lanes
- `overlay` L981–988 (8 lines) — drag overlay re-export
- `skeleton` L989–1021 (33 lines) — loading placeholder
- `exports` L1022–1055 (34 lines) — compound Board namespace

---

# Breadcrumb

> Shows the current page's place in the hierarchy with links back to its ancestors.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** navigation
- **Import:** `import { Breadcrumb } from "@garn/ui/breadcrumb"`
- **Polymorphism:** `asChild` (default element `<nav>`)

## Overview
Breadcrumb shows where the current page sits in a hierarchy and lets users jump back to an ancestor. `Breadcrumb` is the `nav` landmark, `BreadcrumbList` the ordered trail, `BreadcrumbLink` each ancestor link (asChild to wrap a router Link), and `BreadcrumbPage` the current page — rendered as text with `aria-current`, not a link. It's a secondary wayfinding aid for deep hierarchies; for primary navigation use NavigationMenu, and for a multi-step task use a Stepper.

## When to use
Show where the current page sits in a hierarchy and let users jump to an ancestor.

## When not to use
A flat site with no hierarchy; the primary navigation (use a nav menu or tabs); steps in a linear flow (use a stepper).

## Do / Don't
- ✅ Mark the current page with BreadcrumbPage (it sets aria-current="page").
- ✅ Wrap your router's Link with BreadcrumbLink `asChild` for client navigation.
- ✅ Collapse long trails with BreadcrumbEllipsis instead of wrapping to many lines.
- ❌ Don't make the current page a link.
- ❌ Don't use breadcrumbs as the only navigation.
- ❌ Don't add a separator as a real list item — it's decorative.

## Guidelines
**Use breadcrumbs only for genuine hierarchy.** They earn their place when pages nest several levels deep; on a flat site they're noise. Mirror the real structure, root to current, so the trail matches how users got there.

**The last crumb is the page, not a link.** Render the current location as `BreadcrumbPage` (non-interactive, `aria-current="page"`) and make every ancestor a working link. Keep labels short and consistent with the page titles.

**Collapse long trails gracefully.** When the path is deep, truncate the middle into an ellipsis/menu rather than wrapping across lines, while keeping root and current visible. Keep it a supporting aid — don't make it the only way to navigate up.

## Anatomy

**Parts**
- `Breadcrumb` (`breadcrumb`) · required: The <nav aria-label="breadcrumb"> landmark.
- `BreadcrumbList` (`breadcrumb-list`) · required: The ordered list of crumbs (wraps + collapses gracefully).
- `BreadcrumbItem` (`breadcrumb-item`) · required: One crumb (a list item).
- `BreadcrumbLink` (`breadcrumb-link`): A link to an ancestor; `asChild` to wrap a router Link.
- `BreadcrumbPage` (`breadcrumb-page`): The current page — NOT a link (aria-current="page").
- `BreadcrumbSeparator` (`breadcrumb-separator`): Decorative divider between crumbs (defaults to a chevron); aria-hidden.
- `BreadcrumbEllipsis` (`breadcrumb-ellipsis`): Collapsed-middle indicator for long trails; aria-hidden with an sr-only label.

## Accessibility
- **Role:** navigation (APG: breadcrumb)
- **Tab:** Move between the ancestor links.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.4.8 Location (AAA); 4.1.2 Name, Role, Value (A)
- The root <nav> is labeled "breadcrumb" so it's a distinct landmark.
- The current page is BreadcrumbPage (aria-current="page"), not a link.
- Separators and the ellipsis are aria-hidden / role=presentation — they're decorative.

## Tokens
- `itemGap` → `--garn-gap-field` (air)
- `ellipsisSize` → `--garn-control-h-sm` (air)

## Related
- **composes** → `utils`
- **slotAccepts** → `link` (when BreadcrumbLink asChild wraps a router Link)

## Examples
- **basic** (canonical): Home / Components / current page.
- **collapsed** (playground): Long trail collapsed with an ellipsis.

---

# Bullet

> A compact measure-vs-target readout: a value bar over qualitative range bands with a target marker.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Bullet } from "@garn/ui/bullet"`

## Overview
Bullet is Stephen Few's answer to the gauge: a single value read against a target and a few qualitative bands (poor/ok/good), in a fraction of a gauge's space. It's ideal in dense contexts — a table cell, a KPI row — where you need measure-vs-target at a glance. It's a `meter` for assistive tech, so the value and target are announced, not just drawn.

## When to use
Show one measure against a target (and optional qualitative bands) compactly — KPI tiles, tables, dashboards.

## When not to use
A single large standalone dial (use Gauge); a ranked breakdown (use BarList); a trend (use Sparkline).

## Do / Don't
- ✅ Pass an `aria-label`; set a `target` and meaningful `ranges`.
- ✅ Use an explicit `max` when the scale is fixed (e.g. 0–100).
- ❌ Don't stuff many bands in — 2–3 qualitative zones read best.
- ❌ Don't use it where a full trend or breakdown is needed.

## Guidelines
**Prefer it to a gauge when space is tight.** A row of bullets compares many KPIs far better than a wall of dials. Reach for Gauge only when a single, large, standalone dial is the point.

**Give the bands meaning.** The qualitative `ranges` should map to real thresholds (e.g. target zones); keep them muted so the measure bar and target tick stand out. An explicit `max` fixes the scale (the value clamps to it); omit it to auto-fit.

**Announce value + target.** Pass an `aria-label`; the component folds the value and target into `aria-valuetext` so screen-reader users get the comparison, not just a number.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string` | — | no | Measure-bar colour (token ref). |
| `max` | `number` | — | no | Scale max (default: the largest of value / target / ranges). |
| `ranges` | `number[]` | — | no | Qualitative range thresholds → muted background bands (e.g. [50, 75, 100]). |
| `target` | `number` | — | no | A comparison marker (target / prior period). |
| `value` | `number` | — | yes | The measure (the actual value). |
| `valueLabel` | `string` | — | no | Accessible reading for the value (e.g. "$78k"). |

_Plus 278 inherited native `<div>` attributes._

## Anatomy
- `bullet`: The track (role=meter).
- `bullet-ranges`: Muted qualitative range bands behind the measure (decorative).
- `bullet-measure`: The value bar, in the accent colour.
- `bullet-target`: A tick marking the target value.

## Accessibility
- **Role:** meter
- **WCAG:** 1.3.1 Info and Relationships (A); 4.1.2 Name, Role, Value (A)
- role=meter with aria-valuenow (clamped) / aria-valuemin / aria-valuemax; pass an `aria-label`.
- aria-valuetext folds in the value label and the target (e.g. "78%, target 90").
- The bands, bar, and target tick are decorative.

## Related
- **composes** → `utils`
- **alternativeTo** → `gauge` (when space is tight or you're comparing many KPIs at once)
- **pairsWith** → `stat` (when shown under a Stat value as a target readout)

## Gotchas
- **The value bar exceeds the track / never maxes out.** — No explicit `max`, so the scale auto-grew to fit the value. → Pass `max` to fix the scale; the value then clamps to it.

## Examples
- **basic** (canonical): A value bar over three range bands with a target tick.
- **kpis** (edge-case): A labelled stack of bullets — a compact KPI list.

---

# Button Group

> Attaches related buttons into one segmented cluster, and hosts the split button.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** layout
- **Import:** `import { ButtonGroup } from "@garn/ui/button-group"`

## Overview
ButtonGroup binds related actions into one attached cluster — a toolbar segment, a segmented control, a split button. It collapses the seams between adjacent buttons so they read as a single unit while each stays a real button. Use it when the actions are genuinely related and benefit from being visually joined; for unrelated actions, space plain buttons apart with a gap. For picking one option from a set, a ToggleGroup is the stateful cousin.

It also hosts garn's **split button**. `SplitButton` is a thin wrapper: it shares `variant`/`tone`/`size`/`disabled` with its two halves through context — so the pair can't drift apart — and owns the seam between them, drawn from the active fill rather than a generic border token (a gray line reads as a scratch across a brand or danger solid). Both halves stay separate native buttons, which makes the cluster two tab stops and keeps the menu ARIA on the chevron half where it belongs. Leave `size` off the chevron half: an icon-only child derives the square rung matching the wrapper's, so the two can never mismatch in height.

For a static segment between the buttons — a count, a unit, a prefix — `ButtonGroupText` is cut from the same strip: same height token, same border, same collapsed inner radii.

## When to use
Bind related actions into one attached cluster — toolbars, segmented controls, and split buttons (a primary action plus a menu of related ones).

## When not to use
For unrelated actions — space them apart with plain buttons and a gap. Inside a `role="toolbar"`, don't use SplitButton at all: it isn't a roving item. And for choosing among options rather than firing actions, use ToggleGroup.

## Do / Don't
- ✅ Use the same `size` on every child so the seams align.
- ✅ Give the group an aria-label.
- ✅ Set a split button's variant/tone/size/disabled on the SplitButton wrapper, not on a half.
- ✅ Give the chevron half a contextual aria-label (“More save options”).
- ✅ Leave `size` off an icon-only chevron half — it derives the matching square rung.
- ❌ Don't mix wildly different sizes (the 1px seams misalign).
- ❌ Don't nest groups within groups.
- ❌ Don't put a SplitButton inside a role="toolbar" — it breaks the roving-focus model.
- ❌ Don't name the menu half the same as the primary — voice control can't distinguish them.
- ❌ Don't expect `disabled={false}` on a half to escape a disabled wrapper; the axis contains rather than falls through.

## Guidelines
**Group only actions that belong together.** The attached look signals relatedness — peer actions on one object, or steps of a split button. Unrelated actions joined into a bar imply a relationship that isn't there; separate them.

**Keep the cluster visually and semantically even.** Use one size and a consistent variant treatment across the group, with at most one emphasized action; a row of equally-filled buttons has no focal point. Order them by likelihood or convention.

**Preserve each button's affordances.** Every segment keeps its own label, focus ring, and disabled state — don't merge them into one ambiguous control. For a single-choice or multi-select selector, reach for ToggleGroup instead so state is modeled properly.

**Set a split button's axes on the wrapper.** `variant`, `tone`, `size`, and `disabled` belong on `SplitButton`, which hands them to both halves. Setting one on a half instead desyncs the seam — it is a sibling of the halves and can only read the wrapper's fill — and you'll get a dev warning saying so. The one thing to put on the half is the menu trigger's `aria-label`, naming what the menu opens.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | no |  |

_Plus 280 inherited native `<div>` attributes._

### `SplitButton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | yes | Exactly two halves: the primary action, then the menu half. The menu half is normally a whole `DropdownMenu` whose `DropdownMenuTrigger asChild` wraps an icon `Button` — the trigger, not this wrapper, owns the menu ARIA. |

_Plus 283 inherited native HTML attributes._

## Variants
- **orientation** (default `horizontal`): `horizontal`, `vertical`

## Anatomy
- `button-group`: The group container (role=group); children are the buttons.
- `split-button`: A SplitButton's own root — a ButtonGroup that also carries the shared axes as data-variant/data-tone/data-size, because the seam is coloured from the WRAPPER and nothing else in the DOM would show them.
- `split-button-separator`: The divider between the two halves. aria-hidden, wrapper-owned, and derived from the active fill; a real inline-start border in forced colors.
- `button-group-text` — accepts count | unit | short static label: A non-button segment cut from the same strip — shares the control-height token, border, and collapsed inner radii.

**Parts**
- `SplitButton` (`split-button`): A primary action attached to a menu of related ones. Takes `variant` (default | soft | outline | ghost | link), `tone` (neutral | brand | danger | success | warning), `size` (defaults to `md`, so the context always carries a rung), and `disabled` — the same four Button axes, handed to both halves through context; a prop set on a half wins, except `disabled`, which ORs. Reflects all three enum axes as data-variant / data-tone / data-size on its root, because the seam is coloured from the wrapper. Owns that seam and expects exactly two action children.
- `ButtonGroupText` (`button-group-text`): A static text segment inside a ButtonGroup — a count, a unit, a prefix. Takes `size` (xs | sm | md | lg | xl, default `md`); match it to the buttons beside it so the strip keeps one height.

## Accessibility
- **Role:** group (APG: menu-button)
- **Tab:** Moves through the segments one at a time — a SplitButton is TWO tab stops, one per half. The group has no roving-focus model of its own.
- **Enter / Space:** Activates the focused segment; on the chevron half, opens the menu.
- **Escape:** Closes an open menu and returns focus to the chevron half.
- **WCAG:** 2.1.1 Keyboard (A); 2.5.3 Label in Name (A); 4.1.2 Name, Role, Value (A); 2.5.8 Target Size (Minimum) (AA)
- role=group — pass aria-label naming the group's purpose (e.g. “Text alignment”).
- Children manage their own focus and roles; the group only attaches them visually.
- In a SplitButton the menu ARIA (aria-haspopup, aria-expanded) lives ONLY on the chevron half — supplied by the menu primitive through `DropdownMenuTrigger asChild`, never on the primary half or the wrapper. Both halves stay separate native buttons, so no button is ever nested inside another.
- Give the chevron half a contextual accessible name (“More save options”), not a copy of the primary's — voice control cannot pick between two identically-named controls.
- The separator is aria-hidden; the chevron svg is aria-hidden.
- **Forced colors:** The seam's painted 1px collapses to 0 and becomes a real inline-start border, so the divider survives when backgrounds are dropped.; ButtonGroupText keeps a real border.
- **Contract (error):** Renders two native <button> siblings — never a button nested in a button — and both are reachable by Tab, in DOM order. — _when SplitButton_
- **Contract (error):** aria-haspopup / aria-expanded appear only on the chevron half, never on the primary half or the wrapper. — _when SplitButton with a menu half_
- **Contract (error):** Escape closes the menu and returns focus to the chevron half. — _when SplitButton with an open menu_
- **Contract (error):** `disabled` ORs down rather than falling through: it disables both halves, and a half cannot re-enable itself with disabled={false} — the same containment fieldset[disabled] has. A half may still be disabled on its own while the wrapper is not. — _when SplitButton disabled_
- **Contract (error):** A loading primary half leaves the chevron half clickable and focusable — the wrapper never links the two. — _when SplitButton with a loading primary half_
- **Contract (error):** The separator carries data-slot="split-button-separator" and aria-hidden, and renders a real border in forced-colors mode. — _when SplitButton_
- **Contract (error):** The chevron rotates only when motion-safe applies; under reduced motion the open state still reflects via data-state. — _when SplitButton with an open menu_
- **Contract (warn):** Name the menu half for what it opens (e.g. “More save options”). — _when SplitButton whose menu half has no accessible name, or one equal to the primary half's_
- **Contract (warn):** Pass exactly two halves: the primary button, then the menu half. — _when SplitButton with other than two action children_
- **Contract (warn):** Set tone/variant on the SplitButton, not on a half — the seam is derived from the WRAPPER (a sibling element cannot read a half's fill), so an overridden half desyncs it. — _when a SplitButton half whose data-tone/data-variant disagrees with the wrapper's_
- **Contract (warn):** Don't put a SplitButton in a toolbar. It is not a roving item: its halves keep tabIndex 0 and become extra Tab stops that arrow keys skip, and it doesn't count toward the toolbar's control tally, so it can silently downgrade the whole toolbar to a plain group. Use the toolbar's own button parts, or move the split button outside. A first-class toolbar split-button part is future work. — _when SplitButton inside a role="toolbar"_

## Tokens
- `height` → `--garn-control-h-md` (air)
- **Internal (never externalize):** `--btn-fill`, `--btn-px`

## Related
- **composes** → `utils`
- **composes** → `button`
- **slotAccepts** → `button` (when as the segments)
- **pairsWith** → `dropdown-menu` (when as a split button's menu half)
- **alternativeTo** → `toggle-group` (when the segments select a value rather than fire an action)

## Recipes
- **split-button** — A primary action attached to a menu of related ones. Use the SplitButton part — it shares the axes and owns the seam; hand-assembling a ButtonGroup leaves every consumer re-solving seam, labels, and disabled. _(use when a primary action has a small set of related variants)_

## Gotchas
- **Segment corners or seams look broken.** — Children with different sizes/radii don't share an edge. → Give every child the same `size`; ButtonGroup collapses inner radii for you.
- **A split button's seam is the wrong colour — it stayed neutral while the halves went brand (and the console says so).** — `tone`/`variant` was set on a half. The seam is a SIBLING of the halves and cannot read a half's --btn-fill, so it is derived from the wrapper's axes. → Set tone/variant on the `SplitButton` wrapper; it hands them to both halves through context.
- **`<SplitButton disabled>` leaves the chevron half still clickable — or a half's `disabled={false}` doesn't re-enable it.** — Deliberate: `disabled` ORs down instead of falling through, the same containment fieldset[disabled] has. It is load-bearing — a menu trigger passes an explicit disabled={false} to the half it wraps, and fall-through would silently undo the wrapper. → Disable at the level you mean. A half can be more disabled than its wrapper, never less; to enable one half, don't disable the wrapper.
- **The chevron half renders as a wide, text-padded button instead of a square one.** — An explicit `size` on the half overrode the derived rung. → Leave `size` off the icon-only half — with no text content it resolves to the SQUARE rung matching the wrapper's (md→icon, lg→icon-lg).
- **Tab order goes strange, or arrow keys skip a split button inside a toolbar.** — A SplitButton is not a roving toolbar item: its halves keep tabIndex 0, and it doesn't count toward the toolbar's 3-control roving threshold — so it can silently downgrade the whole toolbar to a plain group. → Use the toolbar's own button parts, or move the split button outside the toolbar. A first-class toolbar split-button part is future work.
- **A group stretches to the full width (or height) of a flex parent.** — As a flex item an inline-flex box is blockified, so align-items: stretch sizes it to the cross axis. The base now sets `w-fit` to opt out. → Nothing to do by default. If you DO want the full width, `w-full` in className still wins through twMerge.
- **An arbitrary Tailwind variant targeting the open menu half emits no CSS at all — silently, with no error.** — Two chained attribute selectors in one arbitrary variant (`[&_[data-slot=button][data-state=open]_svg]`) are not parsed. Single-attribute forms work. → Use one attribute per variant — inside a split button, `[aria-haspopup]` or `[data-state=open]` each single out the menu half on their own.

## Examples
- **basic** (canonical): A horizontal segmented cluster.
- **vertical** (playground): Vertical orientation.
- **split-button** (canonical): The canonical split button: primary action, derived seam, and a contextually-named menu half.
- **split-button-appearances** (edge-case): The seam across fills and tones — derived from the fill on solids, the input-border family on the airy ones.
- **group-text** (edge-case): A ButtonGroupText segment carrying a count between two buttons.

## Source map

Regions in `button-group.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L3–10 (8 lines) — dependencies
- `variants` L12–129 (118 lines) — group, seam, section text
- `types` L131–148 (18 lines) — public surface
- `root` L150–172 (23 lines) — ButtonGroup
- `parts` L174–381 (208 lines) — SplitButton, ButtonGroupText
- `exports` L383–392 (10 lines)

---

# Button

> Triggers an action in place — submit, save, confirm, open a dialog.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** primitive
- **Import:** `import { Button } from "@garn/ui/button"`
- **Polymorphism:** `asChild` (default element `<button>`)

## Overview
Button is the workhorse of every interface — the control a person reaches for to make something happen *right now*: submit a form, save a draft, confirm a delete, open a dialog. Because it shows up everywhere, its job is to make the **emphasis** of an action legible at a glance. Button splits that into two orthogonal axes: `variant` sets the fill / emphasis (solid `default` for the one action you most want taken, `soft`/`ghost` for secondary ones) and `tone` sets the color intent (`brand`, `danger`, `success`, `warning`) — so `<Button tone="danger">` is a solid destructive action and `<Button variant="outline" tone="danger">` a quieter one. `size` and the density tokens keep it aligned with the fields and controls around it.

Reach for Button when the result is an *action in the page*, not a *destination*. The moment the click should change the URL, it's a link — render it as one (`<Button asChild><a …>`) so the browser, middle-click, and screen readers all treat it correctly.

## When to use
An in-place action: submit, save, confirm, delete, or open a dialog/menu.

## When not to use
Navigating to a URL or route — use a link, or `<Button asChild>` wrapping an anchor.

## Do / Don't
- ✅ Use one primary (or default) high-emphasis button per view as the main action.
- ✅ Give icon-only buttons an aria-label.
- ✅ Pass icons via `leading`/`trailing` so the optical padding trim applies.
- ✅ Use `loading` for work in flight — it keeps the button focusable and announced.
- ✅ Pair `state` with `onStateChange` when you want the success/error glyph to clear itself.
- ✅ Pair `fullWidth` with `justify` when a wide button should read as a row rather than a centered label.
- ❌ Don't use Button for navigation.
- ❌ Don't place two filled high-emphasis buttons side by side — demote one to soft/ghost.
- ❌ Don't hand-pad with px-* utilities; it collides with the --btn-px / optical-trim system.
- ❌ Don't set `disabled` to express pending — that drops focus to <body> and says nothing to AT. `loading` is the pending state.
- ❌ Don't expect `justify` to do anything at hug width; it only bites once the button is wider than its content.

## Guidelines
**Establish one clear primary action per view.** A screen with five filled buttons has no primary action at all. Pick the single most important action, give it the solid `variant` (with `tone="brand"` for the CTA), and demote everything else to `soft`, `ghost`, or `outline`. This is the fastest way to make a layout feel calm and decisive.

**Let emphasis match consequence.** A destructive action (`tone="danger"`) should look weightier than a benign one, and a rarely-used action shouldn't compete with the main one. Keep tone and fill orthogonal: raise or lower the fill to change emphasis, set the tone to change meaning. When two actions sit together — *Save* and *Cancel* — fill only the affirmative and keep the dismissive quiet.

**Pass icons through `leading`/`trailing`, never inline.** The slot props apply the optical-padding trim so an icon+label stays balanced across every size; hand-placing an icon and padding with `px-*` collides with the `--btn-px` system. For icon-only buttons, always supply an `aria-label` — the dev-time probe will warn you if you forget.

**Let async work stay honest.** Set `loading` for a pending action and the button keeps its width, keeps its place in the tab order, and announces itself — it is never natively `disabled`, because that drops focus to `<body>` and strands whoever pressed it. The spinner is paced rather than immediate: nothing appears for the first ~200ms, so a fast request never flashes, and once shown it stays ~300ms so a slow-ish one never blinks. When the outcome is worth showing, use `state` instead of `loading` and the spinner resolves into a check or cross; wire `onStateChange` to the same setter and the button asks to return to `idle` on its own once the glyph has been readable.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `fullWidth` | `boolean` | `false` | no |  |
| `justify` | `"between" \| "center" \| "start"` | `center` | no |  |
| `size` | `"icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `tone` | `"brand" \| "danger" \| "neutral" \| "success" \| "warning"` | `neutral` | no |  |
| `variant` | `"default" \| "ghost" \| "link" \| "outline" \| "soft"` | `default` | no |  |
| `asChild` | `boolean` | — | no |  |
| `description` | `React.ReactNode` | — | no | Secondary, de-emphasized line under the label — the compound-button shape used for dense choice UIs and onboarding CTAs. Stacks the label into a column and lets the button grow taller than its size rung. Requires a label; not valid on the icon-only sizes. It renders as ordinary content, so it JOINS the accessible name after the label ("Share publicly, Anyone with the link can view") — which is the point: the choice a compound button offers is both lines, and a screen reader user picking between them needs both. Keep it to a short phrase; pass `aria-label` if the spoken name should stay the bare verb. |
| `leading` | `React.ReactNode` | — | no | Content placed before the label — an icon, badge, counter, kbd hint, etc. Fixed width (never shrinks); only the label truncates. |
| `loading` | `boolean` | — | no | Shows a spinner and makes the button inert while keeping it FOCUSABLE (`aria-disabled` + an internal activation guard, never native `disabled` — that would drop focus to `<body>` mid-flight). Also sets `aria-busy` and announces to the shared live region. Sugar for `state="loading"`. Width is preserved — the resting content is hidden in place and the spinner is centered over it, so there's no layout shift. |
| `loadingText` | `React.ReactNode` | — | no | Optional label shown while `loading` (e.g. "Saving…"). When provided the spinner sits inline before this text instead of overlaying the content. |
| `onStateChange` | `(state: ButtonState) => void` | — | no | Called when the button asks for a different `state` — today only to request `"idle"`, once a `success`/`error` resolution has been on screen long enough to read. Wire it to the same setter that drives `state` and the reset chore disappears: ```tsx <Button state={state} onStateChange={setState} onClick={run}>Publish</Button> ``` Leave it off and the resolution holds until you clear it yourself. The button never changes `state` on its own — it only asks, so the value stays yours. |
| `state` | `ButtonState` | — | no | Full async lifecycle, for actions that should resolve visibly rather than just stop spinning: `success` / `error` swap the spinner for a check or cross that draws in, and announce completion. Controlled — pair it with `onStateChange` to have the resolution clear itself. |
| `trailing` | `React.ReactNode` | — | no | Content placed after the label — an icon, badge, kbd hint, etc. Fixed width (never shrinks); only the label truncates. |

_Plus 290 inherited native `<button>` attributes._

## Variants
- **variant** (default `default`): `default`, `soft`, `outline`, `ghost`, `link`
- **tone** (default `neutral`): `neutral`, `brand`, `danger`, `success`, `warning`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl`
- **justify** (default `center`): `center`, `start`, `between`
- **fullWidth** (default `false`): `true`, `false`

## Anatomy
- `button`: The button element (or asChild target).
- `button-leading` — accepts icon | badge | counter | kbd hint: Fixed-width content before the label; only the label truncates.
- `button-label`: The truncating text label.
- `button-label-stack`: Column wrapper around the label + description. Present only when `description` is set; it owns the truncation so a long second line can't widen the button.
- `button-description` — accepts short phrase: De-emphasized second line under the label (the compound-button shape). Ordinary content, so it JOINS the accessible name after the label.
- `button-trailing` — accepts icon | badge | kbd hint: Fixed-width content after the label.
- `button-spinner`: Loading overlay; preserves width, `aria-hidden` (the live region reports the work, not this). Mounted from the first pending frame and merely faded through the show-delay — never remounted, so the rotation doesn't restart when it appears.
- `button-status`: The same overlay slot occupied by the success/error glyph once `state` resolves. Decorative — completion is announced, not read from here.

## Accessibility
- **Role:** button (APG: button)
- **Enter / Space:** Activate the button.
- **Enter / Space:** While loading: activation is suppressed (the keydown default is prevented, which is what stops a pending submit from posting its form), but the event still forwards — a container that owns a keyboard model, like a roving toolbar, keeps reading its own keys off this handler.
- **WCAG:** 2.1.1 Keyboard (A); 1.4.11 Non-text Contrast (AA); 2.4.7 Focus Visible (AA); 2.5.8 Target Size (Minimum) (AA)
- While loading: aria-busy + aria-disabled are set and activation is blocked, but the button keeps the native focusability of a real <button> — it stays in the tab order and focus never moves. Both attributes are OR-ed with any incoming value, so a caller's own aria-disabled is preserved.
- `disabled` is independent of `loading` and keeps full native semantics (attribute set, removed from the tab order).
- `data-state` is reflected only for the non-resting values — an idle button leaves the attribute FREE, which is what lets a wrapper own it (Radix writes open/closed onto a `DropdownMenuTrigger asChild` Button, and that drives the split button's chevron).
- The spinner and the success/error glyphs are aria-hidden. State changes reach AT through the shared live region instead: polite while pending and on success, assertive on error.
- `description` renders as ordinary content, so it JOINS the accessible name after the label ('Share publicly, Anyone with the link can view').
- **Focus:** outline-hidden + 3px box-shadow ring in --btn-fill darkened 18% (hugs the button, no offset).
- **Forced colors:** forced-colors:border gives every button an edge.; disabled → GrayText for text and border.
- **Contract (warn):** Provide aria-label, aria-labelledby, title, or sr-only text. — _when size starts with 'icon' && !asChild && no accessible name (aria-label/labelledby/title/sr-only text)_
- **Contract (error):** A pending button keeps aria-disabled='true' and NO native disabled attribute, so it stays in the tab order and focus does not move when loading flips true while it is focused. — _when loading || state === 'loading'_
- **Contract (error):** Clicking or pressing Enter/Space on a pending button does not fire onClick. — _when loading || state === 'loading'_
- **Contract (error):** A plain disabled button keeps the native disabled attribute — loading is the only state that switches to aria-disabled. — _when disabled && !loading_
- **Contract (error):** Pending announces politely via the shared live region on the same show-delay as the spinner (so a sub-200ms action isn't announced then overwritten before AT reaches it); success announces politely and error assertively, on the transition itself. — _when loading || state === 'success' || state === 'error'_
- **Contract (error):** The success/error glyph swap has no transition — the finished glyph is shown, never a half-drawn one. — _when prefers-reduced-motion && (state === 'success' || state === 'error')_
- **Contract (warn):** `description` is the SECONDARY line — give it a label to sit under. — _when description != null && no text label in children_
- **Contract (warn):** `description` needs a visible label to sit under; drop it or move to a text size. — _when description != null && size starts with 'icon'_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)
- `iconInset` → `--garn-control-icon-inset` (identity)
- `ring` → `--garn-ring` · brandable
- **Internal (never externalize):** `--btn-fill`, `--btn-px`, `--btn-ps`, `--btn-pe`

## Related
- **composes** → `utils`
- **alternativeTo** → `link` (when the target is a URL or route)
- **pairsWith** → `button-group`
- **slotAccepts** → `kbd` (when as a trailing keyboard hint)

## Recipes
- **destructive-confirm** — Irreversible action gated behind a confirmation dialog. _(use when irreversible || bulk-delete, unless trivially-undoable)_
- **form-actions** — Primary submit paired with a low-emphasis cancel. _(use when a form needs a primary action)_
- **async-submit** — A submit button that reports its own request: pending while it runs, then a check or cross that clears itself. _(use when the action is asynchronous and its outcome is worth showing)_

## Gotchas
- **`variant="brand"`, `"danger"`, `"danger-outline"`, `"success"`, or `"warning"` doesn't type-check.** — Those merged tone into `variant`. O3 split the axes: `variant` is fill/emphasis, `tone` is color intent. → Move color to `tone`: brand→`tone="brand"`, danger→`tone="danger"`, danger-outline→`variant="outline" tone="danger"`, success/warning→`tone="success"`/`"warning"`.
- **Icon looks off-center next to the label.** — Optical trim fires per-occupied side via --btn-ps/--btn-pe. → Pass leading/trailing slots; never hand-pad with px-* utilities.
- **Button width jumps when entering the loading state.** — Loading overlays a hidden copy to preserve width (when no loadingText). → Rely on the default overlay; only pass loadingText when you want the inline spinner.
- **A pending button is skipped by the Tab key, or focus jumps to the top of the page when loading starts.** — `disabled={isPending}` was used for the pending state. A natively disabled element leaves the tab order, and the browser drops focus to <body>. → Use `loading={isPending}` (or `state="loading"`). It sets aria-disabled + blocks activation while keeping the button focusable and announced. Reserve `disabled` for genuinely unavailable actions.
- **The success/error glyph never goes away — the button is stuck on its check mark.** — `state` is controlled and nothing cleared it. The button never mutates `state` on its own; it only ASKS. → Wire `onStateChange` to the same setter that drives `state` (`<Button state={s} onStateChange={setS}>`), and it requests `"idle"` ~1.2s after the glyph appears. Leave the prop off and the resolution holds deliberately.
- **Nothing happens for the first fraction of a second after setting `loading` — the spinner seems broken.** — Deliberate pacing: the spinner waits ~200ms before appearing, then stays ~300ms once shown. → Nothing to fix — it's what keeps fast requests from flashing and slow ones from blinking. Don't add your own delay on top.
- **`data-state` is missing on a resting button, so a `[data-state]` selector never matches.** — Only the non-idle values are reflected — deliberately, so a wrapper can own the attribute (Radix writes open/closed onto a `DropdownMenuTrigger asChild` Button). → Target the value you mean (`[data-state="loading"]`), and treat 'attribute absent' as idle.
- **Voice control can no longer activate a button by its visible label after adding `description`.** — The description is ordinary content, so it joins the accessible name after the label — by design: the choice a compound button offers is both lines. → Accept the longer name, or pass an explicit `aria-label` if the spoken name must stay the bare verb.
- **`justify="between"` looks like it does nothing.** — The axis only shows once the button is wider than its content; at hug width all three values render identically. → Combine it with `fullWidth` (or a grid/flex cell that stretches the button).
- **Theming breaks after setting --btn-fill globally.** — --btn-fill is instance-scoped on purpose; a :root value pre-resolves and kills the shadow recipe. → Never declare --btn-fill in :root or expose it as a theme variable.

## Examples
- **basic** (canonical): Default button.
- **variants** (playground)
- **loading** (edge-case): Width preserved, no reflow.
- **icon-before** (edge-case): A leading icon clarifies the action; the optical trim keeps it centered.
- **icon-after** (edge-case): A trailing icon signals direction or progression.
- **icon-only** (edge-case): Square `icon-*` sizes — always pass an aria-label.
- **as-link** (edge-case): asChild around an anchor.
- **async-state** (canonical): The full lifecycle: paced spinner → check/cross → self-reset via `onStateChange`. Each step is announced.
- **form-status** (edge-case): React 19 `useFormStatus` driving `loading` from the enclosing form's pending state.
- **label-swap** (edge-case): Width-preserving label swap (“Copy” → “Copied”) — a grid stack, so the button never resizes.
- **full-width** (edge-case): `fullWidth` with each `justify` value — the axis only becomes visible once the button is wider than its content.
- **description** (edge-case): The compound shape: a de-emphasized second line that joins the accessible name.
- **shortcut-hint** (edge-case): A Kbd hint in the trailing slot, aria-hidden so the accessible name stays the bare verb.
- **icon-nudge** (edge-case): A trailing arrow that nudges on hover — motion-safe gated.
- **nav-antipattern** (anti-pattern): Don't: Button used for navigation. Use a link instead.

## Source map

Regions in `button.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L3–11 (9 lines) — dependencies
- `variants` L13–231 (219 lines) — fill × tone × size matrix
- `types` L233–318 (86 lines) — public surface
- `context` L320–356 (37 lines) — SplitButton defaults
- `model` L358–437 (80 lines) — pending pacing + content probes
- `parts` L439–523 (85 lines) — spinner + status glyphs
- `root` L525–898 (374 lines) — Button
- `exports` L900–902 (3 lines)

---

# Calendar

> A smart, self-constraining month-grid date picker (single, multiple, or range) built on react-day-picker. Owns first-class constraints (min/max/unavailable + clamped nav), fast navigation (dropdown captions or a grid drill-down), range preview feel, a `size` axis, per-day indicator dots, and an opt-in Today footer.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Calendar } from "@garn/ui/calendar"`

## Overview
Calendar picks a date, several dates, or a date range from a month grid — shown inline, or dropped into a Popover to build a date field. It's the smart substrate the whole date family embeds, so its constraints and navigation live here, not re-derived per picker: `minDate` / `maxDate` / `isDateUnavailable` build a single disabled matcher AND clamp navigation; fast nav is month + year dropdowns by default (`captionLayout="dropdown"`) or an opt-in `gridNavigation` drill-down. Range mode gets real feel — a preview band from the anchor to the pointed day on hover and keyboard focus, `resetOnSelect`, and `minNights` / `maxNights`. A `size` axis (sm / md / lg) drives the `--garn-calendar-cell` token; `getDayIndicators` paints up to four tone dots per day; an opt-in `showToday` footer adds a live selection summary. Use it when seeing the month in context matters (booking, scheduling, availability); when the user knows the exact date, a typed field is faster — a Calendar inside a Popover gives you both.

## When to use
Pick a date, several dates, or a date range from a month grid — inline (booking, availability, scheduling) or inside a popover as a date field. Constrain with `minDate` / `maxDate` / `isDateUnavailable`; choose `mode` for the selection; add `getDayIndicators` for per-day dots or `showToday` for a Today footer.

## When not to use
Free-form or precise date entry where typing is faster (use DatePicker / an input with a date mask); a time-only value (use TimeField / TimePicker); a date + time (use DateTimePicker); a far-future/past year jump a month grid makes tedious (use the dropdown captions or `gridNavigation`, or a typed field).

## Do / Don't
- ✅ Choose `mode` to fit the task (single / multiple / range) and hold `selected` in state with `onSelect`.
- ✅ Constrain choices with `minDate` / `maxDate` / `isDateUnavailable` rather than validating after the fact — they clamp navigation too.
- ✅ For a range, control it so the hover/focus preview band paints, and bound it with `minNights` / `maxNights`.
- ✅ Pair with Popover + a labeled trigger to build a date-picker field (or reach for DatePicker, which wires this).
- ❌ Don't force a calendar when a typed date is faster for the user.
- ❌ Don't re-derive a `disabled` matcher the constraints already build (that's the duplication this substrate removed).
- ❌ Don't leave a popover trigger unlabeled when using the calendar as a field — the placeholder isn't a name.
- ❌ Don't reimplement day rendering — theme via `classNames` / `components`, and use the published `data-slot`s.

## Guidelines
**Constrain in the grid, don't validate after.** Pass `minDate` / `maxDate` / `isDateUnavailable` rather than a hand-built `disabled` matcher — they clamp navigation and the year dropdown too, so out-of-range and blackout days can't be reached or picked. The three date pickers pass this intent straight through to the same Calendar.

**Let the use case choose inline vs popover, and the nav mode fit the range.** Show the grid inline when browsing the month is the task (availability, a range); tuck it behind a labelled trigger in a Popover for a form field. Keep the dropdown captions for arbitrary date entry; reach for `gridNavigation` when jumping across years is common. For availability views, `numberOfMonths` renders several months and `fixedWeeks` keeps their height stable.

**Keep the range and today legible, and stay keyboard-operable.** In range mode communicate the start, end, and the span between them (the preview band + the footer summary do this); today's treatment intentionally wins over selection so it's never swallowed. Arrow keys move by day, Page by month, and every day announces its full date — don't strip the focus ring or hide the month/year controls.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no | Density / airiness of the grid. Maps to `--garn-calendar-cell`. |
| `fromYear` | `number` | — | no | Bound the year dropdown / navigation when no min/max is given. |
| `getDayIndicators` | `(date: Date) => CalendarIndicatorTone[] \| undefined` | — | no | Per-day indicator dots (planned items, notifications, warnings, errors). Return one tone per dot; up to four render below the day number. |
| `gridNavigation` | `boolean` | — | no | Fast nav by drill-down: click the caption to open a year grid, then a month grid (clamped to min/max). An alternative to `captionLayout` dropdowns; forces the `label` caption. |
| `isDateUnavailable` | `(date: Date) => boolean` | — | no | Per-date disabling (holidays, blackout dates). |
| `maxDate` | `Date` | — | no |  |
| `maxNights` | `number` | — | no |  |
| `minDate` | `Date` | — | no | Lower / upper selectable bound (inclusive, day granularity). Clamps navigation, the year dropdown, and the disabled matcher. |
| `minNights` | `number` | — | no | Range mode: minimum / maximum number of nights (days) in the range. |
| `showToday` | `boolean` | — | no | Render a footer with a Today jump-and-select + an aria-live selection summary (inside rdp's `role="status"` live-region footer). |
| `todayLabel` | `string` | — | no |  |
| `toYear` | `number` | — | no |  |

_Plus 62 inherited native HTML attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`

## Anatomy
- `calendar`: The DayPicker wrapper — carries `data-size` + `data-caption-layout`. Each month is an in-flow 3-col grid: [prev] [caption] [next] on row 1, the day grid spanning all three on row 2 (navLayout="around"), so it stays content-width.
- `calendar-nav-prev`: Previous-month button, in flow to the left of the caption (styled via buttonVariants ghost). When drilled into the year/month grid it pages that grid instead of walking months.
- `calendar-nav-next`: Next-month button, in flow to the right of the caption.
- `calendar-caption`: The month caption region (month + year). Holds the dropdown selects (captionLayout="dropdown"), a plain label, or the drill-down trigger.
- `calendar-caption-trigger`: The caption-as-button shown only under `gridNavigation` — opens the year grid, then the month grid. Carries an `aria-label` describing what it changes.
- `calendar-weekday`: A weekday column head (Mon, Tue, …) in the grid's `<thead>`.
- `calendar-day`: A day cell (`<td>`); selection / today / range / preview / indicator flags land here (`data-selected`, `data-today`, `data-preview`/`-start`/`-end`, `data-indicators`). Its child is a ghost `buttonVariants` day button carrying `aria-label` + `aria-selected`.
- `calendar-footer`: The opt-in `showToday` footer, rendered inside rdp's role=status live-region. Holds the Today jump-and-select button + the selection summary.
- `calendar-summary`: The aria-live selection summary inside the footer (e.g. “Jun 4 – Jun 10, 6 nights” or “select end date”).

## Accessibility
- **Role:** grid (APG: grid)
- **ArrowLeft / ArrowRight:** Move to the previous / next day (roving focus, react-day-picker).
- **ArrowUp / ArrowDown:** Move to the same weekday in the previous / next week.
- **Home / End:** First / last day of the week.
- **PageUp / PageDown:** Previous / next month.
- **Enter / Space:** Select the focused day. In range mode, arrow-key focus also previews the band to the focused day (keyboard parity with hover).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- react-day-picker renders a labeled `role=grid` with roving focus; each day button exposes an `aria-label` (its full date), `aria-selected`, and disabled state.
- Set `mode` (single | multiple | range) to match the selection you need; the selected shape follows (Date | Date[] | DateRange).
- The in-flow prev/next nav buttons carry accessible names; the default dropdown captions are native `<select>`s (keyboard- and OS-native), each labelled.
- Under `gridNavigation`, the caption becomes a labelled button (aria-label describes the period it changes) that drills into a year grid then a month grid.
- The opt-in `showToday` footer is rendered inside react-day-picker's `role=status` / `aria-live=polite` region: a Today jump-and-select (auto-disabled when today falls outside min/max) plus a live selection summary.
- Indicator dots are purely decorative — the container is `aria-hidden` and `pointer-events-none`, so they never affect the day's name or clickability (a per-day SR summary is a documented follow-up).
- When used as the surface of a date field (inside a Popover), also give the trigger an accessible label — the placeholder is not a name.
- **Focus:** Roving focus across day cells; the focused day shows a ring. Initial focus lands on the selected day, or today clamped into the selectable window.

## Tokens
- `dayCellSize` → `--garn-calendar-cell` (air)
- `navButtonSize` → `--garn-control-h-sm` (air)
- `panelPadding` → `--garn-pad-panel` (air)

## Related
- **composes** → `utils`
- **composes** → `button` (when day + nav cells are styled via buttonVariants)
- **composes** → `use-controllable-state` (when the grid-navigation drill-down uses a controllable month)
- **pairsWith** → `popover` (when as the dropdown surface of a date-picker field)
- **pairsWith** → `input` (when as the visible date field the calendar fills)
- **alternativeTo** → `date-picker` (when the value is best typed and only occasionally picked (a field, not an always-visible month))

## Recipes
- **date-picker** — A date field: a labeled trigger opening a calendar in a popover. _(use when selecting a date in a form without leaving the page)_
- **availability-view** — An inline multi-month availability grid with blackout dates. _(use when showing which days are open/booked across several months inline)_

## Gotchas
- **Selecting a day does nothing.** — react-day-picker is controlled — `selected`/`onSelect` weren't wired. → Hold the value in state and pass `selected` + `onSelect` (with the right `mode`).
- **Type errors on `selected`/`onSelect`.** — The shape depends on `mode` (Date for single, Date[] for multiple, DateRange for range) — CalendarProps keeps that union intact. → Match the selected type to the `mode` you set.
- **The range preview band never appears while dragging out a range.** — The band paints from the anchor (start picked, no end) to the hovered/focused day — it needs a controlled range so the anchor is known. → Control the range (`selected` + `onSelect`) in `mode="range"`; the band then follows hover and arrow-key focus.
- **Nav is silently capped at the current year, or the caption shows dropdowns you didn't ask for.** — Month + year dropdowns are the DEFAULT (`captionLayout="dropdown"`); with no min/max/fromYear/toYear the year range defaults to a generous window (this year −100 … +10). → Pass `captionLayout="label"` for a plain label, or bound the years with `minDate`/`maxDate` or `fromYear`/`toYear`.
- **Out-of-range days are still reachable, or you rebuilt a `disabled` matcher.** — The constraints already build the single disabled matcher and clamp navigation. → Pass `minDate` / `maxDate` / `isDateUnavailable` instead of a hand-rolled `disabled` — don't duplicate it.

## Examples
- **basic** (canonical): An inline single-date calendar (controlled).
- **range** (edge-case): Two-month range selection with the hover/focus preview band and a 2-night minimum.
- **dropdown** (edge-case): Fast navigation via month + year dropdown captions, clamped to a fromYear/toYear range.
- **sizes** (edge-case): The size axis — sm (dense) / md / lg (airy) via --garn-calendar-cell.
- **constrained** (edge-case): minDate/maxDate clamping with weekends marked unavailable via isDateUnavailable.
- **indicators** (edge-case): Per-day indicator dots from getDayIndicators — up to four tones below the day number.
- **grid-navigation** (edge-case): Drill-down fast nav: the caption opens a year grid, then a month grid, clamped and paged.
- **availability** (edge-case): A three-month availability view with blackout dates (isDateUnavailable).

---

# Card

> A bordered surface that groups related content and actions into one unit.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** layout
- **Import:** `import { Card } from "@garn/ui/card"`

## Overview
Card groups related content and actions into one bordered surface — a summary, a form section, a list item, a dashboard tile. The compound parts give it a predictable rhythm: `CardHeader` (with `CardTitle` + `CardDescription`), `CardContent` for the body, and `CardFooter` for actions, all sharing the surface padding and field gap. It's a container, not an interaction — for a whole clickable tile wrap it in a link or button; for a floating anchored surface use Popover.

## When to use
Group related content and actions into one bordered surface — a summary, a form section, a list item, a dashboard tile.

## When not to use
A modal task (use dialog); a full-bleed page section that needs no contained surface (use plain layout); a clickable nav tile that's really a link (wrap an anchor).

## Do / Don't
- ✅ Compose with CardHeader / CardTitle / CardDescription / CardContent / CardFooter for consistent spacing.
- ✅ Put primary actions in CardFooter.
- ✅ Render CardTitle at the correct heading level so the page outline stays right.
- ❌ Don't hand-pad the card — the parts carry --garn-pad-surface.
- ❌ Don't nest cards deeply; flatten the layout or divide with a separator.
- ❌ Don't make the entire card a button — wrap a link or place a clear action inside.

## Guidelines
**Reach for a card to group, not to decorate.** A border earns its keep when it sets genuinely related content apart from the page; boxing every element makes a layout noisy. Don't nest cards inside cards — switch to a Separator or spacing instead.

**Keep one card to one idea.** A card should cover a single entity or task; if it sprouts several unrelated sections and footers, split it. Use the `CardHeader`/`Content`/`Footer` regions so padding and spacing stay consistent rather than hand-rolling them.

**Make whole-card affordances real.** If the entire card is clickable, render it as one link/button with a single focus ring and accessible name — don't scatter nested click targets that fight the outer one. Right-align footer actions and lead with the primary one.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `elevation` | `"hairline" \| "raised"` | `raised` | no |  |

_Plus 280 inherited native `<div>` attributes._

## Variants
- **elevation** (default `raised`): `raised`, `hairline`

## Anatomy

**Parts**
- `Card` (`card`) · required: The surface: rounded border, shadow, card background.
- `CardHeader` (`card-header`): Top region; stacks title + description with the field gap and surface padding.
- `CardTitle` (`card-title`): The card's heading text.
- `CardDescription` (`card-description`): Muted supporting text under the title.
- `CardContent` (`card-content`): The main body region (surface padding, no top padding).
- `CardFooter` (`card-footer`): Bottom region for actions (surface padding, no top padding).

## Accessibility
- **WCAG:** 1.3.1 Info and Relationships (A)
- Card is a styled <div> with no implicit role — structure meaning with a real heading (CardTitle) and the page's landmark regions.
- If the whole card is a target, wrap a real link/button; don't bolt a click handler onto the surface.

## Tokens
- `padding` → `--garn-pad-surface` (air)
- `headerGap` → `--garn-gap-field` (air)

## Related
- **composes** → `utils`
- **slotAccepts** → `button` (when as a footer action)
- **slotAccepts** → `aspect-ratio` (when to frame media in the header/content)
- **pairsWith** → `separator` (when to divide internal sections)
- **pairsWith** → `badge` (when as a status/label in the header)

## Recipes
- **card-with-actions** — A titled card whose footer holds the primary and secondary actions. _(use when a self-contained unit needs its own actions)_

## Examples
- **basic** (canonical): Header + content + footer actions.

---

# Carousel

> A horizontally or vertically scrolling set of slides with prev/next controls.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Carousel } from "@garn/ui/carousel"`

## Overview
Carousel shows a set of peer items — images, cards, testimonials — in a swipeable/steppable track when they don't all fit at once. `Carousel` is the Embla-backed region (sets orientation/options, handles arrow keys), `CarouselContent` the track, `CarouselItem` each slide, with `CarouselPrevious`/`CarouselNext` auto-disabling at the ends. Use it for browsable peer media; for content users must not miss, lay it out directly — carousels hide everything but the current slide.

## When to use
Show a set of peer items (images, cards, testimonials) in a swipeable/steppable track when they don't all fit at once.

## When not to use
Essential content users must not miss (don't hide it off-screen); a long ordered list (use a list + pagination); switching between distinct views (use tabs).

## Do / Don't
- ✅ Give the Carousel an aria-label; keep prev/next reachable.
- ✅ If you autoplay, provide a pause/stop control (and respect reduced motion).
- ✅ Grab the Embla `api` via `setApi` when you need programmatic control or a dot indicator.
- ❌ Don't bury important content in later slides.
- ❌ Don't autoplay without a way to pause.
- ❌ Don't use a carousel where the items should all be visible (use a grid).

## Guidelines
**Use a carousel only for genuinely optional, peer content.** Anything important shouldn't depend on a user swiping to find it — carousels have low engagement past the first slide. A short, equally-weighted set (a gallery, featured cards) is the sweet spot.

**Make navigation obvious and keyboard-operable.** Show prev/next controls and position indicators; the track responds to arrow keys and the buttons disable at the ends — don't hide the only way to advance behind a hover. Let users control the pace.

**Avoid aggressive autoplay.** If it auto-advances, make it slow, pausable, and stopped on focus/hover; honor reduced-motion. Each slide is announced as one of N — keep slides self-contained so they make sense out of sequence.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `opts` | `Partial<OptionsType>` | — | no |  |
| `orientation` | `"horizontal" \| "vertical"` | — | no |  |
| `plugins` | `CreatePluginType<LoosePluginType, {}>[]` | — | no |  |
| `setApi` | `(api: CarouselApi) => void` | — | no |  |

_Plus 280 inherited native HTML attributes._

## Anatomy

**Parts**
- `Carousel` (`carousel`) · required: Root (role=region, aria-roledescription=carousel) — sets `orientation`/`opts`/`plugins`, exposes the Embla `api` via `setApi`, and handles arrow-key nav.
- `CarouselContent` (`carousel-content`) · required: The Embla viewport + flex track that holds the items.
- `CarouselItem` (`carousel-item`) · required: One slide (role=group, aria-roledescription=slide); full-basis by default.
- `CarouselPrevious` (`carousel-previous`): Previous-slide Button; auto-disables at the start.
- `CarouselNext` (`carousel-next`): Next-slide Button; auto-disables at the end.

## Accessibility
- **Role:** region
- **ArrowLeft:** Previous slide (when the carousel has focus).
- **ArrowRight:** Next slide (when the carousel has focus).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.2.2 Pause, Stop, Hide (A)
- Root is role=region aria-roledescription="carousel"; each item is role=group aria-roledescription="slide".
- Give the carousel an accessible name (aria-label) describing what it contains.
- Prev/Next have sr-only labels and disable at the ends so state is conveyed without color.

## Related
- **composes** → `utils`
- **composes** → `button`
- **alternativeTo** → `tabs` (when the slides are distinct views rather than peer items)

## Gotchas
- **useCarousel throws 'must be used within a <Carousel />'.** — CarouselContent/Item/Previous/Next read context from the Carousel root. → Wrap all carousel parts in a single <Carousel>…</Carousel>.
- **Prev/Next don't appear or get clipped.** — They're absolutely positioned just outside the track; a tight/overflow-hidden container hides them. → Leave horizontal room around the Carousel (or reposition the controls).

## Examples
- **basic** (canonical): Five numbered slides with prev/next.

---

# Chart

> Token-themed chart primitives (container, config, tooltip, legend, data-table) composed with Recharts.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Chart } from "@garn/ui/chart"`

## Overview
Chart is not one chart — it's the themed primitives every chart is built from: a `ChartContainer` that turns a typed `ChartConfig` into scoped `--color-<series>` tokens and token-styles the SVG, plus a garn-styled tooltip, legend, data-table, reference lines, gradients, and loading/empty states. You compose these with the underlying library's chart elements; each chart *type* — line, area, bar, pie, scatter, radar, radial, combo, funnel — is a recipe, not a bespoke component. Recharts is the engine, added only when you copy a chart in (the sparkline and gauge stay engine-free).

## When to use
Build a real chart with axes, tooltip, and legend — line, area, bar, pie, scatter, radar, radial, combo, funnel.

## When not to use
An inline trend with no chrome (use Sparkline); a single value vs a target (use Gauge or Bullet); a ranked list (use BarList).

## Do / Don't
- ✅ Drive series colours from `config` → `var(--color-<series>)`; enable `accessibilityLayer`.
- ✅ Pair every chart with an accessible name + `ChartDataTable`.
- ❌ Don't hardcode colours or reach past the primitives into raw library styling.
- ❌ Don't ship a chart with no accessible name or data-table equivalent.
- ❌ Don't hand-wire `isAnimationActive` per series just to respect reduced motion — the container already does; reserve the per-series prop for real exceptions (e.g. the polar 0×0 gotcha).

## Guidelines
**Compose, don't configure.** garn ships primitives + recipes, not a `<LineChart data={} />` engine — you write the chart body in JSX and keep full control (mirrors the table decision). Copy a recipe and swap the `data`.

**Theme through `config`.** Point each series' `color` at a `--garn-chart-*` token; the container injects `var(--color-<series>)`, so dark mode and re-theming come for free. Never hardcode a hex.

**Own the accessibility.** A chart needs an accessible name and a text/data-table equivalent (`ChartDataTable` gives you one for free), plus `accessibilityLayer` for keyboard + tooltip-on-focus. Distinguish series with more than colour.

**Format for humans.** Use `numberFormatter`/`dateFormatter` for axis ticks and tooltips, and a per-series `config.formatter` so values read as currency/percent/dates.

**Let the container own motion.** The entrance animation is JS-driven, so CSS `motion-reduce` can't stop it — `ChartContainer` does: it defaults `isAnimationActive` onto the series and turns animation off under `prefers-reduced-motion`. Set `animate={false}` for a static chart (screenshots, print, visual-regression suites); a per-series `isAnimationActive` overrides the default either way, and custom series read `useChart().animate`.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `animate` | `boolean` | — | no | Entrance/update animation for the series inside. The container defaults `isAnimationActive` onto the library's series (and tooltip) so animation turns off automatically under `prefers-reduced-motion`; set `false` to force a static chart (screenshots, print). A series' own explicit `isAnimationActive` always wins over this default. |
| `children` | `React.ReactNode` | — | yes | A single Recharts chart element (e.g. `<LineChart>…</LineChart>`). |
| `config` | `ChartConfig` | — | yes | Series-key → label + token color map. Drives tooltip/legend + `--color-*`. |

_Plus 279 inherited native `<div>` attributes._

## Anatomy
- `chart`: The themed container: sizes the box, injects the scoped `--color-<series>` vars from `config`, token-styles the library's SVG, wraps children in a responsive container, and owns series animation (the `animate` prop gated by `prefers-reduced-motion`). Carries `data-chart` + `data-animate`.

**Parts**
- `ChartContainer` (`chart`) · required: Root; provides the `config` context + theming. Takes `config` and a single chart child. Defaults `isAnimationActive` onto the series inside (`animate` prop, off under `prefers-reduced-motion`); a series' own explicit value wins, and custom series read `useChart().animate`.
- `ChartTooltip`: Interaction primitive (the library Tooltip), re-exported.
- `ChartTooltipContent` (`chart-tooltip-content`): Token-styled tooltip card: label + per-series swatch/value; `indicator`, `hideLabel`, `nameKey`, config-driven `formatter`.
- `ChartLegend`: Interaction primitive (the library Legend), re-exported.
- `ChartLegendContent` (`chart-legend-content`): Token-styled legend; `hidden` + `onItemClick` make it an interactive show/hide toggle (consumer owns the state).
- `ChartDataTable` (`chart-data-table`): The a11y data-table equivalent, generated from `config` + `data` (Intl `numberFormat`, `collapsible`).
- `ChartReferenceLine`: Target/threshold line (aliased so the library detects it by type); token-styled by the container.
- `ChartReferenceArea`: Shaded reference band (aliased).
- `ChartLabelList`: Data labels on marks (aliased); label text is token-styled.
- `ChartGradient`: A subtle same-hue fill gradient for areas/bars; put in `<defs>` with a unique id.
- `ChartSkeleton` (`chart-skeleton`): A chart-shaped loading placeholder (composes Skeleton).
- `ChartStyle`: Internal — emits the scoped `--color-<series>` custom properties from `config`.

## Accessibility
- **WCAG:** 1.1.1 Non-text Content (A); 1.4.1 Use of Color (A); 1.4.11 Non-text Contrast (AA); 2.1.1 Keyboard (A); 2.3.3 Animation from Interactions (AAA)
- Give the chart an accessible name (a `<figcaption>` + `aria-labelledby`, or `aria-label`).
- Provide a text/data-table equivalent — `ChartDataTable` generates one from the same config + data.
- Enable the library's `accessibilityLayer` for a single tab stop + arrow-key point navigation + tooltip-on-focus.
- Distinguish series without colour alone (markers / dashes / direct labels); series colours meet ≥3:1 in both themes.
- Series entrance animation is disabled automatically under `prefers-reduced-motion` (the container defaults `isAnimationActive` onto its series) — don't re-enable it per-series without cause.

## Related
- **composes** → `utils`
- **pairsWith** → `stat` (when charts sit beside KPI tiles in a dashboard)
- **alternativeTo** → `sparkline` (when you need an inline trend with no axes/legend)

## Gotchas
- **Pie / radial / radar render nothing.** — A Recharts v3 polar chart inside a responsive container that briefly measured 0×0 gets stuck. → Set `isAnimationActive={false}` on the Pie/RadialBar/Radar.
- **Tooltip/legend content is blank in tests.** — The library reports 0×0 in jsdom, so no payloads reach the content slots. → Verify those in the browser/lab; unit-test the engine-free parts (ChartDataTable, ChartStyle, hooks).
- **Gradient fill shows no colour.** — The `<linearGradient>` id isn't unique / not referenced. → Give ChartGradient a `useId()` id and set `fill={`url(#${id})`}`.
- **`useChart must be used within a <ChartContainer />`.** — A tooltip/legend content or hook rendered outside the container. → Keep them inside ChartContainer (which provides the config context).
- **Charts flake in screenshot/visual-regression runs (marks mid-entrance).** — The ~1.5 s entrance animation is JS-driven and still running at capture time. → Set `animate={false}` on ChartContainer, or emulate `prefers-reduced-motion: reduce` in the test browser — both render the final frame immediately.
- **A custom series (or function-as-child chart) still animates under reduced motion.** — The container's `isAnimationActive` defaulting only reaches the library's own elements at the chart's top level. → Read `useChart().animate` and pass it to your element's `isAnimationActive` yourself.

## Examples
- **basic** (canonical): Area chart with accessible name, gradient fills, tooltip, legend + a ChartDataTable.
- **bar** (edge-case): Stacked bars with rounded tops.
- **line** (edge-case): Multi-series line with active dots.
- **pie** (edge-case): Donut with a token-tinted slice palette.
- **interactive-legend** (edge-case): Click the legend to toggle series (useChartVisibility).
- **reference-line** (edge-case): A dashed target line via ChartReferenceLine.
- **states** (edge-case): Loading (ChartSkeleton) + empty (Empty).
- **formatting** (edge-case): Intl date/compact-currency axes + data labels.
- **combo** (edge-case): Dual-axis composed bar + line.
- **scatter** (edge-case): Two numeric axes; correlation.
- **radar** (edge-case): Multi-axis comparison of two series.
- **radial-bar** (edge-case): Concentric progress rings.
- **funnel** (edge-case): Conversion funnel with stage labels.

---

# Checkbox

> A binary (or indeterminate) choice, typically submitted with a form.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Checkbox } from "@garn/ui/checkbox"`

## Overview
Checkbox toggles a single independent boolean ("Remember me", "I agree") or selects several items from a list where choices aren't mutually exclusive. It supports an `indeterminate` state for a parent that summarizes a partially-selected group. Reach for RadioGroup instead when exactly one of a few options must be chosen, or Switch when the change applies immediately with no Save step.

## When to use
Toggle an independent boolean, or select several items from a list.

## When not to use
An on/off that takes effect immediately (use a switch); one choice among mutually exclusive options (use radio-group).

## Do / Don't
- ✅ Pair with a clickable label and keep the hit target generous.
- ✅ Use the `indeterminate` state for a parent that summarizes a partially-checked group.
- ❌ Don't use a checkbox for a setting that applies instantly — that's a switch.
- ❌ Don't group mutually exclusive options as checkboxes — use radio-group.

## Guidelines
**Pair every checkbox with a Label.** The box alone is a tiny hit target with no accessible name; an associated Label both names it and extends the click area to the text. Keep the wording affirmative so checking it means "yes" — "Send me updates", not "Don't send updates".

**Use `indeterminate` only for a summary parent.** It's the visual for "some but not all children selected" in a select-all pattern — never a third user-settable value. Drive it from the children's state; clicking it should resolve to all-on or all-off.

**Don't make a checkbox apply instantly.** Checkboxes imply a pending choice confirmed on submit; if the toggle takes effect the moment it changes (a setting), that's a Switch. Group related checkboxes under a shared heading or fieldset so the relationship is announced.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |

_Plus 294 inherited native `<button>` attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`

## State model
- `checked` (controlled) / `defaultChecked` (uncontrolled), `onCheckedChange` · boolean | 'indeterminate' — Controlled via `checked` + `onCheckedChange`; uncontrolled via `defaultChecked`.
- Selection: single.

## Anatomy
- `checkbox`: The checkbox box (hit target + drawn shape).
- `indicator`: The check glyph; shown when checked or indeterminate.

## Accessibility
- **Role:** checkbox (APG: checkbox)
- **Space:** Toggle checked / unchecked.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- data-state reflects checked / unchecked / indeterminate (Radix maps it to aria-checked).
- **Focus:** outline-hidden + 2px ring with a 2px offset.
- **Forced colors:** checked → Highlight / HighlightText so the state survives HCM.
- **Contract (warn):** Give every checkbox an accessible label (a clickable <label htmlFor>, or aria-label). — _when no associated <label> or aria-label/aria-labelledby_

## Tokens
- `size` → `--garn-box-md` (identity)
- `fill` → `--garn-brand-solid` · brandable
- `ring` → `--garn-ring` · brandable

## Related
- **composes** → `utils`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `switch` (when the toggle applies immediately rather than on submit)
- **alternativeTo** → `radio-group` (when the options are mutually exclusive)

## Recipes
- **labeled-checkbox** — A checkbox with a clickable label. _(use when offering a single boolean opt-in (e.g. accept terms))_

## Gotchas
- **The checkbox won't change when clicked.** — Passing `checked` without `onCheckedChange` makes it controlled and frozen. → Use `defaultChecked` for uncontrolled, or pass `checked` + `onCheckedChange`.

## Examples
- **basic** (canonical): Default checkbox.
- **labeled** (canonical): Checkbox with a clickable label.
- **indeterminate** (edge-case): The third state.
- **disabled** (edge-case)

---

# Collapsible

> A single region that expands and collapses.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** disclosure
- **Import:** `import { Collapsible } from "@garn/ui/collapsible"`
- **Polymorphism:** `asChild`

## Overview
Collapsible shows or hides a single independent region — a "show more", an expandable table row, an optional details block. `Collapsible` owns the open state, `CollapsibleTrigger` toggles it (asChild to wrap your own control), and `CollapsibleContent` is the region. It's the one-region primitive; for a set of stacked, related sections use an Accordion, and for switching between peer panels use Tabs.

## When to use
Show/hide a single independent region — a 'show more', an expandable row, an optional details block.

## When not to use
Several stacked sections with one-open-at-a-time behavior (use accordion); switching peer views (use tabs); a floating surface (use popover/dialog).

## Do / Don't
- ✅ Pair one CollapsibleTrigger with one CollapsibleContent.
- ✅ Use `open`/`onOpenChange` (controlled) or `defaultOpen` (uncontrolled).
- ✅ Make the trigger a real, focusable button.
- ❌ Don't use a Collapsible for many sections — that's accordion.
- ❌ Don't hide essential content behind an unclear trigger.

## Guidelines
**Use it for one optional region, not a set.** A single show/hide is exactly its job; the moment you have several coordinated sections, an Accordion models that better. Keep the trigger label describing what expands ("Show details").

**Don't hide essential content behind it.** Collapse genuinely secondary detail — required fields or critical info shouldn't start hidden where users may never expand them. Default-open when the content is usually wanted.

**Wire the state for assistive tech.** The trigger reflects `aria-expanded` and controls the region — keep that link intact and make the trigger a real button. Avoid animating height in a way that fights reduced-motion.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen`.
- Selection: single.

## Anatomy

**Parts**
- `Collapsible` (`collapsible`) · required: Root — owns the open state.
- `CollapsibleTrigger` (`collapsible-trigger`) · required: Toggles the region (asChild to wrap your own button).
- `CollapsibleContent` (`collapsible-content`) · required: The region that shows/hides.

## Accessibility
- **Enter / Space:** Toggle the region.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- The trigger is a button with aria-expanded + aria-controls pointing at the content region.

## Related
- **alternativeTo** → `accordion` (when you have multiple sections and want single-open-at-a-time behavior)
- **pairsWith** → `button` (when as the toggle trigger)

## Examples
- **basic** (canonical): A show-more region toggled by an icon button.

---

# Combobox

> A searchable single-select — a field-styled trigger that opens a Popover with a cmdk search box and a filtered listbox. Accent-insensitive matching, grouped + rich options, a data-driven options prop, async/loading, opt-in free-text create, a clear control, and an aria-live result-count announcer.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Combobox } from "@garn/ui/combobox"`

## Overview
Combobox picks one option from a long list where typing to filter helps — a typeahead/autocomplete field (country, user, repo). Its field-styled `trigger` shares the `appearance` × `size` surface with Input and Select, opening a searchable listbox of `Combobox.Item`s (group/separate/empty as needed). Drive `inputValue` for server-side search and opt into `allowCustomValue` for free-text tags. Use Select when the list is short and search adds nothing; use Command for an app-wide action palette.

## When to use
Pick one option from a long list where search helps — a typeahead/autocomplete field. Use the `options` prop or compound ComboboxItem children, drive `inputValue` for server-side search, and opt into `allowCustomValue` for free-text tags/labels.

## When not to use
A short list where seeing every option helps (use Select or RadioGroup); an action palette / command menu (use Command); a Select-based picker with no search (use BadgeSelect); free-form text with no option list (use Input); choosing many (this is single-select — a MultiCombobox is a fast-follow).

## Do / Don't
- ✅ Label the trigger (aria-label / aria-labelledby / id + <label>) — the placeholder isn't a name.
- ✅ Give every ComboboxItem a stable, unique `value`; put human text in the label (matching uses it via keywords).
- ✅ For server-side search, set `filter={false}`, drive `inputValue` + `loading`, and feed pre-filtered `options`.
- ✅ Use `allowCustomValue` + `onCreate` for tag/label inputs where new values are allowed.
- ✅ Use the `options` prop for data, or compound children for rich/custom rows — one or the other, not both.
- ❌ Don't reach for Combobox when 2–5 options would be clearer fully visible — that's Select / RadioGroup.
- ❌ Don't treat the search text as the value — `inputValue` is the transient filter; `value` is what's committed.
- ❌ Don't nest the clear button inside the trigger — it's a real sibling (the component already wires this).
- ❌ Don't disable the result-count announcer or the focus ring — they're the a11y contract.

## Guidelines
**Reach for Combobox when search is the point.** If the list is short enough to scan, a plain Select is simpler; Combobox earns its weight on long or remote datasets. For server-side results, control `inputValue` and debounce the query rather than filtering everything client-side.

**Give items stable values and searchable text.** Each `Item` needs a stable `value`; put the human-readable words in its keywords so matching works even when the label is an id or is abbreviated. Always render an empty state so "no matches" is explicit.

**Keep the field accessible and the custom-value path deliberate.** Pair it with a Label, preserve the listbox keyboard model (type, arrow, enter), and only enable `allowCustomValue` when free text is genuinely valid (tags/labels) — otherwise restrict to the known set.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `"aria-invalid"` | `"false" \| "true" \| boolean` | — | no |  |
| `"aria-label"` | `string` | — | no |  |
| `"aria-labelledby"` | `string` | — | no |  |
| `allowCustomValue` | `boolean` | — | no | Allow committing search text that matches no option (free-text). |
| `children` | `React.ReactNode` | — | no | Compound `ComboboxItem` / `ComboboxGroup` children. |
| `className` | `string` | — | no | Applied to the trigger (the visible control surface). |
| `clearable` | `boolean` | — | no | Show a clear button on the trigger when a value is selected. Default true. |
| `clearLabel` | `string` | — | no |  |
| `contentClassName` | `string` | — | no | Applied to the popup content. |
| `createLabel` | `(inputValue: string) => React.ReactNode` | — | no |  |
| `defaultInputValue` | `string` | — | no |  |
| `defaultOpen` | `boolean` | — | no |  |
| `defaultValue` | `string` | — | no |  |
| `disabled` | `boolean` | — | no |  |
| `emptyText` | `React.ReactNode` | — | no | No-results content (used with the `options` prop; ignored if a `ComboboxEmpty` child is given). |
| `filter` | `ComboboxFilter \| false` | — | no | Match function, or `false` to disable client filtering (feed pre-filtered `options` for server-side search). Defaults to an accent-insensitive fuzzy match. |
| `id` | `string` | — | no |  |
| `inputValue` | `string` | — | no | In-popover search text (controlled) — drive this for server-side search. |
| `leading` | `React.ReactNode` | — | no | Trigger leading content; overrides the mirrored selected-option leading. |
| `loading` | `boolean` | — | no | Pending state: a spinner + a loading row + `aria-busy` + an announced "loading". |
| `loadingText` | `string` | — | no |  |
| `name` | `string` | — | no | Name for the hidden input mirroring `value` on form submit. |
| `onClear` | `() => void` | — | no |  |
| `onCreate` | `(value: string) => void` | — | no | Called when a free-text value is committed; also renders a "Create …" row. |
| `onInputValueChange` | `(inputValue: string) => void` | — | no |  |
| `onOpenChange` | `(open: boolean) => void` | — | no |  |
| `onValueChange` | `(value: string \| undefined) => void` | — | no |  |
| `open` | `boolean` | — | no | Popover open state (controlled). |
| `options` | `ComboboxOption[]` | — | no | Data-driven options — an alternative to compound children (one or the other). |
| `placeholder` | `string` | — | no | Trigger text when nothing is selected. |
| `ref` | `React.Ref<HTMLButtonElement>` | — | no | The trigger's ref. |
| `required` | `boolean` | — | no |  |
| `searchLabel` | `string` | — | no | Accessible name for the search input (role=combobox). |
| `searchPlaceholder` | `string` | — | no | Search input placeholder (defaults to `placeholder`). |
| `value` | `string` | — | no | Committed selection (controlled). |

_Plus 3 inherited native `<button>` attributes._

### `Combobox.Item` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `description` | `React.ReactNode` | — | no | Secondary line under the label. |
| `leading` | `React.ReactNode` | — | no | Leading glyph; mirrors into the trigger when this option is selected. |
| `textValue` | `string` | — | no | String used for trigger display + matching when `children` is a non-string node. |
| `value` | `string` | — | yes | Stable value committed on select (required). |

_Plus 283 inherited native HTML attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The committed selection (the option's value, or free text). Cleared to undefined by the clear control.
- `inputValue` (controlled) / `defaultInputValue` (uncontrolled), `onInputValueChange` · string — The in-popover SEARCH text — separate from `value`. Drive it for server-side search; it resets on open.
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Whether the listbox popover is open.
- Selection: single.

## Anatomy
- `combobox`: The relative wrapper — the positioning context for the clear overlay.
- `combobox-trigger`: The field-styled button that opens the listbox (carries the appearance × size axes, aria-haspopup=listbox, data-state). Mirrors the selected option's label + leading.
- `combobox-trigger-leading`: Leading glyph on the trigger — the `leading` prop, or the selected option's mirrored leading.
- `combobox-trigger-label`: The trigger text — the selected option's label, the raw value (free-text), or the placeholder.
- `combobox-clear`: The clear button — a real sibling button overlaid left of the chevron (never nested in the trigger). Shown when clearable + a value is set.
- `combobox-input`: The in-popover search field (cmdk CommandInput) — the transient filter, NOT the persisted value.
- `combobox-list`: The scrollable filtered listbox (cmdk CommandList).
- `combobox-loading-row`: The pending row — a spinner + loadingText while async results resolve.
- `combobox-create`: The free-text 'Create …' row, shown when allowCustomValue and the trimmed search matches no option.

**Parts**
- `Combobox.Item` (`combobox-item`) · required: A selectable option row — leading + label (+ description) + a check when selected. Requires a stable `value`; human text rides in keywords for matching.
- `Combobox.Group` (`combobox-group`): A labelled section of options (cmdk CommandGroup with a heading).
- `Combobox.Separator` (`combobox-separator`): A divider between groups.
- `Combobox.Empty` (`combobox-empty`): The no-results state — cmdk auto-renders it when the filtered count is 0 (or pass emptyText with the options prop).

## Accessibility
- **Role:** combobox (APG: combobox)
- **Enter / Space:** Open the listbox (focus moves into the search input).
- **A–Z:** Type in the search to filter (accent-insensitive contains).
- **ArrowDown / ArrowUp:** Move the active option (tracked via aria-activedescendant; DOM focus stays in the input).
- **Enter:** Commit the active option (or the free-text value / 'Create' row) and close.
- **Escape:** Close the popover; focus returns to the trigger.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The trigger button carries aria-haspopup=listbox and reflects data-state; on open, focus moves into the cmdk search input which is the real role=combobox with aria-expanded / aria-controls / aria-activedescendant / aria-autocomplete.
- A visually-hidden role=status aria-live region announces the result count / no-results / loading — the supplement VoiceOver/NVDA need because activedescendant counts are dropped.
- Roving tabindex is deliberately NOT used (per the APG combobox pattern) — the active option is tracked via aria-activedescendant while DOM focus stays in the input.
- The placeholder is NOT an accessible name — label the trigger via aria-label, aria-labelledby, or an `id` paired with <label htmlFor>.
- The clear button is a real sibling button (never nested in the trigger) with its own accessible label.
- **Focus:** Trigger border darkens (foreground/40) + a subtle ring on focus-visible and while open; focus moves into the search on open and returns to the trigger on close (Radix).
- **Contract (warn):** Give the trigger an accessible name via aria-label, aria-labelledby, or an id + <label htmlFor>. — _when the Combobox trigger has no `aria-label`, `aria-labelledby`, or an `id` paired with a <label htmlFor> (the placeholder doesn't count)_

## Tokens
- `triggerHeight` → `--garn-control-h-md` (air)
- `triggerPaddingInline` → `--garn-control-px-md` (air)
- `itemMinHeight` → `--garn-control-h-md` (air)

## Related
- **composes** → `utils`
- **composes** → `field-variants` (when the trigger consumes the shared fieldVariants surface (identical to Input/Select))
- **composes** → `popover` (when the listbox lives in a Radix Popover anchored to the trigger)
- **composes** → `spinner` (when the loading state shows a Spinner in the trigger + a loading row)
- **composes** → `cmdk` (when the search input + filtered listbox are a cmdk Command (the vendored, boundary-patched engine in lib/cmdk — no npm dep))
- **pairsWith** → `label` (when a <Label htmlFor> names the trigger)
- **pairsWith** → `form` (when the hidden input mirrors `value` on submit)
- **alternativeTo** → `select` (when the list is short enough that search adds nothing)
- **alternativeTo** → `command` (when the popup runs actions/navigation rather than committing a field value)
- **alternativeTo** → `badge-select` (when a Select-based picker (no in-place search) fits)

## Recipes
- **labeled-combobox** — A labelled searchable single-select field. _(use when choosing one option from a long, searchable list in a form)_
- **async-combobox** — Server-side search — disable the client filter, drive inputValue + loading, feed results. _(use when options come from a remote search endpoint)_

## Gotchas
- **The selected value disappears or the field shows the search text.** — Conflating `value` (committed) with `inputValue` (the transient search) — they're separate, controllable states. → Bind `value` + `onValueChange` for the selection; only touch `inputValue` for server-side search.
- **Server results never show, or show double-filtered.** — The client fuzzy filter is still on top of your pre-filtered results. → Set `filter={false}`, drive `inputValue` + `loading`, and feed the already-filtered `options`.
- **Screen readers announce the field with no name.** — The placeholder is not an accessible name (a dev console warns). → Pass aria-label / aria-labelledby, or an `id` paired with <label htmlFor>.
- **Typing a new value can't be committed.** — Free-text is opt-in; without it, only existing options commit. → Set `allowCustomValue` (and `onCreate` to persist it) — a 'Create …' row then appears.
- **An option can't be found by typing its visible text.** — cmdk matches on `value` (often an opaque id) + keywords, not the rendered node. → Pass `textValue` (or keywords) when the label is a non-string node so the human text stays searchable.

## Examples
- **basic** (canonical): Controlled single-select over a list of fruits.
- **with-label** (edge-case): A <Label htmlFor> wired to the trigger via id.
- **appearances** (playground): outline · soft · ghost (shared field surface).
- **sizes** (edge-case): xs · sm · md · lg · xl trigger heights.
- **grouped** (edge-case): The data-driven `options` prop grouped by region.
- **rich-options** (edge-case): Rich rows — avatar leading + a description line.
- **async** (edge-case): Server-side search — filter=false, driven inputValue + loading, latest-wins.
- **free-text** (edge-case): allowCustomValue + onCreate — a label input that creates new values.
- **invalid** (edge-case): aria-invalid with a danger border + recovery message.
- **disabled** (edge-case): A disabled trigger that won't open.

---

# Command

> An agent-native ⌘K command palette — a searchable, keyboard-first list that navigates nested sub-command pages, handles async loading / error / empty states, ranks recents, binds per-item shortcuts that actually fire, and opens a per-row action panel on → / ⌘.. CommandDialog is the canonical host (⌘/Ctrl + optional `/` open-shortcut, controllable open, imperative apiRef).

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { Command } from "@garn/ui/command"`

## Overview
Command lets users find and run an action — or jump to a thing — by typing: a ⌘K palette, a searchable action menu, a quick switcher. It's cmdk's combobox+listbox engine wearing the garn layer, elevated to do four things a thin wrapper can't. It NAVIGATES: push nested sub-command pages (pick a project → pick an action) with a back-pill and Backspace-to-pop, or jump straight in with a leading-token `prefix`. It WAITS: `CommandLoading` / `CommandError` / a refined `CommandEmpty` are first-class async states, not a single 'no results'. It REMEMBERS: `useRecentCommands` ranks by recency + frequency and biases the filter so power users' commands float up. And it ACTS: an item's `shortcut` both shows AND fires, and `CommandItemActions` gives each row a secondary-action panel on → / ⌘.. `CommandDialog` is the one canonical host — it owns the open-shortcut, controllable open state, and an imperative `apiRef` (agent-native), and `AppShellCommand` is a thin pass-through over it. Four headless hooks carry the behavior: `useCommandShortcut` (bind the open key), `useCommandPages` (read/drive the stack), `useRecentCommands` (ranking + injectable store), `useCommandSearch` (debounced async with request cancellation).

## When to use
Let users find and run an action (or jump to a thing) by typing — a ⌘K command palette, a searchable action menu, a quick switcher. Reach for the elevated surface when the palette must navigate sub-commands (nested pages / prefix routing), search an async source, rank recents, bind per-item shortcuts, or expose per-row secondary actions.

## When not to use
A short fixed set of actions (use dropdown-menu); picking one value in a form (use select or combobox); a long single-select that isn't action-oriented (use a searchable select pattern). It accelerates existing actions — it is not a replacement for visible navigation.

## Do / Don't
- ✅ Use CommandDialog with a `shortcut` for the global ⌘K palette (and `openOnSlash` for `/`); the bare Command for an inline palette.
- ✅ Always include a CommandEmpty for the no-results state, and give non-text items a `value` so cmdk can match them.
- ✅ Model async with `useCommandSearch` + `loading` + `shouldFilter={false}`, and render CommandLoading / CommandError / CommandEmpty off the flags.
- ✅ Float recents up with `useRecentCommands`: `record()` in onSelect and pass its `filter` to Command.
- ✅ Bind keys via CommandItem's `shortcut` (renders AND fires) — not a bare CommandShortcut.
- ✅ Declare per-row secondary actions with CommandItemActions + CommandAction, and pass the CommandAction children directly (not wrapped in a fragment / .map).
- ✅ Name CommandDialog via `title`/`description`, and add a CommandFooter of Kbd hints for discoverability.
- ✅ Drive the palette from an agent / toolbar via `apiRef` (CommandApi / CommandDialogApi).
- ❌ Don't hand-roll a second ⌘K listener — CommandDialog is the one host (AppShellCommand is a pass-through over it).
- ❌ Don't rely on CommandShortcut to bind the key — it's display-only; use CommandItem's `shortcut`, and always include a modifier.
- ❌ Don't leave cmdk filtering on for async results — pass `shouldFilter={false}` or the fetched matches get re-filtered.
- ❌ Don't ship a palette with no empty state, and don't show 'no results' while loading (CommandEmpty is guarded, but only if you render it inside CommandList).
- ❌ Don't wrap CommandAction children in a fragment or a .map()-array — the shortcut scan + panel render read them one level deep.

## Guidelines
**Reach for the canonical host.** Use `CommandDialog` with a `shortcut` (and maybe `openOnSlash`) for the global ⌘K palette; the bare `Command` is for an inline palette (a filter popover, a picker). Don't hand-roll a second ⌘K listener — that's exactly the duplication `CommandDialog` folds away.

**Model async through the flags, not by hand.** `useCommandSearch` owns the debounce, the loading/error/empty machine, and cancels stale requests; wire `query`/`setQuery` to `CommandInput`, `loading` to `Command`, and render `CommandLoading` / `CommandError` / `CommandEmpty` off the flags. Pass `shouldFilter={false}` when the server already returned the matches, so cmdk doesn't re-filter them.

**Rank with recents.** Call `record(value)` in an item's `onSelect` and pass `useRecentCommands().filter` to `<Command filter={…}>` to float recents up; render a 'Recent' `CommandGroup` from `recent`. The store is injectable (localStorage by default) so it can ride a consumer store.

**Bind shortcuts, don't just show them.** Put the combo on `CommandItem`'s `shortcut` (it renders the hint AND fires the item) rather than a bare `CommandShortcut` (display-only). Every combo needs a non-shift modifier.

**Keep it keyboard-driven and named.** Type-to-filter, arrow to move, Enter to run, Esc to close; → / ⌘. for a row's action panel; Backspace-on-empty to go back. It's a combobox over a listbox — preserve that. Name the CommandDialog for its context via `title`/`description`.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `apiRef` | `React.Ref<CommandApi>` | — | no | Imperative handle — drive the palette programmatically (agent-native). |
| `defaultSearch` | `string` | — | no |  |
| `loading` | `boolean` | — | no | In-flight async results. Auto-shows `CommandLoading`, hides `CommandEmpty` (so they can't both render — cmdk #269), and turns filtering off. |
| `onSearchChange` | `(value: string) => void` | — | no |  |
| `prefixes` | `CommandPrefixMap` | — | no | Leading-token → page routing (VS Code Quick Open): typing `>` at root jumps to a scope page and strips the token. Keyed by token, e.g. `{ ">": { page: "commands", label: "Commands" } }`. |
| `search` | `string` | — | no | Controlled search text. Uncontrolled by default via `defaultSearch`. |

_Plus 289 inherited native HTML attributes._

### `CommandDialog` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `"data-slot"` | `string` | — | no | `data-slot` for the content surface (AppShellCommand overrides it). |
| `apiRef` | `React.Ref<CommandDialogApi>` | — | no | Imperative handle — open/close plus the inner Command's content ops. |
| `className` | `string` | — | no | Class for the inner `Command`. |
| `contentClassName` | `string` | — | no | Class for the `DialogContent` surface. |
| `description` | `React.ReactNode` | — | no |  |
| `openOnSlash` | `boolean` | — | no | Also open on a bare `/` when focus isn't in a text field. |
| `shortcut` | `string` | — | no | Key for the ⌘/Ctrl open-shortcut; `null`/omitted disables. |
| `title` | `React.ReactNode` | — | no |  |

_Plus 296 inherited native HTML attributes._

### `CommandError` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `onRetry` | `() => void` | — | no | Renders a Retry button when provided. |

_Plus 280 inherited native HTML attributes._

### `CommandItem` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `shortcut` | `string` | — | no | A modifier-gated combo (`"mod+p"`, `"mod+shift+c"`) that both renders as a trailing shortcut hint AND fires this item's `onSelect` while the palette is focused. `mod` = ⌘ on mac, Ctrl elsewhere. |

_Plus 285 inherited native HTML attributes._

### `CommandItemActions` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `hint` | `React.ReactNode` | — | no | Inline affordance on the row. Defaults to a subtle `⌘.` hint; pass `null` to hide it. |

_Plus 280 inherited native HTML attributes._

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The highlighted item's value (Command root, from cmdk). Drives ArrowUp/Down navigation and aria-activedescendant.
- `search` (controlled) / `defaultSearch` (uncontrolled), `onSearchChange` · string — The query text. Controlled on Command (garn's context-backed field) or directly on CommandInput (`value`/`onValueChange`) for async search — an explicit CommandInput value wins as the source of truth, and the garn layer mirrors it: prefixes and `apiRef.getSearch` see the visible query, while page pushes and `apiRef.setSearch` write back through the input's `onValueChange` (so the consumer's state receives "" on a page push).
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — CommandDialog's open state (forwards the Dialog's). The ⌘K/`/` shortcut and apiRef.open()/close()/toggle() drive it.
- Selection: single.

## Anatomy
- `command-dialog`: The `DialogContent` surface a CommandDialog renders the palette into (`data-slot=command-dialog`; AppShellCommand overrides it with its own). Scrim + focus trap + Esc come from Dialog.
- `command-input-wrapper`: The row wrapping the search input and its leading affordance (search icon, or the back-pill on a nested page). Grows the bottom divider only when the list is `data-expanded`, so an input-only palette sits flat.
- `command-back`: The back / breadcrumb pill shown inside the input on a nested sub-command page — a real `button` named 'Go back — {label}'. Clicking it (or Backspace on an empty input) pops the page and restores focus to the input.
- `command-action-panel`: The `PopoverContent` (anchored bottom-right) holding the highlighted row's secondary actions — a nested Command + focus scope, mounted ONLY while open, so Esc closes just the panel (not the outer dialog) and focus returns to the input.

**Parts**
- `Command` (`command`) · required: Root — the filterable container (cmdk engine) plus the garn layer: a nested-page stack, controlled `search`, a `loading` flag (guards the loading↔empty race), per-item shortcut + item registries, the per-row action-panel state, and the imperative `apiRef`. Reflects `data-loading` / `data-expanded` / `data-actions-open`. Works inline or inside CommandDialog.
- `CommandDialog` (`command-dialog`): The canonical ⌘K palette host — drops a Command into a Dialog, owns controllable open state, binds the ⌘/Ctrl (+ optional `/`) open-shortcut via `useCommandShortcut`, and exposes a `CommandDialogApi`. Names the dialog for assistive tech via sr-only `title`/`description` (default "Command menu"). `AppShellCommand` is a thin pass-through over it.
- `CommandInput` (`command-input`) · required: The search box (role=combobox); its text filters the list. Context-backed by default (so pages can reset it and Backspace-on-empty pops), overridable with an explicit `value` for async search; on a nested page it swaps the leading search icon for the back-pill.
- `CommandList` (`command-list`) · required: The scrollable results region (role=listbox). Hides the native scrollbar for a scroll-aware edge-fade mask (`data-overflow-start/-end`), measures visible content to drive the root's `data-expanded`, and slides on page push/pop (reduced-motion aware).
- `CommandEmpty` (`command-empty`): The no-match state. Suppressed while the root is `loading` so 'no results' never renders during a fetch (guards cmdk #269) — distinguish 'no query yet' (show recents) from 'query, no match'.
- `CommandLoading` (`command-loading`): Async in-flight slot — a Spinner + label inside cmdk's Loading region. Auto-managed: renders only while the root is `loading` (still renders standalone, outside a Command).
- `CommandError` (`command-error`): Async-failure slot (not a cmdk concept) — `role=alert` (announced assertively), with an optional Retry `Button` via `onRetry`. Render it when your fetch rejects.
- `CommandGroup` (`command-group`): A labeled group of items (`heading`) — the seam for semantic sections (Recent · Suggestions · Actions · Navigation).
- `CommandItem` (`command-item`) · required: A selectable command (role=option), matched by its text/`value`. A `shortcut` renders a trailing hint AND fires the item's `onSelect` while the palette is focused (modifier-gated). Register a `value` so `apiRef.run(value)` can fire it.
- `CommandItemActions` (`command-item-actions`): Declares a row's secondary actions — place inside a `CommandItem` that has a `value`. Its `CommandAction` children render in the shared action panel that opens on → / ⌘.; it marks the row `aria-haspopup`, and renders only a small inline hint itself (`aria-hidden`). Pass CommandAction children directly (not wrapped in a fragment / .map).
- `CommandAction` (`command-action`): One secondary action — a `CommandItem` rendered inside the action panel (accepts a per-action `shortcut`); running it also closes the panel.
- `CommandShortcut` (`command-shortcut`): Right-aligned shortcut hint. Display-only on its own — CommandItem's `shortcut` prop is what actually binds the key.
- `CommandFooter` (`command-footer`): A footer hint bar below the list for keyboard discoverability — compose `Kbd` inside (e.g. '↵ select · → actions · esc close').
- `CommandSeparator` (`command-separator`): Divider between groups.

## Accessibility
- **Role:** combobox (APG: combobox)
- **A–Z:** Type in the input to filter the list.
- **ArrowUp / ArrowDown:** Move between matching items.
- **Enter:** Run the highlighted item (its onSelect).
- **Escape:** Close the palette (CommandDialog) — or, when a row's action panel is open, close just the panel.
- **Backspace:** On an empty input, pop the current sub-command page (or exit a prefix scope).
- **ArrowRight:** When the caret is at the end of the query, open the highlighted row's action panel (if it has actions).
- **Mod / .:** Open the highlighted row's action panel.
- **Mod / K:** Open / toggle the palette (CommandDialog with a `shortcut`).
- **/:** Open the palette when focus isn't in a text field (CommandDialog `openOnSlash`).
- **Mod / …:** Fire a highlighted item's bound `shortcut` (e.g. ⌘P) without leaving the input.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.3 Focus Order (A); 4.1.2 Name, Role, Value (A)
- CommandInput is role=combobox controlling the role=listbox CommandList; items are role=option with aria-selected. Filtering is by item text/`value` — give non-text items a `value` so they're searchable.
- CommandDialog carries an sr-only DialogTitle/DialogDescription (default 'Command menu') so Radix always has an accessible name; focus is trapped and returns to the opener on close.
- On a nested page the input grows a back-pill — a real button named 'Go back — {label}'; popping it (button or Backspace-on-empty) restores focus to the input, and page navigation is announced via a polite live region.
- A row with secondary actions (CommandItemActions) gets aria-haspopup + aria-keyshortcuts; → / ⌘. opens a focus-scoped Popover panel whose Esc closes ONLY the panel (not the outer dialog) and returns focus to the input.
- Filtered result counts are announced politely ('N results' / 'No results'); the async-failure slot (CommandError) is role=alert (assertive). CommandEmpty is suppressed while `loading`.
- Page-push motion, the edge-fade, and hover affordances are decorative — the fade is offset by a per-row scroll-margin so keyboard navigation never parks a row under it, and motion is gated by prefers-reduced-motion.
- **Focus:** Focus stays in the input; ArrowUp/Down move the active option (aria-activedescendant). The back-pill and the per-row action panel both restore focus to the input on close/pop, so the tab stop never falls to <body>. Don't strip the focus ring.
- **Contract (error):** CommandDialog names the dialog via an sr-only title/description (default 'Command menu'); override `title`/`description` for context, or pass `null` and supply your own DialogTitle. — _when always (CommandDialog)_
- **Contract (warn):** The combo renders as a trailing hint AND fires the item's onSelect while the palette is focused; it must carry a non-shift modifier (mod / ctrl / alt) so it never collides with type-ahead. — _when a CommandItem sets `shortcut`_
- **Contract (error):** The back affordance is a button with an accessible name ('Go back — {label}'); popping it (or Backspace on an empty input) returns focus to the input and announces the navigation politely. — _when a sub-command page is pushed_
- **Contract (error):** The row exposes aria-haspopup; → / ⌘. opens a focus-scoped panel whose Esc closes only the panel and restores focus to the input (never the outer dialog). — _when a row renders CommandItemActions_
- **Contract (warn):** Result counts and page navigation announce via a polite live region and CommandError is role=alert; CommandEmpty is suppressed while `loading` so 'no results' never renders during a fetch. — _when results filter or async state changes_

## Tokens
- `inputHeight` → `--garn-control-h-lg` (air)
- `itemMinHeight` → `--garn-control-h-md` (air)
- `scrollFade` → `--garn-space-48`
- `pageMotionEasing` → `--garn-ease-standard`

## Related
- **composes** → `utils`
- **composes** → `dialog` (when CommandDialog renders the palette in a modal (scrim, focus trap, Esc, sr-only title))
- **composes** → `popover` (when the per-row action panel is a Popover anchored bottom-right (a nested focus scope))
- **composes** → `spinner` (when CommandLoading shows the async in-flight indicator)
- **composes** → `button` (when CommandError renders an optional Retry button)
- **composes** → `use-controllable-state` (when CommandDialog `open` and Command `search` are controlled-or-uncontrolled)
- **composes** → `use-announce` (when result counts, page navigation, and the action panel announce to a polite live region)
- **composes** → `use-local-storage` (when useRecentCommands persists recency/frequency by default (injectable))
- **composes** → `use-debounced-value` (when useCommandSearch debounces the query before fetching)
- **composes** → `use-prefers-reduced-motion` (when the page-push slide is skipped under reduced motion)
- **pairsWith** → `kbd` (when showing the ⌘K hint, per-item shortcuts, or the CommandFooter hints)
- **pairsWith** → `app-shell` (when AppShellCommand is a thin pass-through over CommandDialog for the shell ⌘K)
- **alternativeTo** → `dropdown-menu` (when the actions are a small fixed set that needs no search)
- **alternativeTo** → `select` (when the user is picking one value in a form)
- **alternativeTo** → `combobox` (when you need a single-field autocomplete bound to a form value, not an action palette)

## Recipes
- **command-palette** — A global ⌘K command palette in a modal — recents float up (useRecentCommands biases the filter), actions group into sections, per-item shortcuts fire, and a footer shows the key hints. _(use when an app needs fast keyboard access to many actions / destinations)_
- **sub-command-pages** — A palette that drills into nested sub-commands — selecting a '…' item pushes a page (the input grows a back-pill, Backspace-on-empty pops); a leading-token `prefix` can jump straight into a scope. _(use when a deep palette needs push/pop navigation or mode routing (pick a thing → pick an action))_
- **async-command-search** — Search-as-you-type against an async source — useCommandSearch debounces, cancels stale requests, and drives the loading / error / empty machine; shouldFilter is off because the source already returned the matches. _(use when the palette results come from a server / async source, not a static list)_
- **command-action-panel** — Per-row secondary actions — each item declares CommandItemActions; → / ⌘. opens a focus-scoped Popover panel of that row's actions (each with its own shortcut), and a bound shortcut fires the highlighted row's action from the main list. _(use when a palette row needs more than one action (open · edit · duplicate · delete))_
- **faceted-filter** — A faceted multi-select filter — a dashed Button trigger opens a Popover of searchable, checkable options; the trigger shows the chosen values as Badges, or past a few, a Counter (the 'Status ⌄ 3 selected' pattern). A Clear item resets. Selection state is the consumer's (a Set of values, usually driving a table query). _(use when filtering a data table or list by one column's values — multi-select with search)_

## Gotchas
- **Async results get double-filtered — the server returned matches but the list still hides some as you type.** — cmdk client-filters by the input text by default; on top of a server that already filtered, matches get dropped. → Pass `shouldFilter={false}` to Command for async search (useCommandSearch's recipe). `loading` also turns filtering off automatically while a fetch is in flight.
- **CommandLoading / CommandError never show, or 'No results' flashes during a fetch.** — The async state isn't wired to the flags — CommandLoading renders only when the root is `loading`, and CommandEmpty is suppressed while `loading` (guarding cmdk #269), so both depend on the `loading` prop. → Set `loading` on Command (or use useCommandSearch's `loading`), and render CommandLoading / CommandError / CommandEmpty inside CommandList off the flags.
- **A CommandItem's shortcut hint shows but pressing the key does nothing.** — A bare `CommandShortcut` is display-only, or the combo has no non-shift modifier (unmodified keys would collide with type-ahead, so they're not bound). → Put the combo on CommandItem's `shortcut` (it renders AND fires), and always include a modifier (`mod+p`, `mod+shift+i`). `mod` = ⌘ on mac, Ctrl elsewhere.
- **The per-row action panel doesn't open, or a row's actions are missing.** — CommandItemActions must sit inside a CommandItem that has a `value` (the panel is keyed by value), and its CommandAction children are read one level deep — a fragment or a .map()-array hides them. → Give the row a `value` and pass the CommandAction children directly to CommandItemActions (flatten with Children.toArray if you must map). → / ⌘. then opens the panel.
- **Two ⌘K listeners fight, or the shortcut opens the wrong palette.** — CommandDialog's `shortcut` defaults OFF (opt-in) precisely so an existing dialog with its own listener doesn't double-bind; adding a second host re-introduces the duplication CommandDialog folds away. → Use one CommandDialog with `shortcut="k"` as the host (AppShellCommand is a pass-through over it). Don't add a bespoke global keydown too.
- **The command palette needs a more specific accessible name than the default 'Command menu'.** — CommandDialog ships an sr-only DialogTitle/DialogDescription so Radix's required name is always satisfied, but the defaults are generic. → Pass `title` (and optionally `description`) to name the palette for its context — both render sr-only; pass `null` to supply your own DialogTitle.
- **apiRef.setSearch / navigate / run seem to do nothing.** — The inner Command is unmounted while a CommandDialog is closed, so its content ops no-op until it's open (open/close/toggle always work). → Open the dialog first (apiRef.open()), then drive content; for an always-mounted inline Command the CommandApi ops work immediately.

## Examples
- **basic** (canonical): Inline command list with grouped, filterable items and display-only shortcut hints.
- **palette** (canonical): The canonical ⌘K palette: a modal CommandDialog that binds its own open shortcut, floats recents up (useRecentCommands), groups sections, binds per-item shortcuts that fire, and shows a Kbd footer.
- **nested-pages** (canonical): Sub-command navigation — selecting a '…' item pushes a page (back-pill + Backspace-to-pop); useCommandPages reads the stack and the apiRef drives it (navigate / back / reset).
- **prefix** (canonical): Prefix / mode routing — typing `>` jumps to commands, `@` to people; the token is stripped and Backspace returns to the tip. Driven by the `prefixes` prop over the page stack.
- **async-search** (canonical): Search-as-you-type against an async source via useCommandSearch (debounce + cancel); CommandLoading while fetching, CommandError with Retry on failure (type 'error'), shouldFilter off.
- **loading-state** (edge-case): A static snapshot of the loading state — CommandLoading shows and CommandEmpty is suppressed (the loading↔empty guard).
- **error-state** (edge-case): A static snapshot of the async-failure state — CommandError (role=alert) with a Retry button.
- **empty-state** (edge-case): A static snapshot of the no-match state — a query that matches nothing renders 'No results for ‘…’'.
- **actions** (canonical): Per-item action panel — each row declares CommandItemActions; ↵ runs the primary, → / ⌘. opens the row's actions (each with a shortcut), Esc closes just the panel.
- **faceted-filter** (edge-case): A faceted multi-select filter recipe — Button + Popover + Command + Counter + Badge ('Status ⌄ 3 selected').

## Source map

Regions in `command.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L3–33 (31 lines) — React, cmdk, icons, shared hooks
- `context` L34–110 (77 lines) — garn layer over cmdk: page/shortcut types + contexts
- `api-types` L111–137 (27 lines) — imperative-handle contracts (CommandApi / CommandDialogApi)
- `shortcut-utils` L138–229 (92 lines) — parse / match / format shortcuts + mac detection
- `root` L230–494 (265 lines) — Command provider (page stack, shortcut registry, apiRef) + announcer
  - `command-wiring` L290–424 (135 lines) — registrations, imperative handle, page/shortcut effects
- `dialog` L495–606 (112 lines) — CommandDialog host (⌘K palette, open-state, inner apiRef)
- `input` L607–731 (125 lines) — CommandInput (search box + nested-page back affordance)
- `list` L732–832 (101 lines) — CommandList (scroll container, edge-fade, expand probe)
- `empty` L833–850 (18 lines) — CommandEmpty (loading↔empty race guard)
- `loading` L851–876 (26 lines) — CommandLoading (auto-managed spinner row)
- `error` L877–912 (36 lines) — CommandError (async-failure alert + retry)
- `group` L913–930 (18 lines) — CommandGroup (heading + items wrapper)
- `separator` L931–945 (15 lines) — CommandSeparator (hairline divider)
- `item` L946–1034 (89 lines) — CommandItem (shortcut binding, value registration) + CommandShortcut
- `footer` L1035–1051 (17 lines) — CommandFooter (keyboard-hint bar)
- `item-actions` L1052–1137 (86 lines) — CommandItemActions (declare row's secondary actions + shortcuts)
- `action` L1138–1147 (10 lines) — CommandAction (a single secondary action row)
- `action-panel` L1148–1231 (84 lines) — CommandActionPanel (shared Popover of the open row's actions)
- `use-command-shortcut` L1232–1279 (48 lines) — global ⌘K / slash open-binding hook
- `use-command-pages` L1280–1296 (17 lines) — read/drive the nested-page stack
- `use-recent-commands` L1297–1379 (83 lines) — recency+frequency ranking (types + hook)
- `use-command-search` L1380–1448 (69 lines) — debounced async fetch state machine
- `exports` L1449–1483 (35 lines) — public component + hook + type surface

---

# Context Menu

> A menu of actions opened by right-click or long-press on a target.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { ContextMenu } from "@garn/ui/context-menu"`
- **Polymorphism:** `asChild`

## Overview
ContextMenu offers actions contextual to an element via right-click / long-press — canvas objects, file or list rows, rich editors. `ContextMenuTrigger` wraps the target area, `ContextMenuContent` opens at the pointer, and it carries the same item vocabulary as DropdownMenu (items, checkbox/radio items, labels, separators, submenus). It's discovered by gesture, so it complements a visible affordance — for a button-triggered menu use DropdownMenu.

## When to use
Offer actions contextual to an element via right-click / long-press — canvas objects, file/list rows, rich editors.

## When not to use
The primary or only access to actions (right-click isn't discoverable — also expose them via a button + dropdown-menu); a button-triggered menu (use dropdown-menu); selecting a form value (use select).

## Do / Don't
- ✅ Mirror the same actions on a visible control — right-click alone isn't discoverable or fully accessible.
- ✅ Group and separate destructive items; control checkbox/radio item state.
- ✅ Give the trigger area real, meaningful content.
- ❌ Don't make right-click the only way to reach an action.
- ❌ Don't use it where users expect a button-triggered menu (dropdown-menu).
- ❌ Don't nest deep submenu trees.

## Guidelines
**Never make a context menu the only way to do something.** Right-click/long-press is hard to discover and unavailable to many users — always provide a visible path (a kebab DropdownMenu, inline buttons) to the same actions. Use it to *speed up* expert workflows.

**Scope items to the target and keep the list short.** The menu should act on the element you opened it over; show only relevant actions, group them with separators, and keep destructive items distinct. Deep submenus get unwieldy — go one level where possible.

**Support touch and keyboard.** Long-press opens it on touch and it's fully arrow-key navigable once open; don't trap focus or rely on hover. Selecting an item closes the menu, so use checkbox/radio items for things that should persist it.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Whether the menu is open (opened by right-click / long-press). CheckboxItem (`checked`) and RadioGroup (`value`) hold their own item-level state.
- Selection: single.

## Anatomy

**Parts**
- `ContextMenu` · required: Root — owns the open state. No DOM of its own.
- `ContextMenuTrigger` (`context-menu-trigger`) · required: The target area; right-click / long-press inside it opens the menu.
- `ContextMenuContent` (`context-menu-content`) · required: The portaled menu surface (positioned at the pointer).
- `ContextMenuItem` (`context-menu-item`): An action item; `inset` aligns it with checkbox/radio items.
- `ContextMenuCheckboxItem` (`context-menu-checkbox-item`): A toggleable item (controlled via `checked` + `onCheckedChange`).
- `ContextMenuRadioGroup`: Groups radio items; owns the selected `value`.
- `ContextMenuRadioItem` (`context-menu-radio-item`): A single-select item inside a RadioGroup.
- `ContextMenuLabel` (`context-menu-label`): A non-interactive section heading; `inset` for alignment.
- `ContextMenuSeparator` (`context-menu-separator`): Divider between groups.
- `ContextMenuShortcut` (`context-menu-shortcut`): Right-aligned shortcut hint (display only).
- `ContextMenuSub`: A submenu container (Sub / SubTrigger / SubContent).
- `ContextMenuSubTrigger` (`context-menu-sub-trigger`): Opens a submenu; `inset` for alignment.
- `ContextMenuSubContent` (`context-menu-sub-content`): The nested submenu surface.

## Accessibility
- **Role:** menu (APG: menu)
- **Shift+F10 / ContextMenu:** Open the menu from the focused trigger (keyboard).
- **ArrowUp / ArrowDown:** Move between items.
- **ArrowRight / ArrowLeft:** Open / close a submenu.
- **Enter / Space:** Activate the highlighted item.
- **Escape:** Close the menu.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- Content is role=menu with roving focus; items are menuitem / menuitemcheckbox / menuitemradio.
- Right-click / long-press is the primary opener — also expose the actions from a visible control for discoverability and accessibility.
- **Focus:** Roving focus across items; focus returns to the trigger area on close.

## Tokens
- `itemMinHeight` → `--garn-control-h-md` (air)

## Related
- **composes** → `utils`
- **pairsWith** → `dropdown-menu` (when mirroring the same actions on a visible button for discoverability)
- **slotAccepts** → `kbd` (when rendering a shortcut hint in ContextMenuShortcut)
- **alternativeTo** → `dropdown-menu` (when the menu should open from a visible button instead of right-click)

## Gotchas
- **Keyboard or touch users can't reach the actions.** — Right-click is the only opener. → Also expose the same actions via a visible control (e.g. a dropdown-menu); Radix supports Shift+F10/ContextMenu key on the focused trigger.
- **A checkbox item closes the menu when toggled, or its state resets.** — Items close the menu on select by default, and item state must be lifted. → Call `e.preventDefault()` in onSelect to keep it open; control `checked`/`onCheckedChange` (or RadioGroup `value`).

## Examples
- **basic** (canonical): A right-click target with browser-style actions.

---

# Counter

> A compact numeric count pill — notification totals and unread counts, with a 99+ overflow cap and an animated digit roll.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Counter } from "@garn/ui/counter"`

## Overview
Counter shows a numeric total beside an owner — an unread count on a bell icon or nav item, a tally on a tab or list. It handles the niceties: a 99+ overflow cap, digit-roll animation, and a true-count announcement for assistive tech. `Counter.Indicator` anchors a count (or a bare presence dot) onto the corner of a child like an icon button or avatar. For a labelled status use Badge; for determinate progress use Progress.

## When to use
Show a numeric total beside an owner — a notification/unread count on an icon button or nav item, a tally on a tab or list. Use Counter.Indicator to anchor a count or a presence dot onto the corner of a child (a bell icon, an avatar).

## When not to use
A short text label or status (use Badge); a removable or selectable chip (use Tag); a single pick-to-change value (use BadgeSelect); determinate task progress (use Progress).

## Do / Don't
- ✅ Label the owner so the number has context ('Inbox' + Counter → 'Inbox, 4').
- ✅ Use tone for intent — danger for alerts/notifications, brand for on-brand totals, neutral for generic counts.
- ✅ Let it hide at zero (the default); reach for showZero only when a 0 is meaningful.
- ✅ For overlays, wrap the target in Counter.Indicator; use overlap='circular' on round targets (avatars) and a dot for presence without a number.
- ❌ Don't put non-numeric text in a Counter — that's Badge.
- ❌ Don't rely on the capped '99+' for screen readers — it already announces the real count, but keep the owner labelled.
- ❌ Don't set live={false} on a count users need to hear change (e.g. a cart total).

## Guidelines
**Use a counter for a live tally, not a static label.** It's for counts that change (notifications, items in a cart); a fixed category label is a Badge. Cap large numbers (99+) so the chip stays small and stable.

**Announce the real count, hide zero.** Let the true number reach screen readers even when the visual is capped, and don't render a "0" badge — absence is the clearer signal that there's nothing new.

**Anchor it without obscuring its owner.** When pinning a count to an icon or avatar via `Indicator`, keep the icon's own accessible name intact and make sure the badge doesn't cover the part that identifies it. A bare dot is enough when the exact number doesn't matter.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"soft" \| "solid"` | `solid` | no |  |
| `shape` | `"pill" \| "rounded" \| "sharp"` | `pill` | no |  |
| `size` | `"md" \| "sm"` | `md` | no |  |
| `tone` | `"brand" \| "danger" \| "discovery" \| "info" \| "neutral" \| "success" \| "warning"` | `neutral` | no |  |
| `format` | `"compact" \| "standard"` | — | no | `"compact"` abbreviates large counts (`1.2K`) via Intl; `max` no longer applies. |
| `live` | `boolean` | — | no | Announce changes to assistive tech via an aria-live region. Default true. |
| `locale` | `string` | — | no | BCP-47 locale for number formatting (pass it for SSR determinism). |
| `max` | `number` | — | no | Cap; counts above render `${max}+` (e.g. `99+`). Default 99. |
| `pulse` | `boolean` | — | no | Add a reduced-motion-safe "new activity" halo. |
| `showZero` | `boolean` | — | no | Render a `0` instead of hiding the counter. Default false. |
| `value` | `number` | — | yes | The count to display. `0` renders nothing unless `showZero`. |

_Plus 279 inherited native `<span>` attributes._

### `Counter.Indicator` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"soft" \| "solid"` | — | no | Count-marker appearance: solid (default) or soft. |
| `children` | `React.ReactNode` | — | yes | The target the marker is anchored onto. |
| `count` | `number` | — | no | Show a count marker (a composed Counter). Hidden at 0 unless `showZero`. |
| `dot` | `boolean` | — | no | Show a bare presence dot instead of a number. |
| `format` | `"compact" \| "standard"` | — | no | Forwarded to the count marker. |
| `invisible` | `boolean` | — | no | Hide the marker while keeping the child in place. |
| `live` | `boolean` | — | no | Announce count changes via the count marker's live region. Default true. |
| `locale` | `string` | — | no | Forwarded to the count marker (SSR-deterministic formatting). |
| `max` | `number` | — | no | Forwarded to the count marker. Default 99. |
| `offset` | `number` | — | no | Nudge the marker inward by N px (fine-tuning against the target's radius). |
| `overlap` | `"circular" \| "rectangular"` | — | no | Inset the marker inward for a round target (avatar). Default `rectangular`. |
| `position` | `IndicatorPosition` | — | no | Corner to anchor the marker on. Default `top-end` (logical / RTL-safe). |
| `pulse` | `boolean` | — | no | A reduced-motion-safe "new activity" halo on the marker. |
| `shape` | `"pill" \| "rounded" \| "sharp"` | — | no | Count-marker shape: pill (default), rounded, or sharp. |
| `showZero` | `boolean` | — | no | Render a `0` count instead of hiding the marker. |
| `size` | `"md" \| "sm"` | — | no | Marker size (shared with Counter). |
| `tone` | `CounterTone` | — | no | Tone of the marker (shared with Counter). |
| `withBorder` | `boolean` | — | no | A ring in the surface color so the marker separates from the target. Default true. |

_Plus 278 inherited native HTML attributes._

## Variants
- **tone** (default `neutral`): `neutral`, `brand`, `info`, `success`, `warning`, `danger`, `discovery`
- **appearance** (default `solid`): `solid`, `soft`
- **size** (default `md`): `sm`, `md`
- **shape** (default `pill`): `sharp`, `rounded`, `pill`

## Anatomy
- `counter`: The count pill (a <span>); the aria-live region.
- `counter-value`: The visual, possibly-capped/abbreviated number — aria-hidden (the true count is announced separately).
- `counter-digit`: One rolling 0-9 digit column (the odometer).
- `counter-label`: sr-only true count — the accessible name and the live-announced text.

**Parts**
- `Counter.Indicator` (`counter-indicator`): A wrapper that anchors a marker (a bare dot, or a composed Counter) onto a child target — the notification-bubble / presence-dot role. Logical, RTL-safe positioning; hides at zero.

## Accessibility
- **Role:** status
- **WCAG:** 1.4.1 Use of Color (A); 1.4.3 Contrast (Minimum) (AA); 2.3.3 Animation from Interactions (AAA); 4.1.3 Status Messages (AA)
- The visual number is aria-hidden; the true (uncapped, ungrouped-source) count lives in an sr-only label, so '99+' or '1.2K' never hides the real value from assistive tech.
- The root is an aria-live=polite, aria-atomic region (the `live` prop, on by default) — count changes are announced without moving focus. Live regions stay silent on mount, so a static counter never speaks.
- Counter contributes only the number; label its owner for context (an 'Inbox' button + a Counter reads 'Inbox, 4'). Override the name with aria-label when the number alone isn't enough.
- The digit roll and the pulse halo both honor prefers-reduced-motion (instant swap / hidden halo).
- Counter.Indicator (the overlay) treats a marker as a visual cue tied to its target: the count marker carries Counter's own aria-live announce, while the bare dot is decorative (aria-hidden) and the target conveys meaning in its label (e.g. an avatar labelled 'Maya, online'). Label the target with its purpose only ('Notifications') for a count — the marker announces the number — and don't duplicate the count in both.

## Tokens
- `fill` → `--garn-badge-danger-bold` · brandable
- **Internal (never externalize):** `--counter-ping`

## Related
- **composes** → `utils`
- **pairsWith** → `badge` (when Badge's `count` sugar renders a Counter in its trailing slot)
- **pairsWith** → `button` (when Counter.Indicator anchors a count onto an icon button (a notification bell))
- **pairsWith** → `avatar` (when Counter.Indicator anchors a presence dot onto an avatar)
- **alternativeTo** → `badge` (when the value is a text label or status, not a number)
- **alternativeTo** → `progress` (when the value is determinate task progress, not a count)

## Gotchas
- **A Counter with value={0} renders nothing.** — Counter hides at zero by default to avoid a noisy 0 bubble. → Pass showZero when a 0 is meaningful.
- **Screen reader hears '99+' or '1.2K' instead of the real number.** — It does not — the visual is aria-hidden and the true count is in an sr-only live region. This is the intended split. → Nothing to fix; label the owner for context, or set aria-label to customize the announced name.
- **Editing dark-mode counter colors in the component has no effect.** — Tones resolve through the --garn-badge-* component tokens; the dark values live in the token layer. → Adjust dark mode in the garn theme CSS (.dark block) — never with raw ramps in counter.tsx.
- **A Counter.Indicator dot/count sits in the wrong place or off the corner of a round avatar.** — Default position is top-end (rectangular); a round target needs the marker pulled inward. → Set overlap='circular' for avatars, pick a position ('bottom-end' for presence), and fine-tune with offset.
- **A screen reader announces the notification count twice.** — The count was put in the target's aria-label AND the count marker announces it via its own live region. → Label the target with its purpose only ('Notifications') for a count marker; reserve count-in-the-label for the bare dot case.

## Examples
- **basic** (canonical): A danger-tone notification count.
- **tones** (edge-case): The full palette — neutral · brand · info · success · warning · danger · discovery.
- **appearances** (edge-case): solid (filled) vs soft (light tinted fill, darker text).
- **shapes** (edge-case): sharp · rounded · pill, shown with solid colors.
- **sizes** (edge-case): sm · md.
- **overflow** (edge-case): The 99+ cap and compact (1.2K) abbreviation.
- **pulse** (edge-case): A reduced-motion-safe activity halo.
- **owner** (edge-case): Labelled by its owner — the button reads 'Inbox, 4'.
- **live** (edge-case): Increment/decrement to watch the digit roll (instant under reduced motion).
- **indicator** (edge-case): Counter.Indicator — a count anchored onto a notification bell.
- **indicator-dot** (edge-case): Counter.Indicator — a presence dot on an avatar (overlap='circular').
- **indicator-positions** (edge-case): Counter.Indicator — the corner positions.

---

# DataList

> The read-only 'field: value' detail block — a real description list (<dl>/<dt>/<dd>) for demographics, order summaries, settings recaps, and entity metadata. Three responsive orientations, a token-driven label column, dividers, graceful empty values, truncation, and an opt-in copy affordance.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { DataList } from "@garn/ui/data-list"`
- **Polymorphism:** `asChild` (default element `<dl>`)

## Overview
DataList presents a read-only set of term→value pairs about one entity — demographics, an order summary, a settings recap, a metadata sidebar. It renders real `<dl>`/`<dt>`/`<dd>` (`DataList.Item` / `Term` / `Value`), with empty values showing a placeholder + sr-only "Not set" and opt-in `truncate`/`copyable`. Use `row` for a classic detail block, `grid` when values must align across rows, `stacked` for narrow asides. For tabular records across *many* entities, use a Table.

## When to use
A read-only set of 'field: value' pairs about one entity — demographics, an order/receipt summary, settings recap, a details tab, or a metadata sidebar. Use `row` for the classic detail block, `grid` when values must align across rows, `stacked` for narrow asides.

## When not to use
Tabular data with multiple rows × columns (use Table); editable fields (use Form + inputs); a single big metric (use Stat); a chronology of events (use Timeline); inline tokens/labels (use Badge / Tag).

## Do / Don't
- ✅ Use the real parts (DataList.Item / .Term / .Value) so the <dl>/<dt>/<dd> semantics hold.
- ✅ Pick `grid` (or set `labelWidth`) when you want every value's left edge to line up.
- ✅ Drop rich nodes (Tag, Badge, Avatar, a link) straight into DataList.Value — it composes with the badge family.
- ✅ Let an empty value render the placeholder (don't hide the row) so the field still reads as 'not set'.
- ✅ Use `copyable` for IDs / keys / emails the user will copy; `truncate` for long single-line values.
- ❌ Don't fake a description list with styled <div>s — you lose the announced term↔value relationship.
- ❌ Don't use DataList for rows×columns of records — that's Table.
- ❌ Don't hand-place a copy button; let `copyable` render and wire the announced one.
- ❌ Don't hardcode the label column width in px utilities — use `labelWidth` (token-backed) which feeds the var.

## Guidelines
**Use it for one entity's facts, not a data grid.** DataList describes a single thing (a user, an order); comparing many rows of records is a Table's job. Keep terms short and consistent, and order them by importance.

**Show empty values honestly.** Render a clear "not set" placeholder rather than collapsing the row, so the absence is itself information; the component announces it to screen readers. Make long values `truncate` with a tooltip rather than breaking the layout.

**Pick the layout for the content.** `grid` when value alignment aids scanning, `row` for prose-y detail, `stacked` for narrow columns. Use `copyable` on the values people actually copy (IDs, emails) and keep the markup semantic so AT reads it as a definition list.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `orientation` | `"grid" \| "row" \| "stacked"` | `row` | no |  |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |
| `align` | `"baseline" \| "center" \| "start"` | — | no | Cross-axis alignment of term↔value (`row`/`grid`). Default `baseline` so a Tag/Badge value optically sits on the term's text baseline. |
| `density` | `"compact" \| "spacious"` | — | no | Local density override; omit to inherit the ambient `[data-density]`. |
| `divider` | `boolean` | — | no | Hairline rule between items (never above the first / below the last). |
| `labelWidth` | `number \| string` | — | no | Width of the term ("label") column in `row`/`grid`. Pass a token-backed length (e.g. a CSS var or a Tailwind width via className) or a number of px; omit for the natural `max-content` width. Sets `--data-list-label-w`. |
| `placeholder` | `React.ReactNode` | — | no | Rendered for an empty value. Default an em-dash; `aria-hidden` with an sr-only "Not set" so the absence is meaningful to assistive tech. |
| `truncate` | `boolean` | — | no | Ambient truncation for every value (a value can still override). |

_Plus 280 inherited native `<dl>` attributes._

### `DataList.Item` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `align` | `"baseline" \| "center" \| "start"` | — | no | Override the root's cross-axis alignment for this row. |

_Plus 280 inherited native HTML attributes._

### `DataList.Term` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no | Render as the child element (e.g. a heading or link), merging props. |

_Plus 280 inherited native HTML attributes._

### `DataList.Value` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no | Render as the child element (e.g. a link), merging props. |
| `copyable` | `boolean` | — | no | Show an inline copy affordance (a ghost Button) on hover / focus-within. |
| `copyText` | `string` | — | no | Text to copy when `copyable`; defaults to the value's rendered text. |
| `placeholder` | `React.ReactNode` | — | no | Override the root's empty placeholder for this value. |
| `truncate` | `boolean` | — | no | Truncate a long value to one line with an ellipsis + native title tooltip. Overrides the root's ambient `truncate`. |

_Plus 280 inherited native HTML attributes._

### `DataList.CopyButton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` | — | no |  |
| `label` | `string` | — | no | Accessible label. Default "Copy value". |
| `value` | `string` | — | yes | The text written to the clipboard. |

## Variants
- **orientation** (default `row`): `stacked`, `row`, `grid`
- **size** (default `md`): `sm`, `md`, `lg`

## Anatomy
- `data-list`: The list — a real <dl> carrying the orientation/size/align/divider data-attrs and the --data-list-label-w var.

**Parts**
- `DataList.Item` (`data-list-item`) · required: One term/value pair — a <div> inside the <dl> (valid HTML, the layout host). In `grid` it spans both columns via subgrid so every value edge aligns; carries the optional divider.
- `DataList.Term` (`data-list-term`) · required: The term (`<dt>`) — the field name. Muted; holds the label column (floored, not fixed, so a long term grows past the floor). asChild to become a heading/link.
- `DataList.Value` (`data-list-value`) · required: The value (`<dd>`) — any node. Empty → tokenized placeholder + sr-only 'Not set'. Opt-in `truncate` (title tooltip) and `copyable`. asChild to become a link.
- `DataList.CopyButton` (`data-list-copy`): The inline copy affordance — a ghost Button that writes to the clipboard, flips to a check for a beat, and announces 'Copied' via a polite live region. Auto-rendered by `copyable`.

## Accessibility
- **Role:** term
- **WCAG:** 1.3.1 Info and Relationships (A); 1.4.3 Contrast (Minimum) (AA); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- Real <dl> / <dt> / <dd> semantics so the term↔value association is announced, not just visually implied — never fake it with styled <div>s.
- A DataList.Item is a <div> wrapper (valid since HTML5.2); in `grid` it adopts the parent columns via subgrid so alignment never needs per-cell borders.
- An empty value renders a tokenized, aria-hidden placeholder PLUS an sr-only 'Not set', so the absence is meaningful to assistive tech and the column still holds.
- The copy affordance is a real focusable <button> (reachable by keyboard, visible on touch) that announces 'Copied' via a role=status polite live region.
- Use asChild on Term/Value to host a heading or link without breaking the <dt>/<dd> semantics.
- **Focus:** Only the copy button and any asChild link/heading are focusable, each with a 2px --garn-ring focus ring.

## Tokens
- `rowGap` → `--garn-gap-stack` (air)
- `columnGap` → `--garn-gap-stack` (air)
- **Internal (never externalize):** `--data-list-label-w`

## Related
- **composes** → `utils`
- **composes** → `button` (when DataList.Value `copyable` renders a ghost Button copy affordance)
- **slotAccepts** → `tag` (when a status value renders a Tag)
- **slotAccepts** → `badge` (when a value renders a Badge)
- **slotAccepts** → `avatar` (when an owner/person value renders an Avatar)
- **pairsWith** → `card` (when the detail block sits inside a Card surface)
- **alternativeTo** → `table` (when the data is rows × columns of records rather than one entity's fields)

## Recipes
- **detail-panel** — An entity detail panel — a carded DataList with aligned values and a divider. _(use when showing one entity's fields as label/value pairs)_

## Gotchas
- **Values don't line up across rows.** — `row` floors the label column to the widest term; exact alignment needs the grid or an explicit width. → Use `orientation="grid"` (subgrid alignment) or set `labelWidth` so every value left-edge lines up.
- **The copy button doesn't appear / nothing happens on copy.** — Copy is gated by the `copyable` prop on DataList.Value, and the clipboard can reject in an insecure context. → Set `copyable` on the Value (the button auto-renders); serve over https so navigator.clipboard resolves.
- **An empty field collapses the row or shows nothing.** — An empty value still renders a placeholder by design (holding the column). → Let it render — pass a clearer `placeholder` ('None on file') if the dash is ambiguous.
- **Building this with <div>s and CSS for the label/value look.** — You lose the announced term↔value relationship that <dl>/<dt>/<dd> gives. → Use DataList.Item / .Term / .Value — the semantics are the whole point.

## Examples
- **basic** (canonical): The default row layout — four field/value pairs.
- **orientations** (edge-case): row · stacked · grid (aligned) side by side.
- **dividers** (edge-case): Hairline rules between rows, with Badge / Avatar values.
- **copyable** (edge-case): Inline copy affordances on IDs / keys / emails.
- **empty** (edge-case): Empty values — the default em-dash and a custom placeholder.
- **sizes** (edge-case): sm · md · lg.
- **overflow** (edge-case): Two long-value strategies — truncate (one line + title) vs wrap (default).
- **in-card** (edge-case): A patient detail panel inside a Card with a status Tag.

---

# DatePicker

> A date field you can both type into and pick from a calendar — format-driven, with a native Date value. Ships a DateRangePicker sibling for ranges.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { DatePicker } from "@garn/ui/date-picker"`

## Overview
DatePicker is the *type-and-pick* date field: a text input you can type a date into **and** a calendar you can pick from, on garn's shared field surface (the same `appearance` × `size` grid as Input and Select). A single **`format` prop** — date-fns tokens like `dd.MM.yyyy` or `MMM d, yyyy` — drives the display, the parse, and the placeholder, so the control round-trips in whatever format you set while the committed value stays a native `Date` (`onValueChange` always hands back a `Date`). Typing parses on blur/Enter and reverts to the last valid value on garbage; picking a day fills the field.

`DateRangePicker` is the sibling export for a `{ start, end }` range — a dual-month calendar with optional preset shortcuts ("Last 7 days", "This month"). Both share one field + popover core with the Calendar and Popover components, so they can't drift from the rest of the form family. Reach for the bare **Calendar** instead when the month should always be visible inline; reach for **Input** when the value isn't a date.

## When to use
Collect a single date (or a date range) in a form where typing is often faster than clicking, but a calendar is still wanted for browsing. Use DateRangePicker for a start/end span with optional presets.

## When not to use
Always-visible month browsing (use Calendar inline); a time-only value (use TimeField/TimePicker); a date + time together (use DateTimePicker); non-date text (use Input).

## Do / Don't
- ✅ Pair with a label and choose a `format` that fits the locale; hold the value in state (or use `defaultValue`).
- ✅ Constrain with `minDate`/`maxDate`/`isDateUnavailable` rather than validating after entry.
- ✅ Reflect validation with aria-invalid + a described message; use `presets` for common ranges.
- ❌ Don't rely on the format-pattern placeholder as the label.
- ❌ Don't hand-set height/padding — the size variant + --garn-control-* tokens own the grid.
- ❌ Don't reach for a segmented MM/DD/YYYY field here — this is the free-text + calendar path (a configurable `format` is its advantage).

## Guidelines
**Pair every picker with a Label, and let `format` document the shape.** A placeholder shows the expected pattern, not the field's name — associate a real Label (or Form's wiring). Pick a `format` that matches your users' locale expectations; it drives typing *and* display, so they stay in sync.

**Constrain to valid dates.** Use `minDate`/`maxDate` and `isDateUnavailable` to disable out-of-range and blackout days in the calendar *and* reject them on typed entry — don't accept-then-error. The calendar's navigation is bounded to the same range.

**Signal validity through state.** Set `aria-invalid` on error (the field reddens border + ring) and wire the message via `aria-describedby` (Form does this). Keep the control keyboard-operable: ArrowDown opens, Enter commits a typed value, Escape closes, and the calendar grid is fully navigable.

**Wire format: calendar dates are zoneless.** With `name`, the hidden form input posts a plain **`yyyy-MM-dd`** string (the `<input type="date">` wire format) — DateRangePicker posts `<name>-start`/`<name>-end` in the same shape. The value is never UTC-shifted through an ISO instant; if your backend truly wants an instant, convert the `Date` from `onValueChange` yourself (`lib/date-io` holds the family's serializers).

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `"aria-invalid"` | `"false" \| "true" \| boolean` | — | no |  |
| `"aria-label"` | `string` | — | no |  |
| `"aria-labelledby"` | `string` | — | no |  |
| `className` | `string` | — | no |  |
| `clearable` | `boolean` | — | no | Show a clear ✕ when a date is set. Default true. |
| `clearLabel` | `string` | — | no |  |
| `contentClassName` | `string` | — | no |  |
| `defaultOpen` | `boolean` | — | no |  |
| `defaultValue` | `Date` | — | no |  |
| `disabled` | `boolean` | — | no |  |
| `format` | `string` | — | no | date-fns token string driving display, parse, and the placeholder. |
| `id` | `string` | — | no |  |
| `isDateUnavailable` | `(date: Date) => boolean` | — | no | Per-date disabling (holidays, blackout dates). |
| `maxDate` | `Date` | — | no |  |
| `minDate` | `Date` | — | no | Lower / upper selectable bound (inclusive, day granularity). |
| `name` | `string` | — | no | Name for a hidden input mirroring the value on form submit as a plain `yyyy-MM-dd` calendar date (the `<input type="date">` wire format — zoneless, never UTC-shifted). |
| `onOpenChange` | `(open: boolean) => void` | — | no |  |
| `onValueChange` | `(date: Date \| undefined) => void` | — | no |  |
| `open` | `boolean` | — | no | Popover open state (controlled). |
| `placeholder` | `string` | — | no | Field placeholder; defaults to the `format` pattern. |
| `presets` | `DatePreset[]` | — | no | Quick-pick shortcuts rendered beside the calendar (e.g. Today, Yesterday). |
| `readOnly` | `boolean` | — | no |  |
| `ref` | `React.Ref<HTMLInputElement>` | — | no |  |
| `required` | `boolean` | — | no |  |
| `triggerLabel` | `string` | — | no | Accessible name for the calendar toggle button. |
| `value` | `Date` | — | no | Selected date (controlled). |

_Plus 3 inherited native `<input>` attributes._

### `DateRangePicker` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `"aria-invalid"` | `"false" \| "true" \| boolean` | — | no |  |
| `"aria-label"` | `string` | — | no |  |
| `"aria-labelledby"` | `string` | — | no |  |
| `className` | `string` | — | no |  |
| `clearable` | `boolean` | — | no |  |
| `clearLabel` | `string` | — | no |  |
| `contentClassName` | `string` | — | no |  |
| `defaultOpen` | `boolean` | — | no |  |
| `defaultValue` | `DateRangeValue` | — | no |  |
| `disabled` | `boolean` | — | no |  |
| `format` | `string` | — | no | date-fns token string applied to both ends + the placeholder. |
| `id` | `string` | — | no |  |
| `isDateUnavailable` | `(date: Date) => boolean` | — | no |  |
| `maxDate` | `Date` | — | no |  |
| `minDate` | `Date` | — | no |  |
| `name` | `string` | — | no | Base name for hidden inputs mirroring the range on form submit (`<name>-start` / `<name>-end`), each a plain `yyyy-MM-dd` calendar date. |
| `numberOfMonths` | `number` | — | no | Number of month grids shown side by side. Default 2. |
| `onOpenChange` | `(open: boolean) => void` | — | no |  |
| `onValueChange` | `(range: DateRangeValue \| undefined) => void` | — | no |  |
| `open` | `boolean` | — | no |  |
| `placeholder` | `string` | — | no |  |
| `presets` | `DateRangePreset[]` | — | no | Quick-pick ranges rendered beside the calendar. |
| `readOnly` | `boolean` | — | no |  |
| `ref` | `React.Ref<HTMLInputElement>` | — | no |  |
| `required` | `boolean` | — | no |  |
| `triggerLabel` | `string` | — | no |  |
| `value` | `DateRangeValue` | — | no |  |

_Plus 5 inherited native HTML attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · Date — The selected date as a native `Date`. Controlled via `value` + `onValueChange` (fires with `Date | undefined`); uncontrolled via `defaultValue`. `format` ⊥ value — display is formatting only.
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — The calendar popover's open state. Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen`.
- Selection: single.

## Anatomy
- `datepicker`: The field shell — the visible control surface (border, focus-within ring, invalid/disabled). Styled by `className`.
- `datepicker-input`: The borderless <input> — the type target; ref + typed value land here.
- `datepicker-affordances`: The trailing zone: clear ✕ (when set) + the calendar toggle button.
- `datepicker-clear`: The clear button — shown only when a date is set and not disabled/readOnly.
- `datepicker-trigger`: The calendar toggle (Popover trigger); ArrowDown from the field also opens it.
- `datepicker-presets`: Optional quick-pick column beside the calendar (e.g. Today, Yesterday).

**Parts**
- `DateRangePicker` (`date-range-picker`): The range sibling — value is `{ start, end }`; renders a dual-month Calendar (mode=range) with optional `presets` and hidden `<name>-start`/`<name>-end` form inputs (each a `yyyy-MM-dd` calendar date).

## Accessibility
- **Role:** textbox (APG: date-picker-dialog)
- **ArrowDown:** Open the calendar from the field.
- **Enter:** Commit the typed date.
- **Escape:** Close the calendar.
- **ArrowLeft / ArrowRight / ArrowUp / ArrowDown:** Move by day / week inside the open calendar grid.
- **PageUp / PageDown:** Previous / next month in the calendar.
- **Enter / Space:** Select the focused day (closes the calendar).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- Give the field an accessible label — a <label htmlFor>, aria-label, or aria-labelledby; the placeholder (the format pattern) is not a label.
- The expected format is announced via a visually-hidden aria-describedby hint.
- Opening the calendar moves focus to the selected/today day; on close, focus returns to the field.
- The calendar is react-day-picker's labeled grid (roving focus; days expose aria-selected + disabled).
- Reflect validation with aria-invalid + a described error message.
- **Focus:** Border darkens on any focus; keyboard focus adds a neutral ring. On open, focus enters the calendar grid; on close it returns to the field.
- **Contract (warn):** Give every date picker an accessible label; the format-pattern placeholder is not a label. — _when no associated <label htmlFor>, aria-label, or aria-labelledby_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)
- `borderColor` → `--garn-foreground`
- `iconInset` → `--garn-control-icon-inset`
- **Internal (never externalize):** `--in-px`

## Related
- **composes** → `utils`
- **composes** → `field-surface`
- **composes** → `calendar`
- **composes** → `popover`
- **composes** → `button`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `calendar` (when the month should always be visible inline)
- **alternativeTo** → `input` (when the value isn't a date)

## Recipes
- **labeled-date-field** — A labeled date field — the canonical form row. _(use when collecting a date in a form)_

## Gotchas
- **Typing a date does nothing / it snaps back.** — The typed text didn't match `format`, so it reverted to the last valid value on blur. → Type in the exact `format` (shown as the placeholder), or pick from the calendar.
- **onValueChange gives a Date with the wrong time / timezone.** — The value is a native `Date` at local midnight for date-only pickers. → Treat the value as a calendar date; for date + time use DateTimePicker.
- **DateRangePicker's value is undefined after picking one day.** — A range needs both ends; onValueChange reports `{ start, end }` with end still undefined until the second pick. → Read `value.start` / `value.end`; the popover closes once both are set.

## Examples
- **basic** (canonical): A default date field (type or pick).
- **format** (canonical): A custom `format` (dd.MM.yyyy) driving display + parse.
- **constraints** (edge-case): minDate + isDateUnavailable (weekdays this year).
- **validation** (edge-case): A required field that clears its error once set.
- **presets** (edge-case): Quick-pick shortcuts beside the calendar.
- **states** (edge-case): Disabled and invalid.
- **appearances** (playground): outline · soft · ghost.
- **sizes** (playground): xs · sm · md · lg · xl.
- **range** (canonical): DateRangePicker — a start/end range.
- **range-presets** (edge-case): DateRangePicker with preset ranges + dual-month.

---

# DateTimePicker

> A combined date + time field — a calendar and a time field in one popover, with a single Date value.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { DateTimePicker } from "@garn/ui/date-time-picker"`

## Overview
DateTimePicker is the combined date + time control. One typeable field opens a Popover that pairs the **Calendar** (date) with a **TimeField** (time): picking a day keeps the current time, editing the time keeps the day, and the committed value is a single native `Date` carrying both. A `format` prop (date + time tokens like `MM/dd/yyyy HH:mm`) drives the field's display/parse/placeholder; `timeFormat` drives the inner time field.

It's built on the same field + popover shell as DatePicker (and reuses TimeField), so it matches the rest of the form family. Use **DatePicker** when there's no time, and **TimeField/TimePicker** when there's no date.

## When to use
Collect a date and a time together as one timestamp (event start, deadline, appointment).

## When not to use
Date only (use DatePicker); time only (use TimeField/TimePicker); a range of date-times (compose two, or use DateRangePicker for date-only ranges).

## Do / Don't
- ✅ Pair with a label; choose a combined `format` and a matching `timeFormat`.
- ✅ Constrain the date with min/max/isDateUnavailable.
- ✅ Hold the value in state; read it as one `Date`.
- ❌ Don't rely on the placeholder as the label.
- ❌ Don't split date and time into two separate values — the point is one `Date`.

## Guidelines
**Pair with a Label and choose a `format` that shows both parts** (date + time). Constrain the date with `minDate`/`maxDate`/`isDateUnavailable`. The field is fully keyboard-operable (ArrowDown opens, Enter commits, Escape closes); inside the popover the calendar and the time field are separate, each operable on its own. **Reflect validity** with aria-invalid + a described message.

**Wire format: local wall time, no Z.** With `name`, the hidden form input posts **`yyyy-MM-dd'T'HH:mm:ss`** (the `<input type="datetime-local">` wire format) — exactly what the user expressed, never silently converted to UTC. If your backend wants a UTC instant, convert the `Date` from `onValueChange` yourself; that's a consumer decision, not the library default.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `"aria-invalid"` | `"false" \| "true" \| boolean` | — | no |  |
| `"aria-label"` | `string` | — | no |  |
| `"aria-labelledby"` | `string` | — | no |  |
| `className` | `string` | — | no |  |
| `clearable` | `boolean` | — | no |  |
| `clearLabel` | `string` | — | no |  |
| `contentClassName` | `string` | — | no |  |
| `defaultOpen` | `boolean` | — | no |  |
| `defaultValue` | `Date` | — | no |  |
| `disabled` | `boolean` | — | no |  |
| `format` | `string` | — | no | Field format (date + time tokens). |
| `id` | `string` | — | no |  |
| `isDateUnavailable` | `(date: Date) => boolean` | — | no |  |
| `maxDate` | `Date` | — | no |  |
| `minDate` | `Date` | — | no |  |
| `name` | `string` | — | no | Name for a hidden input mirroring the value on form submit as a LOCAL date-time `yyyy-MM-dd'T'HH:mm:ss` with no Z/offset (the `<input type="datetime-local">` wire format). Serializing a UTC instant is a consumer decision — convert the `Date` yourself if you truly mean one. |
| `onOpenChange` | `(open: boolean) => void` | — | no |  |
| `onValueChange` | `(value: Date \| undefined) => void` | — | no |  |
| `open` | `boolean` | — | no |  |
| `placeholder` | `string` | — | no |  |
| `readOnly` | `boolean` | — | no |  |
| `ref` | `React.Ref<HTMLInputElement>` | — | no |  |
| `required` | `boolean` | — | no |  |
| `step` | `number` | — | no | Minutes stepped by the TimeField arrow keys. |
| `timeFormat` | `string` | — | no | Format for the inner TimeField. |
| `triggerLabel` | `string` | — | no |  |
| `value` | `Date` | — | no |  |

_Plus 3 inherited native `<input>` attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · Date — A single native `Date` carrying both date and time. Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`.
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — The popover's open state. Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen`.
- Selection: single.

## Anatomy
- `date-time-picker`: The field shell (shared with the date pickers) — the visible control surface. Styled by `className`.
- `date-time-picker-input`: The borderless <input> — the type target.
- `date-time-picker-trigger`: The calendar toggle (Popover trigger).
- `date-time-picker-clear`: The clear button — shown when a value is set.
- `calendar`: The Calendar (mode=single) in the popover — sets the date.
- `time`: The inner TimeField beside the calendar — sets the time.

## Accessibility
- **Role:** textbox (APG: date-picker-dialog)
- **ArrowDown:** Open the calendar + time popover.
- **Enter:** Commit the typed date-time.
- **Escape:** Close the popover.
- **ArrowUp / ArrowDown:** Step the time (inside the time field) by `step` minutes.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- Give the field an accessible label; the format-pattern placeholder is not a label.
- The popover pairs a labeled calendar grid with a labeled time field; each is independently operable.
- Reflect validation with aria-invalid + a described message.
- **Focus:** Field focus surface as the date pickers; on open, focus enters the calendar; the time field is a separate tab stop in the popover.
- **Contract (warn):** Give every date-time picker an accessible label. — _when no associated <label htmlFor>, aria-label, or aria-labelledby_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)

## Related
- **composes** → `utils`
- **composes** → `date-picker`
- **composes** → `time-field`
- **composes** → `calendar`
- **composes** → `use-controllable-state`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `date-picker` (when no time is needed)

## Gotchas
- **Picking a date resets the time to midnight.** — There was no time yet, so the first date pick defaults the time to 00:00. → Set the time via the inner time field (it's preserved on subsequent date picks).
- **Typed date-time snaps back.** — The text didn't match `format` (which includes the time tokens). → Type in the exact `format` shown as the placeholder.

## Examples
- **basic** (canonical): A default date + time field.
- **twelve-hour** (canonical): A 12-hour format with a custom date-time pattern.
- **states** (edge-case): Disabled and invalid.

---

# Dialog

> A modal surface that interrupts the flow for a focused task or message.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { Dialog } from "@garn/ui/dialog"`
- **Polymorphism:** `asChild`

## Overview
Dialog interrupts the flow for a focused task that needs attention before the user moves on — a short form, a detail view, a confirmation. It's a **compound** built on Radix: `Dialog` owns the open state, `DialogTrigger` opens it, and `DialogContent` is a focus-trapped surface that renders its own overlay and close button. Inside, `DialogTitle` (required), `DialogDescription`, and the `DialogHeader`/`DialogFooter` layout wrappers structure the content; `DialogClose` dismisses it.

The modal contract is the whole point: focus is trapped while open and returned to the trigger on close, the background is inert, and Escape closes. Pick Dialog when the task is short and self-contained. For a *destructive confirmation* that must not be dismissed by clicking away, use AlertDialog; for a long form or a side panel, use Sheet; for lightweight, non-blocking context anchored to a control, use Popover.

## When to use
Interrupt the flow for a focused task or message that needs attention before continuing — a short form, details, or confirmation.

## When not to use
A destructive yes/no that must force an explicit choice (use alert-dialog); contextual, non-blocking content near a control (use popover); a large side panel (use sheet or drawer).

## Do / Don't
- ✅ Always include a DialogTitle (sr-only if you don't want it visible).
- ✅ Keep the task short; put primary/secondary actions in a DialogFooter.
- ✅ Let Escape and the overlay close it — don't trap users.
- ❌ Don't stack dialogs or nest a dialog inside a dialog.
- ❌ Don't use a modal for a destructive confirm — alert-dialog is purpose-built for that.

## Guidelines
**Always render a `DialogTitle`** — it's the dialog's accessible name and the contract is enforced. If the design has no visible heading, keep the title and visually hide it (sr-only); don't drop it. Pair it with a `DialogDescription` whenever a sentence of context would help, so it wires to `aria-describedby`.

**Keep dialogs short and single-purpose.** A dialog is for one focused task; if it grows into a multi-step flow or a long scroll, that's a sign it should be a full page or a Sheet. Put the primary action in the `DialogFooter` as the one filled button, with Cancel/Close demoted beside it.

**Don't stack or auto-open dialogs.** Opening a dialog from inside a dialog traps focus in a confusing nest; resolve one before opening the next. Reserve dialogs for moments that genuinely warrant interrupting the user — overusing them for messages that a Sonner toast or inline Alert could carry trains people to dismiss them on reflex.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen` (or just a DialogTrigger).
- Selection: single.

## Anatomy

**Parts**
- `Dialog` · required: Root — owns the open state. No DOM of its own.
- `DialogTrigger` (`dialog-trigger`): Opens the dialog (use asChild to wrap your own button).
- `DialogContent` (`dialog-content`) · required: Focus-trapped surface (renders the overlay + a built-in close button).
- `DialogTitle` (`dialog-title`) · required: Accessible name for the dialog (required; sr-only if visually hidden).
- `DialogDescription` (`dialog-description`): Supplementary description, wired to aria-describedby.
- `DialogHeader` (`dialog-header`): Layout wrapper for title + description.
- `DialogFooter` (`dialog-footer`): Layout wrapper for actions (right-aligned on ≥sm).
- `DialogClose` (`dialog-close`): Closes the dialog (e.g. a Cancel button).

## Accessibility
- **Role:** dialog (APG: dialog (modal))
- **Escape:** Close the dialog.
- **Tab / Shift+Tab:** Cycle focus within the dialog (focus is trapped).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.3 Focus Order (A); 4.1.2 Name, Role, Value (A)
- aria-modal; labelled by DialogTitle and (if present) described by DialogDescription.
- Focus moves into the dialog on open and returns to the trigger on close.
- **Focus:** Focus trapped inside the content; returns to the trigger on close.
- **Contract (warn):** Every DialogContent must contain a DialogTitle (wrap it in sr-only to hide it visually). — _when DialogContent has no DialogTitle_

## Tokens
- `padding` → `--garn-pad-surface` (air)
- `gap` → `--garn-gap-stack` (air)
- `closeSize` → `--garn-control-h-xs` (air)
- `motion` → `--garn-motion-fast`

## Related
- **composes** → `utils`
- **pairsWith** → `button` (when as the trigger and the footer actions)
- **alternativeTo** → `alert-dialog` (when the dialog forces an explicit destructive choice)
- **alternativeTo** → `sheet` (when a side panel fits the task better)
- **alternativeTo** → `popover` (when the content is contextual and non-blocking)

## Recipes
- **modal-form** — A short form inside a dialog, with footer actions. _(use when a focused create/edit task shouldn't navigate away)_

## Gotchas
- **Console warning about a missing Description / Title; screen readers can't name the dialog.** — DialogContent without a DialogTitle (Radix requires it). → Add a DialogTitle (wrap in an sr-only span if you don't want it visible); add DialogDescription to silence the description warning.

## Examples
- **basic** (canonical): Trigger → titled dialog with footer actions.

---

# Drawer

> A bottom sheet that slides up and can be swiped to dismiss — mobile-first.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { Drawer } from "@garn/ui/drawer"`
- **Polymorphism:** `asChild`

## Overview
Drawer surfaces a secondary task from the bottom edge on touch/mobile — quick settings, a picker, contextual actions you can swipe away. `DrawerContent` renders a centered drag handle and the page scales back behind it (`shouldScaleBackground`), giving the native bottom-sheet feel; `DrawerTitle` (required) names it. It's the mobile counterpart to a Sheet: on the desktop, an edge Sheet or a Popover usually fits better than a bottom drawer.

## When to use
Surface a secondary task or details from the bottom edge on touch/mobile — quick settings, a picker, contextual actions you can swipe away.

## When not to use
A desktop side panel (use sheet); a small focused confirmation (use dialog / alert-dialog); contextual content anchored to a control (use popover).

## Do / Don't
- ✅ Always include a DrawerTitle (sr-only if you don't want it visible).
- ✅ Keep content short — a drawer is a quick, dismissible surface, not a full page.
- ✅ Provide an explicit action/close in the footer in addition to swipe-to-dismiss.
- ❌ Don't use a drawer for primary desktop layouts — prefer sheet there.
- ❌ Don't omit the DrawerTitle.
- ❌ Don't pack a long form into a bottom sheet — promote it to a page or dialog.

## Guidelines
**Use the drawer where the bottom-sheet gesture belongs — touch.** It's tuned for thumbs: swipe-to-dismiss and a drag handle. On pointer-first layouts, prefer a right Sheet or an anchored Popover instead of forcing a bottom sheet.

**Keep it short enough to swipe away.** A drawer is for a quick, dismissible task; if it needs to fill the screen or scroll heavily, that's really a full page or a Sheet. Pin primary actions in `DrawerFooter` within thumb reach.

**Always render a `DrawerTitle` and respect dismissal.** It's the accessible name (sr-only if visually hidden); swipe-down, the overlay, and Escape all close. Don't trap a destructive, no-undo action behind a gesture that's easy to trigger by accident.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen` (or just a DrawerTrigger). Swiping down also closes it.
- Selection: single.

## Anatomy

**Parts**
- `Drawer` · required: Root — owns the open state; `shouldScaleBackground` (default true) scales the page behind it.
- `DrawerTrigger` (`drawer-trigger`): Opens the drawer (asChild to wrap your own button).
- `DrawerContent` (`drawer-content`) · required: The bottom panel; portals its overlay and renders a centered drag handle.
- `DrawerClose` (`drawer-close`): Closes the drawer (e.g. a Cancel button).
- `DrawerTitle` (`drawer-title`) · required: Accessible name for the drawer (required; sr-only if visually hidden).
- `DrawerDescription` (`drawer-description`): Supplementary description, wired to aria-describedby.
- `DrawerHeader` (`drawer-header`): Layout wrapper for title + description (panel padding).
- `DrawerFooter` (`drawer-footer`): Bottom-pinned wrapper for actions (panel padding).

## Accessibility
- **Role:** dialog (APG: dialog (modal))
- **Escape:** Close the drawer.
- **Tab / Shift+Tab:** Cycle focus within the drawer (focus is trapped).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.3 Focus Order (A); 4.1.2 Name, Role, Value (A)
- vaul wraps Radix Dialog — aria-modal, labelled by DrawerTitle, described by DrawerDescription.
- Swipe/drag down dismisses it; the same close paths (Escape / overlay / DrawerClose) work for keyboard and pointer.
- Focus moves into the drawer on open and returns to the trigger on close.
- **Focus:** Focus trapped inside the content; returns to the trigger on close.
- **Contract (warn):** Every DrawerContent must contain a DrawerTitle (wrap it in sr-only to hide it visually). — _when DrawerContent has no DrawerTitle_

## Tokens
- `padding` → `--garn-pad-panel` (air)
- `headerGap` → `--garn-gap-field` (air)

## Related
- **composes** → `utils`
- **pairsWith** → `button` (when as the trigger and the footer actions)
- **alternativeTo** → `sheet` (when on desktop, or when an edge side-panel fits better than a bottom sheet)
- **alternativeTo** → `dialog` (when a centered modal suits the task)

## Recipes
- **mobile-actions** — A swipe-dismissable bottom sheet of contextual actions on touch. _(use when a touch user needs a quick, dismissable surface)_

## Gotchas
- **The page behind the drawer doesn't scale (or looks odd) with shouldScaleBackground.** — The scale effect needs the app root marked `data-vaul-drawer-wrapper` with a background set. → Wrap the app root in `[data-vaul-drawer-wrapper]` (or pass shouldScaleBackground={false}).
- **Screen readers can't name the drawer / a console warning about a missing title.** — DrawerContent without a DrawerTitle. → Add a DrawerTitle (sr-only if hidden) and a DrawerDescription.

## Examples
- **basic** (canonical): Trigger → bottom drawer with footer actions.

---

# Dropdown Menu

> A menu of actions and toggles launched from a button.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { DropdownMenu } from "@garn/ui/dropdown-menu"`
- **Polymorphism:** `asChild`

## Overview
DropdownMenu offers a list of commands or toggles from a button — row/overflow (kebab) actions, an account menu, view options. It's a rich compound: action `DropdownMenuItem`s, toggleable `CheckboxItem`s, single-select `RadioGroup`/`RadioItem`s, `Label`/`Separator` for structure, `Shortcut` hints, and nested `Sub` menus. It's a menu of *actions*, not a form control — to pick a value that stays on a field use Select, to right-click an element use ContextMenu, and to search-and-run use Command.

## When to use
Offer a list of commands or toggles from a button — row/overflow (kebab) actions, an account menu, view options.

## When not to use
Selecting a value in a form (use select); a few always-visible options (use radio-group / a button group); contextual rich content or a form (use popover); a right-click menu (use context-menu).

## Do / Don't
- ✅ Give the trigger an accessible name (aria-label if it's icon-only).
- ✅ Group with DropdownMenuLabel + DropdownMenuSeparator; keep destructive items separated.
- ✅ Control CheckboxItem (`checked` + `onCheckedChange`) and RadioGroup (`value` + `onValueChange`) state.
- ❌ Don't use a dropdown-menu as a form select — use select.
- ❌ Don't rely on DropdownMenuShortcut to actually bind a key — it's display only; wire the handler yourself.
- ❌ Don't nest deep submenu trees — flatten or split the menu.

## Guidelines
**Menus are for actions, not data entry.** Use it to *do* things or flip view toggles; if the user is choosing a form value, that's a Select. Order items by likelihood, group related ones with a Separator, and keep destructive actions visually distinct and away from the default-focus path.

**Label icon-only triggers and keep the list shallow.** The trigger needs an accessible name (a kebab button is meaningless to screen readers otherwise). Avoid deep `Sub` nesting — one level is usually plenty; more becomes a maze on touch.

**`Shortcut` is a hint, not a binding.** It displays the key combo but doesn't register it — wire the actual keyboard handler yourself. Selecting an item closes the menu; for toggles that should persist the menu open, use `CheckboxItem`/`RadioItem`.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Whether the menu is open. Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen` (or just a trigger). CheckboxItem (`checked`) and RadioGroup (`value`) hold their own item-level state.
- Selection: single.

## Anatomy

**Parts**
- `DropdownMenu` · required: Root — owns the open state. No DOM of its own.
- `DropdownMenuTrigger` (`dropdown-menu-trigger`) · required: The menu button (asChild to wrap your own button); exposes aria-haspopup / aria-expanded.
- `DropdownMenuContent` (`dropdown-menu-content`) · required: The portaled, scrollable menu surface.
- `DropdownMenuItem` (`dropdown-menu-item`): An action item; `inset` aligns it with checkbox/radio items. Selecting it closes the menu.
- `DropdownMenuCheckboxItem` (`dropdown-menu-checkbox-item`): A toggleable item (controlled via `checked` + `onCheckedChange`).
- `DropdownMenuRadioGroup`: Groups radio items; owns the selected `value`.
- `DropdownMenuRadioItem` (`dropdown-menu-radio-item`): A single-select item inside a RadioGroup.
- `DropdownMenuLabel` (`dropdown-menu-label`): A non-interactive section heading; `inset` for alignment.
- `DropdownMenuSeparator` (`dropdown-menu-separator`): Divider between groups.
- `DropdownMenuShortcut` (`dropdown-menu-shortcut`): Right-aligned keyboard-shortcut hint (display only — doesn't bind the key).
- `DropdownMenuGroup`: Semantic grouping of related items.
- `DropdownMenuSub`: A submenu container (Sub / SubTrigger / SubContent).
- `DropdownMenuSubTrigger` (`dropdown-menu-sub-trigger`): Opens a submenu; `inset` for alignment.
- `DropdownMenuSubContent` (`dropdown-menu-sub-content`): The nested submenu surface.

## Accessibility
- **Role:** menu (APG: menu button)
- **Enter / Space / ArrowDown / ArrowUp:** Open the menu from the trigger.
- **ArrowUp / ArrowDown:** Move between items.
- **ArrowRight / ArrowLeft:** Open / close a submenu.
- **Home / End:** Jump to the first / last item.
- **A–Z:** Type-ahead to a matching item.
- **Enter / Space:** Activate the highlighted item.
- **Escape:** Close the menu and return focus to the trigger.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A); 2.4.7 Focus Visible (AA)
- Trigger is a menu button (aria-haspopup=menu, aria-expanded); Content is role=menu with roving focus.
- Items are menuitem / menuitemcheckbox / menuitemradio; checked items expose aria-checked.
- An icon-only trigger relies on the menu for nothing — give the trigger its own accessible name.
- **Focus:** Roving focus across items; focus returns to the trigger on close.
- **Contract (warn):** Give an icon-only menu trigger an accessible name (aria-label). — _when the DropdownMenuTrigger is an icon-only control with no aria-label / aria-labelledby / text_

## Tokens
- `itemMinHeight` → `--garn-control-h-md` (air)

## Related
- **composes** → `utils`
- **pairsWith** → `button` (when as the menu trigger)
- **slotAccepts** → `kbd` (when rendering a shortcut hint in DropdownMenuShortcut)
- **alternativeTo** → `select` (when the menu is really choosing one value in a form)
- **alternativeTo** → `context-menu` (when the menu should open on right-click instead of a button)
- **alternativeTo** → `popover` (when the surface holds a form or rich content, not a list of commands)

## Recipes
- **row-actions** — An overflow (kebab) menu of actions for a list/table row. _(use when a row/card needs secondary actions without crowding the layout)_

## Gotchas
- **A checkbox item closes the menu every time it's toggled.** — Selecting an item closes the menu by default. → Call `e.preventDefault()` in the item's onSelect to keep the menu open for multi-toggle.
- **The toggle/radio state resets each time the menu reopens.** — CheckboxItem/RadioGroup state wasn't lifted. → Control `checked` + `onCheckedChange` (checkbox) or `value` + `onValueChange` (radio group) in your state.
- **An icon-only trigger is announced with no name.** — The menu doesn't name its trigger. → Pass aria-label to the DropdownMenuTrigger (or the button it wraps).

## Examples
- **basic** (canonical): Account menu with a label, items, shortcuts, and a separator.

---

# Empty

> A centered empty-state surface — no results, first-run, or a cleared list.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** feedback
- **Import:** `import { Empty } from "@garn/ui/empty"`

## Overview
Empty communicates a blank state — no search results, nothing created yet, a cleared list — and turns a dead end into a next step. `EmptyHeader` groups the `EmptyMedia` (icon/illustration), `EmptyTitle`, and `EmptyDescription`, with `EmptyContent` below for an action. It's for a genuinely empty result, not a wait: use a Skeleton or Spinner while loading, and an Alert for an error.

## When to use
Communicate a blank state — no search results, nothing created yet, a cleared list.

## When not to use
For a transient loading state — use a Spinner or a Skeleton that preserves layout.

## Do / Don't
- ✅ Lead with a concise title and one clear next action in EmptyContent.
- ✅ Use EmptyMedia variant="icon" for a single lucide icon.
- ❌ Don't stack multiple competing actions.
- ❌ Don't use it for errors that need an accessible alert without providing one.

## Guidelines
**Distinguish the three blanks.** "Nothing yet" (onboarding), "no matches" (a filtered search), and "all done" each want different copy and actions — don't ship one generic "No data". Name which one it is and what to do about it.

**Always offer a way forward.** The most useful empty state includes the next action — "Create your first project", "Clear filters". For a no-results search, suggest broadening the query rather than leaving the user stuck.

**Keep the tone light and the layout calm.** A short title, a sentence of guidance, and one primary action; the illustration sets mood but shouldn't dominate. Don't confuse empty with error — reserve alarming language for actual failures.

## Anatomy
- `empty`: Centered container. Outer padding + stack gap are AIR (density-scaled).

**Parts**
- `EmptyHeader` (`empty-header`) · required: Groups media + title + description.
- `EmptyMedia` (`empty-media`): Media holder. Has its own `variant`: `icon` is a tonal rounded tile for a single lucide icon; `default` is a bare slot for illustrations or an Avatar. (Sets data-variant.)
- `EmptyTitle` (`empty-title`): The headline. Identity type (fixed).
- `EmptyDescription` (`empty-description`): Supporting copy.
- `EmptyContent` (`empty-content`): Actions / secondary content below the header.

## Accessibility
- Use a real heading (or aria-labelledby pointing at EmptyTitle) where the state should be announced.
- If it reports an error that needs attention, give the actionable message role=status or wrap it in an alert.

## Tokens
- `padding` → `--garn-pad-surface` (air)
- `stackGap` → `--garn-gap-stack` (air)
- `fieldGap` → `--garn-gap-field` (air)
- `mediaTile` → `--garn-muted` (identity)

## Related
- **composes** → `utils`
- **slotAccepts** → `button` (when as the primary next action)
- **alternativeTo** → `skeleton` (when the state is loading, not empty)

## Recipes
- **no-results** — A filtered list returned nothing; offer a way to clear filters. _(use when a filtered or searched collection returns zero items)_

## Gotchas
- **The media icon sits on a double background or wrong tile.** — EmptyMedia variant="icon" already provides the tonal rounded tile. → Don't add your own background; use variant="default" for custom illustrations.

## Examples
- **basic** (canonical): An empty inbox with a next action.

---

# Field

> Pairs a control with a label and optional description, as a row or a card.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** layout
- **Import:** `import { Field } from "@garn/ui/field"`

## Overview
Field is the shared control-field: it takes a Switch, Checkbox, or a single RadioGroupItem as its child and lays it beside a label and an optional one-line description, doing the accessible-name (htmlFor) and description (aria-describedby) wiring for you. `appearance="card"` turns the row into a bordered option card that highlights when its control is checked, and `orientation` flips between a control-leading row (checkboxes, radios) and a text-leading settings row (the switch on the right). Because it wires by cloning the control, one Field looks and behaves identically whichever control drives it. For a form bound to react-hook-form with validation messages, use Form instead; Field is the lightweight, standalone layout.

## When to use
Pair a Switch / Checkbox / RadioGroupItem with a label (+ optional description), as a plain row or a selectable card.

## When not to use
A form bound to react-hook-form with validation messages (use Form); a label with no control (use Label directly).

## Do / Don't
- ✅ Pass exactly one control as children; let Field wire the label + description.
- ✅ Use `appearance="card"` for pick-one option cards, `orientation="end"` for switch settings rows.
- ❌ Don't add an aria-label to the control — the Field's label already names it.
- ❌ Don't put multiple controls in one Field; wrap each in its own Field.

## Guidelines
**Give every Field a label — that IS the control's name.** The label is required and is associated by `htmlFor`, so you don't add a separate `aria-label` to the control. Add a `description` only when the effect isn't obvious from the label.

**Use `card` for selectable options, `plain` for dense settings.** A list of option cards (pick-one radios, feature toggles) reads well as `card`; a long settings screen is calmer as `plain` rows with a divider. The card's checked-edge highlight only makes sense when one option among several is chosen.

**Match `orientation` to the control.** Checkboxes and radios read naturally control-first (`start`); a switch usually sits at the end of a settings row (`end`), label on the left. Keep the whole group consistent.

**One control per Field.** Field clones a single child to wire it. For a group of radios, wrap each RadioGroupItem in its own Field inside one RadioGroup.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"card" \| "plain"` | `plain` | no |  |
| `orientation` | `"end" \| "start"` | `start` | no |  |
| `children` | `React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>` | — | yes | The control: a Switch, Checkbox, or single RadioGroupItem. |
| `description` | `React.ReactNode` | — | no | Optional one-line explanation, wired to the control via `aria-describedby`. |
| `label` | `React.ReactNode` | — | yes | The setting name — becomes the control's accessible name via `htmlFor`. |
| `size` | `"lg" \| "md" \| "sm"` | — | no | Label text size — pair with the control's own `size`. |

_Plus 279 inherited native `<div>` attributes._

## Variants
- **appearance** (default `plain`): `plain`, `card`
- **orientation** (default `start`): `start`, `end`

## Anatomy
- `field`: The row/card container; lays out the control and the text column.
- `control`: The wrapped control (children) — cloned to receive the id + aria-describedby.
- `label`: The setting name (a Label, associated via htmlFor).
- `description`: Optional one-line explanation, referenced by aria-describedby.

## Accessibility
- **WCAG:** 1.3.1 Info and Relationships (A); 4.1.2 Name, Role, Value (A)
- The Label's htmlFor points at the control's generated id, so the control's accessible name is the label text.
- A description is given an id and wired onto the control via aria-describedby (preserving any aria-describedby the control already had).
- Clicking the label toggles the control (native label association); the description is not part of the accessible name.
- **Contract (warn):** Pass exactly one control (Switch, Checkbox, or a RadioGroupItem) as children — Field clones it to inject the id + aria-describedby. — _when children is not a single control element_

## Tokens
- `cardSurface` → `--garn-card`
- `cardPadding` → `--garn-pad-panel` (air)
- `selectedEdge` → `--garn-brand-solid` · brandable
- `descriptionColor` → `--garn-muted-foreground`

## Related
- **composes** → `utils`
- **composes** → `label`
- **slotAccepts** → `switch`
- **slotAccepts** → `checkbox`
- **slotAccepts** → `radio-group`
- **alternativeTo** → `form` (when the field is bound to react-hook-form and needs validation messages)

## Recipes
- **switch-settings-row** — A switch settings row — label + description on the left, switch on the right. _(use when a toggle needs a description)_
- **radio-option-cards** — Pick-one option cards — each RadioGroupItem in its own card Field inside one RadioGroup. _(use when choosing one option from a small set with descriptions)_

## Gotchas
- **The control has no accessible name / axe flags it.** — The Field's `label` is missing, or an aria-label on the control competes with it. → Always pass `label`; don't add aria-label to the control — Field names it via htmlFor.
- **The card doesn't highlight when selected.** — The child control doesn't expose data-state=checked (or isn't checked). → Use a Switch / Checkbox / RadioGroupItem as the child — the card reads their data-state via :has().

## Examples
- **basic** (canonical): Settings row: label + description + switch.
- **card** (canonical): Card appearance.
- **controls** (canonical): Same Field with a checkbox and radio items.

---

# File Upload

> A drag-and-drop file intake surface for business documents — résumés, attachments, deal-room docs. Accessible-first (a real, keyboard-operable file input; drag is progressive enhancement) and transport-agnostic (it owns file state, validation, and per-item status/progress display — the consumer drives the actual upload and reports progress back through a controlled `files` array). Typed rejections (type/size/count/totalSize/duplicate), directory drop, a running total, retry/remove, and drag-reorder — with rows composed from List + per-row Progress.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { FileUpload } from "@garn/ui/file-upload"`

## Overview
FileUpload is a drag-and-drop intake surface for business documents — résumés, attachments, deal-room docs — not a photo gallery. It is accessible-first: the dropzone is a real, keyboard-operable file input, and drag is progressive enhancement on top. It is also transport-agnostic — it owns the file queue, validation, drag state, and per-item status/progress display, but never performs the network request. You drive your own upload (fetch / XHR / presigned URL / tus) and push status and progress back through the controlled `files` array. File rows are composed from List (so they inherit its a11y and drag-reorder) and per-row Progress. Omit `files` for a plain collect-files-for-a-form field; pass `files` + `onFilesChange` to drive real progress.

## When to use
Letting a user attach one or more documents — a résumé, email attachments, a batch of deal-room docs — via drag-and-drop or a file picker, with validation, per-file status/progress, and retry/remove. Omit `files` for a simple form field; pass `files` + `onFilesChange` to show real upload progress.

## When not to use
An image/media gallery with thumbnail grids and cropping (FileUpload is document-first — mime icons, not thumbnails); a single avatar/photo picker (use a plain Input type=file or an Avatar upload affordance); when you need a bundled resumable/chunked transport out of the box (FileUpload is transport-agnostic — wire your own, or reach for a dedicated uploader); a plain text field (use Input).

## Do / Don't
- ✅ Drive the actual upload yourself: on `onFilesAccepted`, start your transport and push `status`/`progress` back through the controlled `files` array.
- ✅ Set `accept` / `maxSize` / `maxFiles` / `maxTotalSize` and surface `onFilesRejected` reasons to the user.
- ✅ Give the input a meaningful `label`; keep the real file input as the accessible path.
- ✅ Use `directory` for folder drops and `reorderable` to let users order attachments.
- ✅ Wire `onRetry` to restart a failed upload and `onRemove` to cancel an in-flight one.
- ❌ Don't expect FileUpload to perform the network request — it's transport-agnostic by design.
- ❌ Don't hide or bypass the real <input type=file> — drag must never be the only way in.
- ❌ Don't rely on the row tint alone for the error state — the message + Retry carry it too.
- ❌ Don't use it for a thumbnail-first media gallery — it shows mime icons, not previews.

## Guidelines
**Let the consumer own the network.** FileUpload displays status; it doesn't upload. On `onFilesAccepted`, start your transport and update each entry's `status`/`progress` in your `files` state; wire `onRetry` to restart and `onRemove` to cancel in-flight requests.

**Constrain up front.** Set `accept`, `maxSize`, `maxFiles`, and/or `maxTotalSize`; every rejection arrives via `onFilesRejected` with a typed `errors[]` (`type` | `size` | `count` | `totalSize` | `duplicate`) so you can tell the user *why* a file didn't make it in — never drop files silently. The constraints are also surfaced to screen readers on the input.

**Keep it accessible.** The real file input is the baseline path — don't hide it or replace it with a div. Give a meaningful `label`. Convey status with the row's text + Progress, not colour alone. Use `directory` for folder drops (it degrades on Safari) and `reorderable` to let users order attachments.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no | Dropzone scale. |
| `accept` | `string` | — | no | Native accept syntax — mime types, `type/*`, and/or `.ext`, comma-separated. |
| `allowDuplicates` | `boolean` | — | no | Allow the same name+size file more than once (default de-dups). |
| `defaultFiles` | `FileUploadFile[]` | — | no | Uncontrolled initial queue (the component owns the list). |
| `directory` | `boolean` | — | no | Recurse dropped folders (`webkitdirectory`); degrades to flat files. |
| `disabled` | `boolean` | — | no | Disable the whole surface (input, drop, and row actions). |
| `files` | `FileUploadFile[]` | — | no | Controlled queue — pair with `onFilesChange`; drives real upload progress. |
| `label` | `string` | — | no | Accessible name for the file input (default "Upload files"). |
| `maxFiles` | `number` | — | no | Cap on the number of files (overflow is rejected as `count`). `1` → replace. |
| `maxSize` | `number` | — | no | Per-file byte ceiling. |
| `maxTotalSize` | `number` | — | no | Ceiling on the summed size of the whole queue. |
| `onFilesAccepted` | `(files: FileUploadFile[]) => void` | — | no | Fires with the newly accepted entries — the signal to start uploading them. |
| `onFilesChange` | `(files: FileUploadFile[]) => void` | — | no | The next queue after any add / remove / retry / reorder. |
| `onFilesRejected` | `(rejections: FileRejection[]) => void` | — | no | Fires with the files that failed validation, each carrying its reasons. |
| `onRemove` | `(file: FileUploadFile) => void` | — | no | Fires when a row is removed — cancel that file's transport if in flight. |
| `onReorder` | `(ids: string[]) => void` | — | no | Fires with the next id order after a reorder drop. |
| `onRetry` | `(file: FileUploadFile) => void` | — | no | Fires when a row's retry is pressed — restart that file's transport. |
| `reorderable` | `boolean` | — | no | Enable drag-reorder of the file list (via List's Sortable wiring). |

_Plus 279 inherited native `<div>` attributes._

### `FileUpload.Summary` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `format` | `(info: { count: number; totalBytes: number; maxFiles?: number; maxTotalBytes?: number; }) => React.ReactNode` | — | no | Override the caption; receives the live totals. |

_Plus 280 inherited native HTML attributes._

### `FileUpload.List` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | no | Manual rows; omit to auto-render one `FileUpload.Item` per queued file. |
| `renderItem` | `(file: FileUploadFile) => React.ReactNode` | — | no | Per-file row override used by the auto path. |

_Plus 294 inherited native HTML attributes._

### `FileUpload.Item` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `file` | `FileUploadFile` | — | yes | The queued file this row represents. |
| `icon` | `React.ReactNode` | — | no | Override the auto mime glyph. |

_Plus 293 inherited native HTML attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`

## State model
- `files` (controlled) / `defaultFiles` (uncontrolled), `onFilesChange` · FileUploadFile[] — The queue of `{ id, file, status, progress?, error? }`. Omit `files` for uncontrolled (the component holds the queue — a plain form field); pass it + `onFilesChange` to drive real upload status/progress.
- Selection: multiple.

## Anatomy
- `file-upload`: The container <div> that provides context (validation config + the file queue + centralized add/remove/retry/reorder). Reflects data-disabled. No ARIA role of its own.
- `file-upload-remove`: The per-row remove <button> (a labelled `Remove <name>`); deletion moves focus to the next remove button or the input.

**Parts**
- `FileUpload.Dropzone` (`file-upload-dropzone`) · required: The drop target — a <label> wrapping a focusable (never display:none) <input type=file>, so click/keyboard open the OS picker natively; drag-and-drop is enhancement. The input is named via `label` (aria-label) and described by an sr-only constraints span. Reflects data-state = idle | dragging | reject | disabled. Pass children to replace the default prompt; the input + constraints are always rendered.
- `FileUpload.Summary` (`file-upload-summary`): A running "N files · X of Y" caption derived from the queue (and `maxTotalSize`). `format` overrides the caption with the live totals.
- `FileUpload.List` (`file-upload-list`): The queued-file list — a <List appearance="divided"> wired to the queue (and to List's `reorderable`/`onReorder` when the root is reorderable). Renders nothing while empty; auto-maps the queue to FileUpload.Item rows, or takes `children`/`renderItem` to override.
- `FileUpload.Item` (`file-upload-item`): One queued-file row (a composed List.Item): mime glyph · filename · size, with an inline Progress while uploading, the error message + a Retry on failure, and a Remove button. Reflects data-file-status. `icon` overrides the auto mime glyph.

## Accessibility
- **Role:** group
- **WCAG:** 1.3.1 Info and Relationships (A); 1.4.1 Use of Color (A); 2.1.1 Keyboard (A); 2.4.3 Focus Order (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The dropzone is a <label> wrapping a real <input type=file> that is sr-only (focusable, never display:none), so click / Tab / Enter / Space open the OS picker with zero JS — drag-and-drop is progressive enhancement layered on top, never the only path in.
- The input gets a concise accessible name from `label` (aria-label, default "Upload files") and is described by an sr-only constraints span (accepted types / size / count limits) via aria-describedby, so AT users hear the rules before choosing.
- The dropzone reflects data-state = idle | dragging | reject | disabled (component state, not the `variant` axis); the visible box wears the focus ring via has-[input:focus-visible] since the input itself is sr-only.
- File events are announced through a shared live region: additions politely ("N files added."), rejections and per-file error transitions assertively — so a file appearing or vanishing from the DOM is never silent to screen-reader users.
- Each row composes List.Item, inheriting List's listitem semantics; the row's Retry (error only) and Remove are real labelled buttons (`Retry <name>` / `Remove <name>`). Removing a row moves focus to the next remove button (or the input) so deletion never drops focus to <body>.
- While uploading, the row shows a Progress (role=progressbar) — determinate with a `progress` value, indeterminate without one; disabled disables the input and every row action.
- **Focus:** The sr-only <input> is the keyboard/AT target; the visible dropzone box wears the ring via has-[input:focus-visible]. Row Retry/Remove are ordinary tab stops. On removal, focus is programmatically moved to the sibling remove button (or the input) so it never falls to <body>.

## Related
- **composes** → `utils`
- **composes** → `list` (when the queued-file list is a composed <List> of List.Item rows (inheriting its a11y + Sortable drag-reorder))
- **composes** → `progress` (when each uploading row shows an inline <Progress size="sm">)
- **composes** → `button` (when each row's Retry / Remove are ghost icon <Button>s)
- **pairsWith** → `field` (when wrapping the dropzone in a Field for a label, description, and validation message)
- **pairsWith** → `form` (when the upload is one control in a larger Form submission)
- **pairsWith** → `sonner` (when a toast confirms a completed (or failed) upload batch)
- **alternativeTo** → `input` (when you only need a single, unmanaged <input type=file> with no queue, validation, or progress)

## Recipes
- **attachment-dropzone** — A collect-files-for-a-form dropzone with type + size limits (uncontrolled). _(use when letting a user attach documents to a form without tracking upload progress)_
- **upload-with-progress** — A controlled uploader that shows per-file progress, success, and retry-on-error. _(use when uploading files to a server and showing live per-file progress)_
- **deal-docs-folder-upload** — A folder-drop intake with a running total capped by maxTotalSize. _(use when uploading a whole folder of documents with a batch size cap)_

## Gotchas
- **Expecting FileUpload to upload the files by itself (looking for an `action`/`url` prop).** — FileUpload is transport-agnostic — it owns the queue and display, never the network request. → On `onFilesAccepted`, start your own upload (fetch / XHR / presigned URL) and push each entry's `status`/`progress` back through the controlled `files` array.
- **Wanting real upload progress but passing no `files` (uncontrolled).** — Uncontrolled mode holds the queue internally at status "idle"; you can't push progress into it. → Control it: pass `files` + `onFilesChange`, then update each entry's `status`/`progress` as your transport reports.
- **Setting the native `accept` and assuming dropped files are pre-filtered.** — `accept` only hints the OS picker and is bypassed entirely by drag-and-drop. → Nothing to do — FileUpload validates `accept` itself on both paths and reports mismatches via `onFilesRejected` (reason `type`).
- **A rejected file only shows one reason when it breaks several rules.** — Each FileRejection carries an `errors[]` array, not a single reason. → Read `rejection.errors` (each `{ code, message }`) — a file can be both `type` and `size`, etc.
- **Folder drop doesn't recurse (or does nothing on Safari).** — Directory drop needs `directory` and the non-standard webkitGetAsEntry API, which Safari lacks. → Set `directory`; it recurses where supported and degrades to the flat file list where it isn't.

## Examples
- **basic** (canonical): Uncontrolled — the component holds the queue; a plain document field with accept + maxSize.
- **uploading** (edge-case): Controlled — a fake transport ticks each file to success; one is forced to fail to show the error + Retry.
- **validation** (edge-case): Typed rejections surfaced to the user — accept + per-file + count limits, every reason reported.
- **reorderable** (edge-case): Attachments the user can drag to reorder (via List's Sortable wiring).
- **directory** (edge-case): Folder drop + a running total capped by maxTotalSize, with a custom dropzone prompt.
- **disabled** (edge-case): The whole surface inert.

## Source map

Regions in `file-upload.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–25 (24 lines) — React, lucide icons, cn/announce, sibling components
- `types` L26–83 (58 lines) — overview doc + file/rejection interfaces
- `utils` L84–226 (143 lines) — id/fingerprint/format, accept matching, DataTransfer walk, FileGlyph
- `context` L227–261 (35 lines) — FileUploadContextValue + useFileUpload
- `root` L262–522 (261 lines) — FileUpload (queue state, validation, callbacks)
- `dropzone` L523–678 (156 lines) — dropzoneVariants (cva) + FileUploadDropzone
- `summary` L679–728 (50 lines) — FileUploadSummary caption
- `list` L729–778 (50 lines) — FileUploadList (composes List)
- `item` L779–904 (126 lines) — FileUploadItem (composed List.Item row)
- `exports` L905–930 (26 lines) — namespace assembly + public exports

---

# FilterBar

> An agent-native filter system — a headless `useFilters<T>` engine plus a `FilterBar` of editable `field · operator · value` pills, where the operator set is derived from each field's type so impossible queries can't be authored. Ships type-dispatched value editors, faceted counts, a rolling-vs-calendar relative-date engine, nested AND/OR groups, saved views, URL round-trip, a natural-language Ask bar, and a `FilterApi` handle an agent or MCP tool can drive.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { FilterBar } from "@garn/ui/filters"`

## Overview
Filters is garn's agent-native filter system — a headless `useFilters<T>` engine plus a `FilterBar` compound, the same shape as Sortable (an engine + a composed UI that re-skins nothing). The reliable unit is an **editable pill**: `field · operator · value`, where the operator set is a pure function of the field's `type`, so an impossible query — a comparison on an enum, `contains` on a number — simply can't be authored. Below the pills, `useFilters` owns a serializable, nestable `FilterModel` (`{ id, conjunction, rules }`, recursive), compiles it to a memoized pure `predicate` for the client (or a query object for a server seam), and round-trips through the URL with validate-and-repair so a shared link that references a since-removed field drops the stale rule instead of crashing.

On top of the pills sit the layers best-in-class products ship: **faceted counts** (count-annotated multi-selects, recomputed with the disjunctive two-query trick so OR-siblings don't zero out), a **relative-date engine** that ships rolling windows AND calendar buckets labelled distinctly (the reliability win — a rolling "past week" is 7 days; a calendar "this week" is Mon–Sun), first-class date `between`, **saved views** from an injectable store, **nested AND/OR groups** (one conjunction per group, ~3-level cap), and the 2026 headline — a natural-language **`Ask`** bar that returns *editable chips*, never a black-box answer. A `FilterApi` handle (`addRule` / `setModel` / `fromNaturalLanguage` / `toQuery` / …) is the seam an agent, an MCP tool, or the Ask parser drives.

## When to use
Letting users author a predicate over a collection: a data-table / list / board filter bar, a faceted search, a saved-segment view, or an agent/MCP surface that returns editable filter chips. Use `<FilterBar fields={…} records={…}/>` for a self-contained bar, or drive `useFilters` yourself and pass the `engine` to share one model with a table/CollectionView.

## When not to use
Plain membership toggles with no operators over a couple of columns (a simpler faceted-checkbox popover / the faceted-filter recipe is lighter — Filters is the count-annotated value editor for exactly that, but the full bar is overkill for one column). Free-text search of a list (use an Input type=search). Picking one/several values as a form field, not as a query (use Select / MultiSelect / BadgeSelect). Running an action or navigating (use Command). Sorting or reordering rows (use Sortable / the table's sort).

## Do / Don't
- ✅ Describe each column as a `FilterField` with the right `type` (text/number/date/select/multi/boolean/user) and let the operator set + value editor derive from it.
- ✅ Pass `records` (client mode) so the result count and faceted counts compute; give date fields with a status pairing a `deadline` config to unlock overdue/upcoming operators.
- ✅ Share one model with a table/CollectionView by creating the engine via `useFilters` and passing it as `engine` (read `engine.matches` / `engine.predicate`).
- ✅ Persist and share the active filter through the URL (`serialize`/`deserialize` or `useFilterUrlState`); use `SavedViews` with an injectable store for named presets.
- ✅ Drive it programmatically (agents, the Ask bar) through `apiRef` / the `FilterApi` — `addRule`, `setModel`, `fromNaturalLanguage`, `toQuery`.
- ❌ Don't hand-author a rule value the operator can't validate — an `is_within` date needs a `{ preset }` RelativeSpec, not a bare string; an invalid value renders as a (harmless) pending chip that doesn't filter.
- ❌ Don't expect a pending chip (no value yet) to affect results — it's neutral/dashed and excluded until complete; that's the intended "not live" cue.
- ❌ Don't override the chip roles to a listbox — interactive-child chips require the role=grid TagGroup pattern.
- ❌ Don't nest groups past the cap (default 3) — `Add group` grays out; escalate to a text expression (backlog) rather than ever-deeper nesting.
- ❌ Don't promise an exact live count on very large datasets — the count/facets degrade to approximate at scale.

## Guidelines
**Give it a field schema, and let type derive the rest.** Each `FilterField` is `{ id, label, type, … }` — the `type` picks the operator set and the value editor automatically. Reach for the escapes (`operators` to restrict by id, `getOperators` to derive functionally) only when the type defaults don't fit; the whole point is that impossible queries are unrepresentable.

**Two ways to wire it.** For a self-contained bar, pass `fields` (+ `records` for the live count) to `<FilterBar>` and it owns its own engine. For a data-table or CollectionView, create the engine yourself with `useFilters` and pass it via `engine`, then read `engine.matches` / `engine.predicate` to drive the rows — the bar and the table share one model.

**A pending chip doesn't filter.** A rule with no valid value renders neutral + dashed (`data-state="pending"`) and is excluded from the predicate; it earns its field tone and starts filtering only once complete. That neutral rendering is deliberate — tone means "this condition is live."

**Label rolling vs calendar dates for your users, and don't promise exact counts at scale.** The engine ships both relative families distinctly on purpose. Faceted counts are the highest-leverage feature (they prevent zero-result dead-ends) but degrade to approximate on large sets — surface that, don't imply precision.

**The URL is the source of truth for the active filter.** Use the `serialize`/`deserialize` helpers (or the optional `useFilterUrlState` hook) so a filtered view is shareable and back-button-safe; saved views are named objects that set it.

**Date rule values are `yyyy-MM-dd` calendar dates.** The date editors (and the NL parser) commit zoneless `yyyy-MM-dd` strings — the same shape the engine's own `asDate` coercion local-parses back — never UTC ISO instants, so a stored or shared filter can't drift a day across timezones. Values you inject via `addRule`/`setModel` should use the same format (a `Date` or epoch number is also accepted on input).

## Props
### `FilterBar` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `apiRef` | `React.Ref<FilterApi>` | — | no | Imperative handle (agent-native). |
| `defaultFilters` | `FilterGroup` | — | no |  |
| `engine` | `UseFiltersReturn<T>` | — | no | Adopt an externally-owned engine (data-table / CollectionView pass theirs). |
| `fields` | `FilterField<T>[]` | — | no | Field schema — required unless an `engine` is supplied. |
| `filters` | `FilterGroup` | — | no |  |
| `onFiltersChange` | `(model: FilterModel) => void` | — | no |  |
| `records` | `readonly T[]` | — | no | Records for the client pipeline (drives the result count). |
| `size` | `"md" \| "sm"` | — | no |  |

_Plus 279 inherited native HTML attributes._

### `FilterBar.Ask` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `placeholder` | `string` | — | no |  |

_Plus 307 inherited native HTML attributes._

### `FilterBar.Error` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `onRetry` | `() => void` | — | no |  |

_Plus 280 inherited native HTML attributes._

## State model
- `filters` (controlled) / `defaultFilters` (uncontrolled), `onFiltersChange` · FilterModel — Pass `filters` + `onFiltersChange` for a controlled model; `defaultFilters` for uncontrolled. The model is a recursive `{ id, conjunction, rules }` group (JSON-serializable). When you adopt an `engine`, the engine owns this pair instead.
- Selection: single.

## Anatomy
- `filter-bar`: The FilterBar provider + default layout (chips · add · result-count · clear). A flex-wrap row; reflects data-size. Creates its own engine from `fields`, or adopts one passed via `engine` (state lifted to a data-table / CollectionView).
- `filter-chips`: The pill row. `role="grid"` with a single tab stop and roving focus — chips carry interactive segment + remove buttons, so grid (not listbox) is the correct semantics (React Aria TagGroup). Switches to the nested querybuilder tree when any top-level node is a group.
- `filter-chip`: One rule as an editable pill — `field · operator · value · ✕`. Reflects data-type / data-operator / data-tone / data-appearance="soft" / data-state (complete|pending). A pending rule (no value yet) renders neutral + dashed and does not filter; it earns its field tone once complete. `role="row"` in the grid, `role="group"` standalone (inside a nested group).
- `filter-chip-operator`: The operator segment — a button opening a Command operator menu. Regular-weight + tone-colored (hierarchy by weight, not color); a caret marks word operators as editable (suppressed for symbol operators `> ≥ < ≤ = ≠`). aria-label `Operator: <label>. Change`.
- `filter-chip-value`: The value segment — opens the type-dispatched value editor popover. aria-label `Value: <summary>. Change` when set, `Set value` while pending. Hidden entirely for no-value operators (`is empty`).
- `filter-chip-remove`: The per-chip ✕ button with a descriptive name (`Remove filter: Status is Done`). In the grid it is reached by Enter-to-drill + arrows; standalone it is Tab-focusable; Backspace/Delete on the row also removes.
- `filter-value-editor`: The per-type value editor popover — Input (text), NumberField ×2 (number/between), DatePicker + relative-preset Command (date), Combobox/Select (select), count-annotated MultiSelect (multi — the folded faceted-filter recipe), Switch (boolean), avatar MultiSelect (user).
- `filter-operator-menu`: The searchable Command list of the field type's operators, with a check on the current one.
- `filter-conjunction`: The and/or selector — one per group (not per row); reflects data-conjunction. aria-label `Match all/any of the filters — change`.
- `filter-group`: A nested condition group rendered as a group-outline box (`role="group"`), with its own conjunction, add-rule/add-group controls, and a remove-group button. Depth is capped (default 3) — `filter-add-group` grays out at the cap.
- `filter-add`: The `+ Filter` trigger → a searchable Command field menu (`filter-field-menu`) → operator → value. Typing a field name skips category navigation.
- `filter-result-count`: The live result count (`role="status"`, aria-live=polite) — announced as filters change; renders only in client mode (with `records`).
- `filter-clear`: The reset-all button (the two-tier clear's second tier; the first is each chip's ✕).
- `filter-saved-views`: Name / switch / delete filter presets from an injectable store (localStorage default via createLocalViewStore, swappable to a consumer store).
- `filter-ask`: The natural-language bar — a phrase parses (deterministic default, or the injected `parseQuery` LLM/MCP seam) into editable chips, never a black-box answer. A misparse is still an editable chip.
- `filter-empty`: First-class empty state (no filters / no matches).
- `filter-loading`: First-class loading state (async option/count fetch); `role="status"`, keep-previous so there is no empty flash.
- `filter-error`: First-class error state (`role="alert"`) with an optional retry button, for a failed option/count fetch.

**Parts**
- `FilterBar` (`filter-bar`) · required: The root provider + default layout. Pass `fields` (+ optional `records`) and it creates its own engine, or adopt an externally-owned one via `engine`; `apiRef` exposes the FilterApi. With no compound children it renders the canonical bar; pass children to arrange the parts yourself.
- `FilterBar.Chips` (`filter-chips`): The pill row (flat roving grid, or the nested querybuilder tree when a group is present).
- `FilterBar.Add` (`filter-add`): The `+ Filter` field-menu trigger.
- `FilterBar.ResultCount` (`filter-result-count`): The `role="status"` live result count (client mode).
- `FilterBar.Clear` (`filter-clear`): The reset-all button.
- `FilterBar.SavedViews` (`filter-saved-views`): Named filter presets from an injectable `store` (createLocalViewStore default).
- `FilterBar.Ask` (`filter-ask`): The natural-language bar → editable chips.
- `FilterBar.Empty` (`filter-empty`): The empty state.
- `FilterBar.Loading` (`filter-loading`): The loading state (keep-previous).
- `FilterBar.Error` (`filter-error`): The error state (`role="alert"`) with an optional `onRetry`.

## Accessibility
- **Role:** grid (APG: Grid (editable chips) + Combobox/Listbox (authoring) + Status message (result count))
- **ArrowLeft / ArrowRight / ArrowUp / ArrowDown:** On a chip row: rove to the previous/next chip. On a segment: move to the previous/next segment within the chip.
- **Home / End:** Focus the first / last chip in the row.
- **Enter / Space:** On a chip row: drill in — focus the operator segment. On a segment: open its menu/editor.
- **Escape:** From a segment: exit back to the chip row (or close an open menu/editor).
- **Backspace / Delete:** On a chip row: remove that filter and move focus to its neighbour.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A); 4.1.3 Status Messages (AA)
- The chip row is `role="grid"` with `aria-label="Active filters"`, a single tab stop, and roving focus — because each chip carries interactive segment + remove buttons, grid is the correct semantics (a listbox is wrong for interactive-child chips; this is the React Aria TagGroup pattern). Each chip is a `role="row"`; its field/operator/value/remove segments are `role="gridcell"`.
- Keyboard model on the flat bar: arrows rove between chips (Home/End jump); Enter/Space drills into a chip (focus its operator segment); arrows then move between segments and Escape exits back to the row; Backspace/Delete removes the focused chip and moves focus to its neighbour. Standalone chips inside a nested group are `role="group"` and their buttons are directly Tab-focusable.
- Every interactive segment has a descriptive accessible name: the operator button `Operator: <label>. Change`, the value button `Value: <summary>. Change` (or `Set value` while pending), the remove button `Remove filter: <field> <operator> <value>`, the conjunction `Match all/any of the filters — change`.
- The result count is a `role="status"` aria-live=polite region so screen readers hear the match count update as filters change; the loading state is also role=status (keep-previous, no empty flash) and the error state is role=alert with a labelled retry.
- Authoring surfaces (the `+ Filter` field menu, the operator menu, select/multi/user/relative-date value editors) are Command comboboxes/listboxes with a text filter, following the WAI-ARIA combobox pattern; the natural-language Ask input has aria-label `Ask in natural language` and announces `Filters updated` on parse.
- **Focus:** The chip grid holds one roving tab stop; the active chip carries tabIndex 0 and self-heals when chips are added/removed (focus lands on the removed chip's neighbour). Segment buttons are tabIndex -1 in the grid (reached by drill + arrows) and Tab-focusable standalone. Don't strip the focus rings.
- **Contract (error):** Chips carrying interactive controls must be a `role="grid"` with roving tabindex (row + gridcell segments), NOT a listbox — the React Aria TagGroup pattern. FilterBar.Chips does this; don't override the roles. — _when the chip row renders editable pills with remove/segment buttons_
- **Contract (error):** Removing a chip must move focus to its neighbour (never lose focus to the body), so keyboard users stay in the bar. — _when a chip is removed via Backspace/Delete or the ✕ button_
- **Contract (error):** The operator, value, and remove segments each need a descriptive accessible name that includes the field/value context (not a bare "button" or icon-only ✕). — _when any chip is rendered_
- **Contract (warn):** The result count must be a `role="status"` (aria-live=polite) live region so the match count is announced as filters change. — _when the live result count is shown_

## Tokens
- `gap` → `--garn-gap-inline` (air)
- **Internal (never externalize):** `--t-soft-fg`, `--t-line`

## Related
- **composes** → `utils`
- **composes** → `use-controllable-state` (when the FilterModel is controlled/uncontrolled)
- **composes** → `use-announce` (when the Ask bar announces parse results to a polite live region)
- **composes** → `use-debounced-value` (when async option/count fetch is debounced (with abort + response-keying + keep-previous))
- **composes** → `tag` (when each chip reuses tag's `tagVariants` look (paste-literal, per-field tone, appearance soft))
- **composes** → `popover` (when the operator/value segment editors and menus open in popovers)
- **composes** → `command` (when the field menu, operator menu, and searchable value editors are Command lists)
- **composes** → `input` (when the text value editor)
- **composes** → `number-field` (when the number value editor (×2 for `between`))
- **composes** → `date-picker` (when the date value editor (point / range))
- **composes** → `switch` (when the boolean value editor)
- **composes** → `spinner` (when the async loading affordance in a value editor)
- **composes** → `multi-select` (when the multi/user value editor — the count-annotated, faceted variant (the folded faceted-filter recipe))
- **pairsWith** → `table` (when a data-table shares the engine (`useFilters` → `engine.matches` drives rows) and mounts FilterBar above it)
- **pairsWith** → `badge-select` (when a compact single/multi value editor for enum fields)
- **alternativeTo** → `multi-select` (when you only need to pick tags/values as a form field, with no operators or a shared query model)
- **alternativeTo** → `input` (when you only need free-text search of a list (type=search), not a structured predicate)

## Recipes
- **data-table-filter-bar** — A filter bar wired to a data table — one `useFilters` engine drives both the chips and the rows. _(use when letting users filter the rows of a table/list by any column)_
- **faceted-value-editor** — The count-annotated multi-select value editor — `label (count)`, selected-first, recomputed against the current set (disjunctive two-query so OR-siblings don't zero out). The faceted-filter recipe, folded in. _(use when picking several enum values with live counts that prevent zero-result dead-ends)_
- **natural-language-ask** — A natural-language bar that parses a phrase into editable chips (deterministic default parser, or an injected LLM/MCP `parseQuery`), never a black-box answer. _(use when letting users (or an agent) express a filter in words and correct the result)_
- **saved-filter-views** — Named filter presets (personal/shared) from an injectable store — a saved view sets the active model, which the URL still owns. _(use when saving and switching between named filter configurations)_
- **nested-and-or-groups** — Nested AND/OR condition groups — one conjunction per group, ~3-level cap, group-outline box — for queries the flat AND bar can't express. _(use when mixing AND and OR logic (e.g. amount > X AND (stage = A OR stage = B)))_

## Gotchas
- **FilterBar renders nothing / throws — no chips, no add button.** — Neither `fields` nor `engine` was supplied, so the bar has no schema to build from. → Pass `fields={[…]}` (the bar creates its own engine) OR pass an `engine` you made with `useFilters(fields, opts)`. `records` is additionally needed for the live result count / facets.
- **A chip stays gray/dashed and doesn't affect the results.** — The rule is `pending` — it has no valid value yet (e.g. an `is_within` date without a `{ preset }`), so it's excluded from the predicate and rendered neutral by design. → Set a valid value for the operator's arity (a scalar for `is`, a `{ preset }` RelativeSpec for `is_within`, an array for `is_any_of`). It turns tone-colored and starts filtering once `isRuleComplete` passes.
- **A chip icon (the field glyph, the caret, or the ✕) renders at 16px no matter what `size-*` I set.** — The chip reuses tag's `tagVariants`, whose `size` variant sets `[&_svg]:size-4` ON the chip — a descendant rule that forces every chip icon to 16px and wins same-specificity ties on source order. → Use Tailwind `!important` on the per-icon size (`!size-3.5`, etc.), per garn convention (cf. calendar.tsx). Without the `!` it's a silent no-op.
- **A relative-date filter returns different rows than the user expected (off by a few days at week/month boundaries).** — Rolling windows (`past_week` = rolling 7 days) and calendar buckets (`this_week` = calendar Mon–Sun) are different presets — picking the wrong family is the classic reliability trap. → Choose the labelled family deliberately: the rolling presets (last/next N days, past week/month/year) vs the calendar ones (this/last/next week/month/quarter/year, labelled "(calendar)"). Both ship on purpose.
- **The filter model won't change / the chips are frozen.** — `filters` was passed without `onFiltersChange`, making the model read-only (controlled with no writer). → Pass both `filters` + `onFiltersChange` for controlled, or `defaultFilters` for uncontrolled. When adopting an `engine`, let the engine own the pair.
- **The result count doesn't render, or reads 0 when rows clearly match.** — The count/facets are client-mode only — they need `records` (or an `engine` created with `records`). Without records the engine has nothing to evaluate. → Pass `records={data}` to `<FilterBar>` or to `useFilters(fields, { records })`. On very large sets, treat the count as approximate.
- **The `Ask` bar returns an answer/blob instead of chips, or I can't customize its parsing.** — Expecting a black-box NL answer; the doctrine is "AI returns a query, not an answer" — it always emits editable chips via the engine's `parseQuery`. → Rely on the deterministic default parser, or inject `parseQuery` (the LLM/MCP seam) in `useFilters` opts — constrain the model to the JSON-Schema FilterModel so it can only emit valid rules, which render as correctable chips.

## Examples
- **basic** (canonical): A self-contained FilterBar over a records array — `+ Filter` → field → operator → value, keyboard-operable chips.
- **prefilled** (canonical): A controlled model seeded with rules — the editable-pill state, per-segment editing.
- **live-results** (edge-case): The engine's `predicate` wired to a live result list (`engine.matches`).
- **full-matrix** (edge-case): Every field type (text/number/date/select/multi/user) with its operators + value editor, incl. relative dates and deadline mode.
- **nested-groups** (edge-case): Nested AND/OR groups — the group-outline querybuilder tree with one conjunction per group.
- **ask** (edge-case): The natural-language Ask bar parsing a phrase into editable chips (custom layout via compound children).
- **saved-views** (edge-case): Saved filter views from a localStorage store (createLocalViewStore).
- **url-round-trip** (edge-case): serialize/deserialize round-trip through a URL query string, with validate-and-repair on restore.

## Source map

Regions in `filters.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `types` L53–185 (133 lines) — the model + field schema (JSON-serializable from day one)
- `operators` L187–846 (660 lines) — the type→operators registry (Slice 1: text + select)
- `model` L848–976 (129 lines) — recursive helpers + validity
- `predicate` L978–1013 (36 lines) — compile the model to a pure (T) => boolean
- `serialize` L1015–1109 (95 lines) — URL contract with validate-and-repair
- `parse` L1111–1335 (225 lines) — natural language → editable chips (deterministic default)
- `use-filters` L1337–1586 (250 lines) — the engine hook + FilterApi handle
- `context` L1588–1604 (17 lines) — FilterBar provider
- `root` L1606–1683 (78 lines) — FilterBar.Root
- `chips` L1685–2141 (457 lines) — FilterBar.Chips + FilterBar.Chip (the editable pill)
- `groups` L2143–2290 (148 lines) — nested and/or groups (querybuilder tree)
- `editors` L2292–2704 (413 lines) — type-dispatched value editors (Slice 1: text + select)
- `add` L2706–2850 (145 lines) — FilterBar.Add ("+ Filter" → field menu)
- `saved-views` L2852–3018 (167 lines) — named presets (injectable store)
- `ask` L3020–3079 (60 lines) — natural-language input → editable chips
- `status-parts` L3081–3186 (106 lines) — ResultCount + Clear
- `helpers` L3188–3256 (69 lines) — labels + value summaries
- `exports` L3258–3296 (39 lines)

---

# Form

> React Hook Form scaffolding that wires labels, controls, descriptions, and validation messages.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Form } from "@garn/ui/form"`
- **Polymorphism:** `asChild`

## Overview
Form is the accessible wiring layer over React Hook Form: it ties each field's label, control, description, and error message together so the ARIA plumbing is correct by default. `Form` is the RHF provider, `FormField` binds a name via Controller, and within a `FormItem` the `FormLabel` / `FormControl` / `FormDescription` / `FormMessage` parts share one id set — `FormControl` injects `id` + `aria-describedby` + `aria-invalid` onto your control. Use it for any real form; a single uncontrolled field doesn't need the machinery.

## When to use
Build accessible forms with React Hook Form — consistent label / control / description / error wiring out of the box.

## When not to use
A single, simple field with no validation (just use the control + a Label); a form not using react-hook-form.

## Do / Don't
- ✅ Wrap fields in FormField (control + name) and render the control inside FormControl.
- ✅ Put one FormItem per field so the label/control/message ids stay linked.
- ✅ Let FormMessage render the error — it pulls from RHF field state automatically.
- ❌ Don't hand-wire aria-describedby/aria-invalid — FormControl does it.
- ❌ Don't call useFormField outside a FormField — it throws.

## Guidelines
**Wrap each field in FormField + FormItem.** That's what generates the shared id and links label↔control↔description↔error; reaching past it to hand-wire `htmlFor`/`aria-*` reintroduces the bugs Form exists to prevent. Put your control inside `FormControl` so the a11y attributes land on it.

**Validate with a schema and surface errors inline.** Drive RHF with a resolver (Zod/Yup) so `FormMessage` renders the real validation message beside the field and `aria-invalid` styles it; show errors on submit/blur, not on every keystroke. Keep one clear message per field.

**Write helpful labels and descriptions.** Use `FormDescription` for format hints and requirements rather than cramming them into the label or a placeholder, mark optional fields explicitly, and keep the submit action's state honest (disable/spinner while pending).

## Anatomy

**Parts**
- `Form` · required: = RHF FormProvider. Spread your `useForm()` return into it.
- `FormField` · required: Binds a field by `name` to a control via RHF's Controller (render-prop).
- `FormItem` (`form-item`) · required: One field's row; provides the id that ties label/control/message together.
- `FormLabel` (`form-label`): Label wired to the control (htmlFor), turns destructive on error.
- `FormControl` (`form-control`) · required: Slot that injects id + aria-describedby + aria-invalid onto your control.
- `FormDescription` (`form-description`): Helper text, linked via aria-describedby.
- `FormMessage` (`form-message`): Validation error, linked via aria-describedby; renders nothing when valid.

## Accessibility
- **Role:** form
- **WCAG:** 1.3.1 Info and Relationships (A); 3.3.1 Error Identification (A); 3.3.2 Labels or Instructions (A); 4.1.2 Name, Role, Value (A)
- FormControl auto-wires id + aria-describedby (description + message) + aria-invalid onto the control.
- FormLabel's htmlFor targets the control; FormMessage announces the validation error.

## Tokens
- `fieldGap` → `--garn-gap-field` (air)

## Related
- **composes** → `utils`
- **composes** → `label`
- **pairsWith** → `input`
- **pairsWith** → `textarea`
- **pairsWith** → `select`
- **pairsWith** → `checkbox`
- **pairsWith** → `radio-group`
- **pairsWith** → `button` (when as the submit action)

## Recipes
- **validated-field** — A labeled, described, validated field bound to React Hook Form. _(use when a form needs validation + accessible error messaging)_

## Gotchas
- **`useFormField should be used within <FormField>` thrown at runtime.** — A Form* part rendered outside a FormField/FormItem. → Wrap each field's parts in FormField → FormItem.
- **The field doesn't track input or validate.** — The control isn't wired to RHF. → Render the control inside FormControl and spread the Controller `field` onto it.

## Examples
- **basic** (canonical): A single RHF-bound, labeled field with description + submit.

---

# Gallery

> A masonry / justified / uniform thumbnail grid — a real layout engine plus a zero-CLS lazy-media pipeline, a view-agnostic multi-select model (click · shift-range · marquee · keyboard), a built-in lightbox, FLIP re-layout motion, drag-reorder, and windowed virtualization for large asset libraries.

- **Status:** beta
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Gallery } from "@garn/ui/gallery"`

## Overview
Gallery renders a large, heterogeneous set of visual records — DAM assets, product shots, moodboard pins — as a real layout engine, not a `<div>` of cards. One `layout` axis wears three looks: `uniform` (an aspect-cropped auto-fill grid), `masonry` (column-packed variable heights, reaching for the native `grid-template-rows: masonry` on Safari 26+ and a DOM-order-preserving computed-span fallback everywhere else), and `justified` (Flickr / Google-Photos row-fill). It is data-driven — pass `items` (+ an optional `renderItem`) rather than composing tiles by hand — because the packing math needs each tile's aspect ratio up front, which is what lets it justify and pack without a measure-render-remeasure thrash. Every tile reserves its aspect box (zero CLS), lazy-loads with a blur-up placeholder, and skeletons while pending.

## When to use
Displaying a large set of images / thumbnails where the visuals ARE the content: a DAM / asset library, a photo stream, an e-commerce product grid, a Pinterest-style moodboard, a portfolio. Use masonry for variable-height pins, justified for a photo stream that fills each row, uniform for a cropped contact sheet. Add selection for batch ops, a lightbox to inspect, reorder to curate, virtualization to scale.

## When not to use
A single-row horizontal scroller (use Carousel). Records better scanned as sortable rows of fields than as tiles (use Table / List / Data-list). One image with a fixed ratio (use Aspect-ratio + a plain <img>). A calendar heatmap of activity (use Activity-grid). Grouping/faceting or a bulk-action bar above the grid — those belong in the CollectionView layer, not the Gallery.

## Do / Don't
- ✅ Give each item `width`/`height` (or `aspectRatio`) so masonry/justified pack with zero layout shift.
- ✅ Name the gallery with `aria-label` / `aria-labelledby` (required for a selectable listbox).
- ✅ Control selection with `selectedIds`/`onSelectionChange` (view-agnostic ids), and pick `single` vs `multiple`.
- ✅ Compose `Gallery.Media` + `Gallery.Overlay` inside `renderItem`; keep Root's tile cell.
- ✅ Use `lightbox` for the built-in viewer, or drive `Gallery.Lightbox` from your own `onActivate`.
- ✅ Choose `reorderable` OR `virtualized` — not both; virtualize the big libraries, reorder the small moodboards.
- ❌ Don't replace or restyle the tile cell's `role`/`data-slot` — it carries selection, keyboard, drag, and FLIP; put custom content inside `renderItem` instead.
- ❌ Don't skip item dimensions for masonry/justified — without an aspect the layout can't reserve the box and tiles repack when images load.
- ❌ Don't set both `reorderable` and `virtualized` — windowing unmounts off-screen tiles that a drag can't reach (virtualized wins, reorder is dropped).
- ❌ Don't use Gallery for a single-row scroller (Carousel) or a field table (Table) — it's for a packed 2D grid of visuals.
- ❌ Don't strip the focus ring or silence the reduced-motion gating.

## Guidelines
**Give items their aspect ratios.** Provide `width`/`height` (or `aspectRatio`) on each record so masonry and justified pack correctly on the first paint with no reflow when images load. `uniform` crops to a single `aspectRatio` and doesn't need per-item ratios.

**Selection is a view-agnostic `Set<id>`.** Turn it on with `selectionMode` and control it with `selectedIds`/`onSelectionChange`. Because it's ids (not indices), the selection survives a filter, a reorder, or a CollectionView view switch. `multiple` gives you click · ⇧-range · ⌘/Ctrl-toggle · marquee drag · ⌘/Ctrl+A · a full roving-tabindex keyboard.

**Compose inside `renderItem`, don't replace the cell.** Root wraps your content in the tile cell that carries selection, keyboard, drag, and FLIP. Put `Gallery.Media` + `Gallery.Overlay` inside `renderItem`; never restyle the cell's role/`data-slot`.

**Reach for the built-ins.** `lightbox` for a batteries-included viewer (or drive the exported `Gallery.Lightbox` from your own `onActivate`); `reorderable` to curate a moodboard; `virtualized` for a huge DAM. `reorderable` and `virtualized` are mutually exclusive (windowing unmounts the tiles a drag needs) — pick one. Always give the gallery an `aria-label`.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `layout` | `"justified" \| "masonry" \| "uniform"` | `uniform` | no | The layout engine — the structural axis (reflected `data-layout`). |
| `selectionMode` | `"multiple" \| "none" \| "single"` | `none` | no | Enable selection. `none` (default) keeps the read-only `role="list"`; `single`/`multiple` fork it to a selectable `role="listbox"`. |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no | Tile density (reserved for per-size tuning; currently sets `data-size`). |
| `animate` | `boolean` | — | no | Animate tiles between positions (FLIP) when the set reorders/filters. Default true; always disabled under `prefers-reduced-motion`. |
| `aspectRatio` | `number` | — | no | Crop ratio for `uniform` tiles (w ÷ h). Default 1 (square). |
| `columns` | `number` | — | no | Fixed column count (uniform · masonry). Omit to auto-fill by `minTileWidth`. |
| `defaultSelectedIds` | `readonly GalleryItemId[]` | — | no | Uncontrolled initial selection. |
| `empty` | `React.ReactNode` | — | no | Rendered when `items` is empty. |
| `gap` | `"lg" \| "md" \| "sm"` | — | no | Gutter between tiles — maps to the `--garn-gallery-gap-*` tokens. |
| `items` | `readonly T[]` | — | yes | The records to render. Their `aspectRatio` (or width/height) drives packing. |
| `lightbox` | `boolean` | — | no | Open a built-in lightbox (composed Dialog + Carousel) on activation. |
| `minTileWidth` | `number` | — | no | Auto-fill floor when `columns` is unset (px). Default: token `min-tile` (240). |
| `onActivate` | `(item: T, ctx: { index: number; }) => void` | — | no | Activate a tile (Enter / double-click, or single click when not selectable). |
| `onReorder` | `(items: T[]) => void` | — | no | Fires with the next item order after a reorder. |
| `onSelectionChange` | `(ids: GalleryItemId[]) => void` | — | no | Fires with the full selected-id list on every selection change. |
| `overscan` | `number` | — | no | Extra px rendered above/below the viewport in `virtualized`. Default 400. |
| `renderItem` | `(item: T, ctx: { index: number; layout: GalleryLayout; }) => React.ReactNode` | — | no | Render a tile's content. Defaults to a lazy `Gallery.Media` from the item. |
| `renderSlide` | `(item: T, ctx: { index: number; }) => React.ReactNode` | — | no | Render a lightbox slide. Default: the item's full image, letterboxed. |
| `reorderable` | `boolean` | — | no | Enable drag-to-reorder (composes the `sortable` primitive: pointer + keyboard + touch long-press + announcements). Each tile grows a grip. |
| `selectedIds` | `readonly GalleryItemId[]` | — | no | Controlled selection — the ids of selected records (view-agnostic). |
| `targetRowHeight` | `number` | — | no | Target row height for `justified` (px). Default: token `row-height` (224). |
| `virtualHeight` | `number` | — | no | The scroll-viewport height (px) for `virtualized`. Default 640. |
| `virtualized` | `boolean` | — | no | Window the render: compute an absolute layout and mount only the tiles near the viewport. Requires a scrollable height (`virtualHeight` or a CSS height). Trades native CSS masonry for a JS packing model. Wins over `reorderable` (windowing unmounts off-screen tiles, which drag can't reach). |

_Plus 279 inherited native `<div>` attributes._

### `Gallery.Media` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `alt` | `string` | — | no |  |
| `aspectRatio` | `number` | — | no | Own aspect box (w ÷ h) when used standalone, outside a Gallery.Item. |
| `blurDataURL` | `string` | — | no | Tiny blurred data-URI for `placeholder="blur"`. |
| `fallback` | `React.ReactNode` | — | no | Rendered in place of a broken image. Default: a muted broken-image glyph. |
| `fit` | `"contain" \| "cover"` | — | no | `cover` (default) crops to fill; `contain` letterboxes. |
| `loading` | `"eager" \| "lazy"` | — | no | `lazy` (default) defers load until near the viewport; `eager` loads now. |
| `placeholder` | `"blur" \| "none" \| "skeleton"` | — | no | Placeholder while loading: blur-up LQIP, a shimmer skeleton, or none. |
| `src` | `string` | — | no |  |

_Plus 287 inherited native HTML attributes._

### `Gallery.Overlay` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `position` | `"bottom" \| "top"` | — | no | Which edge the scrim sits on. |

_Plus 280 inherited native HTML attributes._

### `Gallery.Lightbox` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `index` | `number` | — | yes | The open slide index; `null` closes the lightbox (controlled). |
| `items` | `readonly T[]` | — | yes |  |
| `label` | `string` | — | no | Accessible name for the viewer. |
| `onIndexChange` | `(index: number \| null) => void` | — | no |  |
| `renderSlide` | `(item: T, ctx: { index: number; }) => React.ReactNode` | — | no | Render a slide. Default: the item's full image, letterboxed. |

## Variants
- **layout** (default `uniform`): `uniform`, `masonry`, `justified`
- **size** (default `md`): `sm`, `md`, `lg`
- **selectionMode** (default `none`): `none`, `single`, `multiple`

## State model
- `selectedIds` (controlled) / `defaultSelectedIds` (uncontrolled), `onSelectionChange` · (string | number)[] — The selected record ids — a view-agnostic Set<id> (not indices), so selection survives a filter, reorder, or a CollectionView view switch.
- Selection: multiple.

## Anatomy
- `gallery`: The grid container. Reflects `data-layout`, `data-size`, and `data-reorderable` / `data-dragging`. Its role adapts to the interaction model: `role=list` (read-only), `role=listbox` + `aria-multiselectable` (selectable), or `role=group` (activatable-only). Named via aria-label / aria-labelledby.
- `gallery-item`: One positioned tile, rendered by Root around each record (or your `renderItem`). Reserves its own box (aspect-ratio / width-height / masonry span / absolute box) so media loads with zero layout shift. Its role tracks the container: `listitem` (static), `option` + roving tabindex + `aria-selected` (selectable), or `button` (activatable-only). Carries `data-selected` / `data-active` / drag data-attrs.
- `gallery-media`: The lazy image (Gallery.Media). Reserves its aspect box, holds a blur/skeleton placeholder until decode, fades the image in, and swaps to a fallback on error. Reflects `data-status` (idle / loaded / error).
- `gallery-media-fallback`: The broken-image state inside a media slot — a muted glyph by default, overridable via `fallback`.
- `gallery-overlay`: A hover/selected scrim (Gallery.Overlay) for tile metadata (title, meta). Pointer-transparent so it never blocks selection; appears on hover / focus / selected.
- `gallery-check`: The auto selection affordance on a selectable tile — a check circle, decorative (`aria-hidden`; the option's `aria-selected` is the source of truth), visible on hover or when selected.
- `handle`: The drag grip on a `reorderable` tile — a real button (its name + keyboard come from the sortable primitive), visible on hover.
- `gallery-marquee`: The rubber-band selection rectangle drawn while dragging across empty space (token-styled, `aria-hidden`).
- `gallery-viewport`: The full-height absolute-positioned spacer in `virtualized` mode; only tiles near the scroll window are mounted inside it.
- `gallery-empty`: Wraps the `empty` node shown when there are no items.
- `gallery-lightbox`: The full-screen viewer's DialogContent (Gallery.Lightbox) — a letterboxed Carousel with prev/next, ←/→ paging, Esc-to-close, and an sr-only title.
- `gallery-lightbox-counter`: The '3 / 12' slide counter at the foot of the lightbox.

**Parts**
- `Gallery` (`gallery`) · required: Root + engine (generic over the item type — extend `GalleryItemData` with your own fields). Owns the layout math, the view-agnostic selection model, the roving-tabindex keyboard, FLIP motion, the drag machine (via useSortable), the virtualizer, and the built-in lightbox. Data-driven: pass `items` + optional `renderItem`.
- `Gallery.Media` (`gallery-media`): The lazy image part used by the default tile and available inside a custom `renderItem`. Zero-CLS: reserves the aspect box, defers load until near the viewport (IntersectionObserver + native `loading=lazy`), shows a blur-up LQIP or skeleton, and falls back to a broken-image glyph on error.
- `Gallery.Overlay` (`gallery-overlay`): A hover/selected scrim slot for tile metadata — place it inside a `renderItem`. Pointer-transparent (never blocks selection); `position` puts the gradient on the top or bottom edge.
- `Gallery.Lightbox` (`gallery-lightbox`): The controlled full-screen viewer (Dialog + Carousel) — driven by `index` (null = closed). Gallery renders it internally for the `lightbox` prop, but it's exported so you can open it from your own `onActivate`.

## Accessibility
- **Role:** list (read-only) · listbox + option (selectable) · group + button (activatable-only) (APG: Listbox (rowless multi-select) / Grid)
- **ArrowLeft / ArrowRight:** Move the active tile one step in DOM (reading) order.
- **ArrowUp / ArrowDown:** Move to the nearest tile above / below by center geometry (layout-aware).
- **Home / End:** Move to the first / last tile.
- **Space:** Toggle selection of the active tile (multiple) / select it (single); activate it when the gallery is activatable-only.
- **Shift / ArrowUp / ArrowDown / ArrowLeft / ArrowRight:** Extend the selection from the range anchor to the moved tile (multiple).
- **Meta / Control / a:** Select all tiles (⌘/Ctrl+A, multiple).
- **Enter:** Activate the active tile (open the lightbox / fire onActivate); otherwise select it.
- **Escape:** Clear the selection (or close the lightbox when it's open).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.3 Focus Order (A); 2.4.7 Focus Visible (AA); 2.5.7 Dragging Movements (AA); 4.1.2 Name, Role, Value (A)
- The container's role tracks the interaction model: read-only it is a `role=list` of `role=listitem` tiles; `selectionMode` forks it to a `role=listbox` of `role=option` tiles with `aria-selected` (and `aria-multiselectable` in `multiple`); an activatable-only gallery (lightbox / onActivate without selection) is a `role=group` of focusable `role=button` tiles. Masonry / justified have no honest rows, so a rowless listbox is used rather than a dishonest `role=grid` with fake `role=row` wrappers.
- Roving tabindex: exactly one tile is the tab stop (`tabindex=0`, `data-active`); the arrows move focus. Left/right walk DOM (reading) order; up/down pick the nearest tile by center geometry (from the absolute model when virtualized, so navigation works over unmounted tiles). Home/End jump to the first/last. Focus is resolved by stable `data-gallery-id`, not array position.
- The auto selection check is decorative (`aria-hidden`) — the option's `aria-selected` is the single source of truth, so no nested control is introduced inside the listbox option. The marquee rectangle is `aria-hidden`.
- A gallery with items must be named (`aria-label` / `aria-labelledby`) — required for the selectable listbox, good practice always; a dev warning fires when it's missing.
- The lightbox is a Dialog (scrim, focus trap, Esc-to-close, an sr-only title '{label} — n of N') wrapping a Carousel; prev/next controls and ←/→ page the slides, and a counter announces position.
- Media is zero-CLS: every tile reserves its aspect box before load, so nothing shifts. Motion (FLIP glide, hover zoom, placeholder fades) is disabled under `prefers-reduced-motion`.
- **Focus:** Roving tabindex — one tile carries `tabindex=0`, the rest `-1`; arrows move focus (and it) between tiles. Focus resolves by stable `data-gallery-id`. In `virtualized` the active tile is kept mounted even when scrolled out so the tab stop never vanishes. Don't strip the focus ring.
- **Contract (warn):** Provide an accessible name via `aria-label` or `aria-labelledby` — required for the selectable listbox, recommended always. — _when the gallery has items_

## Tokens
- `gap` → `--garn-gallery-gap-md` (air)
- `tileRadius` → `--garn-gallery-radius`
- `minTileWidth` → `--garn-gallery-min-tile` (identity)
- `rowHeight` → `--garn-gallery-row-height` (identity)
- `rowUnit` → `--garn-gallery-row-unit`
- `placeholder` → `--garn-gallery-placeholder`
- `selectionRing` → `--garn-brand-solid` · brandable

## Related
- **composes** → `dialog` (when the built-in lightbox is a Dialog (scrim, focus trap, Esc, sr-only title))
- **composes** → `carousel` (when the lightbox pages slides with a Carousel (←/→, loop, counter))
- **composes** → `sortable` (when `reorderable` drives tile drag-reorder through the useSortable hook (grip handle, keyboard, touch))
- **pairsWith** → `badge` (when a tile's Gallery.Overlay carries a status / type badge)
- **pairsWith** → `empty` (when the `empty` state renders when there are no items)
- **alternativeTo** → `carousel` (when you want a single-row horizontal scroller instead of a packed multi-row grid)
- **alternativeTo** → `table` (when the records are better scanned as sortable rows of fields than as visual tiles)
- **alternativeTo** → `activity-grid` (when you're plotting a calendar heatmap of activity, not a grid of images)

## Recipes
- **image-gallery** — A masonry / justified / uniform grid of thumbnails with zero-CLS lazy media — the base renderer for a DAM, photo stream, or product grid. _(use when displaying a large set of images or thumbnails in a packed 2D grid)_
- **selectable-gallery** — A batch-selectable asset library — click · shift-range · ⌘/Ctrl-toggle · marquee drag · keyboard, over a view-agnostic id set. _(use when batch-selecting assets in a DAM / photo library)_
- **gallery-lightbox** — Activate a tile to open a full-screen viewer with prev/next paging — a Dialog wrapping a Carousel. _(use when opening a full-screen image viewer when a tile is activated)_
- **reorderable-gallery** — A drag-to-reorder moodboard — tiles reorder by pointer, keyboard, or touch via the sortable primitive. _(use when letting users curate / reorder tiles by drag)_

## Gotchas
- **Masonry / justified tiles jump or repack after the images finish loading.** — The layout math needs each item's aspect ratio up front; without `width`/`height` (or `aspectRatio`) it can't reserve the box, so it repacks once images report their natural size. → Give every record `width` + `height` (or an explicit `aspectRatio`). `uniform` is exempt — it crops to the single `aspectRatio` prop.
- **Setting both `reorderable` and `virtualized` doesn't let tiles drag (and a console warning fires).** — Windowing unmounts off-screen tiles, which a drag can't reach — the two modes are mutually exclusive and virtualized wins. → Pick one: `reorderable` for a full-DOM moodboard, `virtualized` for a huge library. Don't set both.
- **Selection, keyboard, drag, or FLIP breaks when I customize a tile.** — Root wraps each `renderItem` in the tile cell (the option/listitem role, selection check, drag handle, `data-gallery-id`). Replacing or restyling that cell's role/`data-slot` strips the machinery. → Put custom content INSIDE `renderItem` — compose `Gallery.Media` + `Gallery.Overlay`. Don't render your own `Gallery.Item` wrapper or override its role/data-slot.
- **A console warning asks for an accessible name.** — A gallery with items has no `aria-label` / `aria-labelledby`; a selectable listbox requires a name. → Pass `aria-label` (or `aria-labelledby`) to the Gallery.
- **Masonry looks different across browsers.** — `grid-template-rows: masonry` is native only on Safari 26+; elsewhere Gallery falls back to a computed `grid-row-end: span` (still DOM-order preserving). → This is expected progressive enhancement — both paths pack correctly, no action needed. It gets better as browsers ship the native primitive.
- **`onActivate` and the built-in `lightbox` — which opens the viewer?** — `lightbox` opens the built-in Dialog + Carousel viewer on activation; `onActivate` is your own hook. They compose — with both set, `onActivate` fires AND the lightbox opens. → Set `lightbox` for the batteries-included viewer, or leave it off and drive the exported `Gallery.Lightbox` (controlled by `index`) from your `onActivate` for full control.

## Examples
- **masonry** (canonical): Column-packed variable heights (Pinterest) — native `grid-template-rows: masonry` on Safari 26+, a DOM-order computed-span fallback elsewhere.
- **justified** (canonical): Flickr / Google-Photos row-fill — each row scales to exactly fill the container width; the last row is left-aligned.
- **uniform** (canonical): An aspect-cropped auto-fill grid (DAM / Instagram) — the cheapest, most common shape.
- **columns** (edge-case): A fixed column count (`columns={3}`) with a non-square crop ratio, instead of auto-fill.
- **placeholder** (edge-case): Blur-up LQIP placeholders — a tiny data-URI blurs up as the full image decodes (zero CLS).
- **broken** (edge-case): A broken source falls back to a muted broken-image glyph without collapsing the tile.
- **selectable** (canonical): Multi-select — click, ⇧-range, ⌘/Ctrl-toggle, marquee drag, and arrows + Space; controlled via `selectedIds`.
- **overlay** (edge-case): Tile metadata in a `Gallery.Overlay` (title + dimensions) that appears on hover / focus / selected.
- **lightbox** (canonical): The built-in lightbox — click (or focus + Enter) to open a full-screen viewer; ←/→ page, Esc closes.
- **motion** (edge-case): FLIP re-layout — tiles glide between positions when the order changes (shuffle to see it); off under reduced motion.
- **reorder** (canonical): Drag-to-reorder — hover a tile for its grip and drag, or focus the grip and use Space + arrows. Powered by the sortable primitive.
- **virtualized** (edge-case): 240 assets, windowed — only the tiles near the scroll viewport are mounted.
- **empty** (edge-case): The empty state rendered via the `empty` prop when there are no items.

## Source map

Regions in `gallery.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L3–24 (22 lines) — React, lucide icons, shared hooks + composed parts
- `types` L25–95 (71 lines) — overview doc, axis aliases, item shape + gap tokens
- `context` L96–110 (15 lines) — per-tile React context (fill + selection state)
- `native-check` L111–131 (21 lines) — CSS masonry support-probe hook
- `flip` L132–250 (119 lines) — First-Last-Invert-Play re-layout hook
- `helpers` L251–268 (18 lines) — aspect-ratio derivation + tile-placement shape
- `absolute-layout` L269–350 (82 lines) — synchronous x/y/w/h packing for virtualization
- `root` L351–1138 (788 lines) — Gallery props + the layout/selection/keyboard/virtual engine
- `item` L1139–1297 (159 lines) — GalleryItem tile + drag-handle + selection-check
- `overlay` L1298–1324 (27 lines) — hover/selected metadata scrim slot
- `lightbox` L1325–1425 (101 lines) — full-screen Dialog + Carousel viewer
- `media` L1426–1546 (121 lines) — lazy zero-CLS image part (blur/skeleton/fallback)
- `utils` L1547–1555 (9 lines) — px-rounding for inline geometry
- `exports` L1556–1578 (23 lines) — compound namespace + named re-exports

---

# Gantt

> A horizontal roadmap / Gantt canvas — entity rows × a zoomable time axis with editable bars, milestones, rolled-up summaries, dependency arrows and a critical path.

- **Status:** beta
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Gantt } from "@garn/ui/gantt"`

## Overview
Gantt is a **roadmap canvas** — entity rows on the left, a zoomable time axis across the top, and a horizontal bar per item from its `start` to its `end`. Because each item owns a row, there is no overlap packing; the axis stretches from a day view out to years. Zero-duration items render as **milestone** diamonds, and a group or parent task rolls its children into a **summary** bar with duration-weighted progress. It is a full editor: drag a bar to reschedule, drag its edges to resize, drag the progress handle — by pointer *or* keyboard — with optimistic callbacks, so you always own `items`. On top of the core sit the planning layers: `dependencies` draw cycle-safe FS/SS/FF/SF arrows (with drag-to-link), `criticalPath` runs a backward-pass CPM to ring the zero-float chain and show each task's float, `baseline` + `scheduleHealth` compare planned vs actual, and `groupBy` / `filter` / `spotlight` re-lens the same data. For a vertical read-only history use `timeline`; for an hour-grid calendar use `scheduler`.

## When to use
Laying out and editing work against a horizontal time axis — a product roadmap, a project plan with dependencies and a critical path, a delivery/release schedule, a construction or campaign timeline, or a WBS with rolled-up summary bars.

## When not to use
A vertical, read-only chronological feed of events (use `timeline`); an hour-grid day/week calendar with overlapping events (use `scheduler`); picking a date or range (use `date-picker` / `calendar`); a plain hierarchical list with no time axis (use `tree` / `table`).

## Do / Don't
- ✅ Keep `items` in your own state and apply the move / resize / progress / reorder / link callbacks optimistically.
- ✅ Model phases as `groups` or parent tasks (via `parent`) so children roll up into a weighted summary bar.
- ✅ Add `dependencies` for a real Gantt; turn on `criticalPath` (with deps) to surface the driving chain and float.
- ✅ Give a bar a `baseline` and turn on `scheduleHealth` to compare planned vs actual around the today-line.
- ✅ Pass `range`/`defaultRange` (or anchor your dates) for SSR-deterministic output; build a toolbar from `useGantt` or drive it via `apiRef`.
- ❌ Don't mutate the passed items in a callback and expect a re-render — update your source of truth.
- ❌ Don't hardcode bar colors or positions — use `tone` / `appearance` and let the canvas place them in day-units.
- ❌ Don't remove the composed bar accessible name inside a custom `renderItem`.
- ❌ Don't expect garn to reschedule for you — dependencies and the critical path are display-only (garn flags violations, never moves bars).

## Guidelines
**Own the data; treat the callbacks as intents.** `items` is a controlled data prop — `onItemMove` / `onItemResize` / `onItemProgress` / `onReorder` / `onDependencyCreate` hand you the proposed change; apply it to your own state. Nothing moves until you do.

**Style only through tone × appearance and the render slot.** Give bars a `tone` (the shared vocabulary) and `appearance` (solid / soft / outline); reach for `renderItem` when you need custom bar content and `renderDetail` for a hover peek. Geometry rides inline CSS variables in day-units — never hand-position or hardcode a color or a pixel length.

**Keep it operable and honest.** The keyboard model is the differentiator — arrow-navigate bars, Enter to select, Shift/Alt+arrows to reschedule/resize, [ and ] to walk dependencies; don't strip the focus ring or the sr-only instructions. Pass `range`/`defaultRange` (or a fixed anchor for your dates) for SSR-deterministic output.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `apiRef` | `React.Ref<GanttApi>` | — | no | An imperative handle for driving the gantt from outside a child. |
| `collapsedGroups` | `string[]` | — | no | Controlled/uncontrolled collapsed group ids. |
| `criticalPath` | `boolean` | — | no | Highlight the critical path (the zero-float dependency chain) + show each non-critical task's total float as a faint trailing bar. Needs `dependencies`. |
| `defaultCollapsedGroups` | `string[]` | — | no |  |
| `defaultRange` | `GanttRange` | — | no |  |
| `defaultScale` | `GanttScale` | — | no |  |
| `defaultSelectedId` | `string` | — | no |  |
| `dependencies` | `GanttDependency[]` | — | no | Scheduling links drawn as arrows between bars (cycle-safe; see GanttDependency). |
| `editable` | `boolean` | — | no |  |
| `empty` | `React.ReactNode` | — | no | What to render when there are no rows (default: a built-in empty state). |
| `filter` | `(item: T) => boolean` | — | no | Hide rows that don't match; rollups stay honest over the visible set. |
| `firstDay` | `number` | — | no | Week start (0=Sun…6=Sat); defaults to the locale's convention, else Sunday. |
| `groupBy` | `(item: T) => { id: string; label: string; tone?: GanttTone; } \| string \| null` | — | no | Re-group rows by a derived key (status, assignee, …), overriding `group`. Return a group `{ id, label, tone }`, a bare id string, or null for ungrouped. |
| `groups` | `GanttGroup[]` | — | no |  |
| `isWorkingDay` | `(date: Date) => boolean` | — | no | Predicate for column shading (day scale). Default: weekends are non-working. |
| `items` | `T[]` | — | yes |  |
| `loading` | `boolean` | — | no | Show a skeleton loading state instead of the rows. |
| `locale` | `string` | — | no |  |
| `minimap` | `boolean` | — | no | Show a minimap / overview strip below the canvas with a draggable viewport. |
| `onCollapsedGroupsChange` | `(ids: string[]) => void` | — | no |  |
| `onDependencyCreate` | `(dep: Required<Pick<GanttDependency, "from" \| "to" \| "type">>) => void` | — | no | Enable interactive drag-to-link — hovering a bar shows edge handles you drag onto another bar to create a dependency. Fired only for cycle-safe links. |
| `onExternalDrop` | `(info: { row: string \| null; start: Date; end: Date; }) => void` | — | no | Accept a native (HTML5) drag-in onto a row; fires with the drop target. |
| `onItemClick` | `(item: T) => void` | — | no |  |
| `onItemMove` | `(item: T, range: GanttRange) => void` | — | no |  |
| `onItemProgress` | `(item: T, progress: number) => void` | — | no |  |
| `onItemRename` | `(item: T, label: string) => void` | — | no | Enable inline rename of a row's label in the rail (composes InlineEdit). |
| `onItemResize` | `(item: T, range: GanttRange) => void` | — | no |  |
| `onRangeChange` | `(range: GanttRange) => void` | — | no |  |
| `onReorder` | `(item: T, target: { parent: string \| null; index: number; }) => void` | — | no | Enable dragging a rail row to reorder / reparent it. Fires with the drop target: the new parent (or null for top level) and index among its children. |
| `onScaleChange` | `(scale: GanttScale) => void` | — | no |  |
| `onSelectedChange` | `(id: string \| null) => void` | — | no |  |
| `onVisibleRangeChange` | `(info: { startDay: number; endDay: number; }) => void` | — | no | Fired as the canvas scrolls horizontally (the visible-day range). Named so it never shadows the native `onScroll` DOM prop (different signature). |
| `railColumns` | `GanttRailColumn<T>[]` | — | no | Extra left-rail columns (turns the rail into a mini WBS grid). |
| `range` | `GanttRange` | — | no |  |
| `ref` | `React.Ref<HTMLDivElement>` | — | no |  |
| `renderDetail` | `(item: T) => React.ReactNode` | — | no | Rich detail shown in a HoverCard when a bar is hovered/focused. |
| `renderItem` | `(item: T, ctx: GanttItemContext) => React.ReactNode` | — | no |  |
| `resizableRail` | `boolean` | — | no | Let the user drag the rail / canvas divider to resize the rail. |
| `scale` | `GanttScale` | — | no |  |
| `scheduleHealth` | `boolean` | — | no | Tone each task by schedule health (behind / overdue) from its progress vs today. |
| `scrollToNow` | `boolean` | — | no | Scroll the canvas near today on mount (instead of opening at the span start). |
| `selectable` | `boolean` | — | no |  |
| `selectedId` | `string` | — | no |  |
| `showWeekNumbers` | `boolean` | — | no | Show ISO week numbers on the week-scale header tier. |
| `snap` | `boolean` | — | no | During a drag, snap the moving edge to nearby bar edges / today / milestones. |
| `spotlight` | `boolean` | — | no | On hover, highlight a bar's full dependency chain and dim the rest. |
| `todayLine` | `boolean` | — | no |  |

_Plus 277 inherited native `<div>` attributes._

### `GanttBar` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no |  |
| `linkable` | `boolean` | — | no | Show the dependency link handles (Gantt sets this from `onDependencyCreate`). |
| `onLinkStart` | `(edge: "start" \| "end", e: React.PointerEvent) => void` | — | no |  |
| `onProgressStart` | `(e: React.PointerEvent) => void` | — | no |  |
| `onResizeStart` | `(edge: "start" \| "end", e: React.PointerEvent) => void` | — | no |  |
| `progressHandle` | `boolean` | — | no | Show the progress drag handle at the fill edge. |
| `ref` | `React.Ref<HTMLButtonElement>` | — | no |  |
| `resizable` | `boolean` | — | no | Show start/end resize handles (Gantt sets this from `editable`). |

_Plus 291 inherited native HTML attributes._

## State model
- `scale` (controlled) / `defaultScale` (uncontrolled), `onScaleChange` · day | week | month | quarter | year — The time scale (column width + header tiers).
- `range` (controlled) / `defaultRange` (uncontrolled), `onRangeChange` · { start: Date; end: Date } — The visible date window. The uncontrolled seed is fitted once from the items — control `range` for live re-fit.
- `collapsedGroups` (controlled) / `defaultCollapsedGroups` (uncontrolled), `onCollapsedGroupsChange` · string[] — Collapsed group ids AND parent-task ids (a shared set).
- `selectedId` (controlled) / `defaultSelectedId` (uncontrolled), `onSelectedChange` · string | null — The selected row id (reflected via data-selected + aria-current).

## Anatomy
- `gantt`: The role=group frame; carries an accessible name for the visible range, the sr-only keyboard-model description, and reflects `data-scale` / `data-editable`.
- `gantt-rail`: The sticky left row-rail (row labels, collapse toggles, optional WBS columns and a resize separator).
- `gantt-rail-header`: The rail's sticky header row — the “Roadmap” label plus any `railColumns` headers.
- `gantt-row-header`: A rail row (group header or item). Carries `data-gantt-id` / `data-group` / `data-parent`; hosts the collapse button, inline rename, reorder grip and column cells.
- `gantt-canvas`: The scrollable time canvas whose width is the range in day-units; the drag/measure surface for pointer geometry.
- `gantt-header`: The sticky two-tier time header (primary period above, secondary below).
- `gantt-body`: The rows layer stacked over the presentational grid; the keyboard + external-drop surface.
- `gantt-grid`: The presentational (aria-hidden) gridlines + weekend/non-working shading + today-line.
- `gantt-today`: The live today-line + flag over the grid (aria-hidden).
- `gantt-deps`: The presentational dependency-arrow overlay (orthogonal elbows + arrowheads), painted behind the bars.
- `gantt-row`: One canvas row (`data-gantt-id` / `data-group` / `data-parent`) that hosts the bar / summary / milestone; also the external-drop target.
- `gantt-bar`: A focusable task bar (GanttBar). Richly labelled, roving tabindex, keyboard reschedule/resize; carries data-selected / data-dragging / data-critical / data-health.
- `gantt-summary`: A rolled-up summary bar (bracket) for a group or parent task — spans its descendants, shows weighted progress.
- `gantt-milestone`: A zero-duration marker (diamond) at `start`.
- `gantt-empty`: The built-in empty state shown when there are no rows (override via `empty`).
- `gantt-minimap`: The optional overview strip (role=scrollbar) below the canvas, with a draggable viewport window.

**Parts**
- `Gantt` (`gantt`) · required: Root + provider (generic over the item type). Owns scale/range/collapse/selection + the drag machine, dependency resolution, critical-path/rollup math and the imperative `apiRef`; renders the rail + time canvas. Lifts `useGantt` for a consumer toolbar.
- `GanttBar` (`gantt-bar`): The default bar / summary / milestone renderer — `tone` × `appearance` (badge tokens) × `variant` (task / summary / milestone), a tonal left accent, progress fill and optional resize / progress / link handles. Exported for use inside `renderItem`.

## Accessibility
- **Role:** group (APG: grid)
- **Tab:** Enter the bars; one bar is tabbable (roving tabindex).
- **ArrowDown / ArrowRight:** Move to the next bar (down the rows).
- **ArrowUp / ArrowLeft:** Move to the previous bar.
- **Home / End:** First / last bar.
- **Enter / Space:** Select / activate the focused bar (onItemClick).
- **Shift / ArrowLeft:** Reschedule the focused bar one day earlier (when editable).
- **Shift / ArrowRight:** Reschedule the focused bar one day later (when editable).
- **Alt / ArrowLeft:** Shorten the focused bar by one day (when editable).
- **Alt / ArrowRight:** Lengthen the focused bar by one day (when editable).
- **[:** Jump to the focused bar's predecessor (a dependency source).
- **]:** Jump to the focused bar's successor.
- **Escape:** Cancel an in-progress pointer drag / link / reorder (no commit).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A); 2.4.7 Focus Visible (AA); 1.4.10 Reflow (AA)
- The root is role=group with an accessible name for the visible range (aria-roledescription="gantt chart") and an sr-only aria-describedby that states the keyboard model.
- The decorative grid, time header, today-line, minimap and dependency arrows are presentational (aria-hidden); the real semantics live on the bars.
- Each bar is a focusable control with a composed accessible name ("{label}, {start} to {end}, {n}% complete"); a milestone reads "{label} milestone, {date}", a summary "{label} summary, …".
- The name also folds in relationships + status: "after {preds}", "blocks {succs}", "on the critical path", "overdue" / "behind schedule", and the baseline range.
- One bar is tabbable at a time (roving tabindex); selection is exposed via aria-current="true" on the selected bar (not visual-only).
- Group / parent rows have an aria-expanded collapse toggle labelled "Expand/Collapse {label}". The rail resize divider is a labelled role=separator with aria-value min/max/now; the minimap is a role=scrollbar with aria-controls the scroll region.
- Move / resize / progress / link / reorder results are announced in a polite live region; a cancelled drag announces "Cancelled."
- Geometry uses logical properties, so the rail, bars and arrows mirror under dir="rtl".
- **Focus:** Roving tabindex over the bars (and focusable group/parent summary bars); focus-visible rings preserved; keyboard focus follows [ / ] dependency jumps.
- **Contract (warn):** The root exposes an accessible name describing the visible range (default: "Roadmap, {range}"). — _when always_
- **Contract (warn):** Every focusable bar control has a composed accessible name including its label and dates; a custom renderItem must not remove it. — _when a bar is rendered_
- **Contract (warn):** The grid, header, today-line, minimap and dependency arrows are aria-hidden; a11y lives on the bars + the [ / ] jump. — _when always_
- **Contract (warn):** The collapse control is a button with aria-expanded and a label naming the group/task. — _when a group or parent row is rendered_

## Tokens
- `dayWidth` → `--garn-gantt-day-base` (identity)
- `rowHeight` → `--garn-gantt-row` (identity)
- `railWidth` → `--garn-gantt-rail` (identity)
- `railColumnWidth` → `--garn-gantt-col` (identity)
- `headerTier` → `--garn-gantt-tier` (identity)
- `viewport` → `--garn-gantt-viewport` (identity)
- `surface` → `--garn-background`
- `hairline` → `--garn-border`
- `todayLine` → `--garn-danger-solid`
- `selectedRing` → `--garn-brand-solid` · brandable
- **Internal (never externalize):** `--garn-gantt-day`, `--garn-gantt-rail`, `--gantt-x`, `--gantt-w`, `--gantt-p`, `--b-bg`, `--b-fg`, `--b-solid`, `--b-solid-fg`, `--b-line`, `--b-fill`, `--b-rail`

## Related
- **composes** → `utils`
- **composes** → `inline-edit` (when onItemRename turns a rail label into edit-in-place)
- **composes** → `empty` (when the built-in empty state (no rows))
- **composes** → `skeleton` (when the loading state)
- **composes** → `hover-card` (when renderDetail wraps each bar in a detail peek)
- **alternativeTo** → `timeline` (when you need an editable horizontal roadmap, not a vertical read-only feed)
- **alternativeTo** → `scheduler` (when work spans days/weeks on a horizontal axis rather than hours in a day/week calendar)
- **pairsWith** → `button` (when a scale / zoom / today toolbar built from useGantt or apiRef)
- **pairsWith** → `tree` (when a deep WBS rail drives the rows (a documented recipe))
- **pairsWith** → `dialog` (when confirm / edit a task on click or on external drop)
- **slotAccepts** → `hover-card` (when a detail peek on a bar via renderDetail)

## Recipes
- **roadmap-editor** — A grouped product roadmap with milestones, progress and a full drag editor, plus a scale/zoom toolbar built from useGantt. _(use when planning and adjusting phased work on a horizontal timeline where users drag bars to reschedule/resize, unless the timeline is read-only history (use timeline) or the horizon is a single day/week of hours (use scheduler))_
- **dependency-plan** — A project plan whose tasks link with FS/SS/FF/SF dependencies and highlight the critical path and each task's float. _(use when tasks constrain each other and you need to see the driving chain / slack)_
- **wbs-rail** — A work-breakdown rail — nested subtasks, extra columns (owner, %), a resizable divider, inline rename and drag-to-reorder — beside the timeline. _(use when the left rail should read as a mini spreadsheet / WBS with editable, reorderable rows)_

## Gotchas
- **Dragging or resizing a bar does nothing — it snaps back.** — `items` is a controlled data prop; the callbacks are intents, not mutations. The component never changes your data for you. → In onItemMove / onItemResize / onItemProgress, apply the returned range/fraction to your own state (setItems(prev => prev.map(...))).
- **A dependency arrow doesn't appear, or the critical path is empty.** — An endpoint is hidden inside a collapsed group/parent, an edge was dropped for closing a cycle, or `criticalPath` is on without `dependencies`. → Expand the endpoints; remember resolveDeps drops self-links, unknown ids and cycle-closing edges; pass `dependencies` for criticalPath to have a graph.
- **Bars won't move by pointer even though keyboard edits work.** — Editing is off, or that item opted out. Pointer geometry needs the canvas laid out (it measures the gantt-canvas). → Set `editable`; check the item isn't `editable: false` and isn't a milestone (zero-duration, non-resizable). Keyboard Shift/Alt+arrows are layout-free and always work when editable.
- **The range shows the wrong window and won't update when items change.** — The uncontrolled range seed is fitted once from the first items/scale; later item changes don't re-fit an uncontrolled range. → Control `range` (with onRangeChange) and re-fit yourself, or call apiRef.fitToItems(), or key the component to remount.
- **SSR hydration mismatch — the today-line or fitted range differs between server and client.** — With no `range`/`defaultRange` the seed is fitted from `new Date()`-derived data, and the today-line reads the live clock. → Anchor your item dates and pass `range`/`defaultRange` for deterministic SSR; the today-line reconciles on mount.
- **A custom renderItem bar keeps the default GanttBar chrome (accent rail, progress fill, lozenge shape) around my content.** — renderItem is a CONTENT slot rendered inside the GanttBar control (so it keeps the ref, roving tabindex, accessible name and drag/select wiring) — it is not a full replacement of the bar element. → Style within the bar via tone/appearance and the content you return; branch on ctx.variant (task/summary/milestone) for per-kind content. The bar's accessible name and interaction come for free — don't try to re-add them.

## Examples
- **roadmap** (canonical): The hero: a grouped roadmap with milestones, progress, snap, a minimap, hover detail and a full drag editor with a useGantt scale/zoom toolbar.
- **flat** (playground): No groups, day scale — a simple task list with weekend shading and milestones.
- **dependencies** (playground): FS/SS dependency arrows chaining into a milestone, a violation flagged, weighted group rollups, and interactive drag-to-link.
- **critical-path** (playground): The zero-float critical path highlighted, with a floating side task showing its total float as a trailing bar.
- **baseline-health** (playground): Planned-vs-actual baselines (ghost bars) + schedule-health tones (behind / overdue) around today's line.
- **wbs-rail** (playground): The left rail as a WBS grid — nested subtasks, extra columns, a resizable divider, inline rename and drag-to-reorder.
- **lenses** (playground): Re-group by team or status, filter to active, and spotlight a dependency chain on hover.
- **external-drop** (playground): Drag an unscheduled chip from outside onto a row to schedule it (onExternalDrop).
- **states** (playground): The imperative apiRef (today / fit / expand / collapse) plus the loading and empty states.
- **tones** (playground): The bar tone × appearance range (soft / solid), plus a summary and a milestone.

## Source map

Regions in `gantt.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–19 (18 lines) — React, cva, icons, garn lib and component deps
- `time-scale` L20–80 (61 lines) — doc banner, tone unions, scale factors, ISO weeks
- `types` L81–161 (81 lines) — public item, group, dependency, rail, api interfaces
- `time-math` L162–215 (54 lines) — DST-safe day math and period-start helpers
- `ticks` L216–308 (93 lines) — range fitting and two-tier header ticks
- `model` L309–443 (135 lines) — flatten groups and item tree into rows, rollups
- `dependencies` L444–550 (107 lines) — cycle-safe dep resolution, violations, riser routing
- `critical-path` L551–632 (82 lines) — CPM backward pass, total float, schedule health
- `bar` L633–804 (172 lines) — GanttBar variants: task, summary, milestone renderer
- `context` L805–833 (29 lines) — GanttContext and useGantt toolbar hook
- `drag-model` L834–854 (21 lines) — pointer drag kinds and state shape
- `props` L855–947 (93 lines) — GanttProps: the full public prop surface
- `root` L948–2715 (1768 lines) — Gantt root: state, gestures, keyboard, zoom, render
  - `state` L1001–1064 (64 lines) — controllable scale, range, collapse, selection, drag state
  - `layout` L1066–1198 (133 lines) — day span, formatters, header tiers, rows, rail geometry
  - `dep-graph` L1200–1297 (98 lines) — dep memos, spotlight, critical set, placement, xToDay
  - `gestures` L1299–1677 (379 lines) — pointer drag, snap, drag-to-link, row reorder
  - `keyboard` L1679–1775 (97 lines) — roving focus, arrow nav, keyboard reschedule and resize
  - `zoom-api` L1777–1847 (71 lines) — anchored zoom and the imperative GanttApi handle
  - `scroll-sync` L1849–1892 (44 lines) — scroll state, onVisibleRangeChange callback, initial scroll, percentages
  - `render-prep` L1894–2140 (247 lines) — context value, empty, skeleton, bar and summary renderers
  - `arrows` L2142–2250 (109 lines) — orthogonal dependency arrow overlay with obstacle avoidance
  - `render` L2252–2713 (462 lines) — the assembled JSX: rail, canvas, header, minimap

---

# Gauge

> A radial dial for a single value — with threshold zones, an optional needle, ticks, and a target.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Gauge } from "@garn/ui/gauge"`

## Overview
Gauge is the KPI dial: a single value on a radial scale, read against optional threshold zones (calm → warning → critical) that colour the arc and the accessible reading. It shows as a filled arc or a speedometer needle, with optional ticks, a scale, and a target marker. It's pure d3-shape SVG — no charting engine — and a `meter` for assistive tech, so the value is announced.

## When to use
Show a single value on a dial against thresholds/target — capacity, score, throughput, health.

## When not to use
Comparing many KPIs or fitting a dense table (use Bullet); simple linear progress (use Progress); a trend (use Sparkline).

## Do / Don't
- ✅ Pass `thresholds` for auto-zone colouring; give it an `aria-label`.
- ✅ Use `variant="needle"` for a speedometer; set `target` for a reference.
- ❌ Don't hand-colour per value when zones express the meaning.
- ❌ Don't line up many gauges where bullets would compare better.

## Guidelines
**Use it for one prominent value.** A gauge earns its space as a single, glanceable dial; to compare many KPIs or fit a table, a Bullet is denser. For simple linear progress, Progress is lighter.

**Let zones do the colouring.** Pass `thresholds` and the arc auto-colours by the active zone and folds the zone label into the reading — don't hand-set `color` per value. Zones double-encode as bands so the state reads without relying on hue.

**Announce the value.** It's a `meter`: give it an `aria-label`; the value, active zone, and target are folded into `aria-valuetext`.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string` | — | no | Single-tone fallback when there are no `thresholds`. Token reference. |
| `delta` | `React.ReactNode` | — | no | Optional trend readout under the value (e.g. a delta). |
| `endAngle` | `number` | — | no |  |
| `label` | `React.ReactNode` | — | no |  |
| `max` | `number` | — | no |  |
| `min` | `number` | — | no |  |
| `numberFormat` | `Intl.NumberFormatOptions` | — | no |  |
| `showScale` | `boolean` | — | no | Min / max end labels on the scale. |
| `showValue` | `boolean` | — | no |  |
| `size` | `"lg" \| "md" \| "sm"` | — | no |  |
| `startAngle` | `number` | — | no | Sweep in degrees, clockwise from 12 o'clock. Default a 270° dial. |
| `target` | `number \| { value: number; label?: string; }` | — | no | A reference marker on the arc; folded into the accessible reading. |
| `thresholds` | `GaugeThreshold[]` | — | no | Colour zones — auto-colour the arc + reading, and draw the track bands. |
| `ticks` | `number` | — | no | Number of tick intervals around the arc (0 = none). |
| `value` | `number` | — | yes |  |
| `valueLabel` | `React.ReactNode` | — | no |  |
| `variant` | `"arc" \| "needle"` | — | no | Filled progress arc (default) or a speedometer needle over the zones. |

_Plus 279 inherited native `<div>` attributes._

## Anatomy
- `gauge`: The dial (role=meter); an SVG (arc/zone bands/needle/ticks/target) + a decorative centre readout overlay. `data-variant`, `data-size`.

## Accessibility
- **Role:** meter
- **WCAG:** 1.4.1 Use of Color (A); 4.1.2 Name, Role, Value (A)
- role=meter with aria-valuenow (clamped into [min,max]) / aria-valuemin / aria-valuemax; pass an `aria-label`.
- aria-valuetext folds in the value, the active zone label, and the target (e.g. "94%, Critical, target 80").
- The centre readout + SVG are decorative; zone colour is paired with the zone label so meaning isn't colour-only.

## Related
- **composes** → `utils`
- **alternativeTo** → `bullet` (when space is tight or you're comparing many KPIs)
- **alternativeTo** → `progress` (when the value is simple linear progress, not a dial)

## Gotchas
- **aria-valuenow sits outside [min,max].** — The value exceeds the bounds. → It's clamped for aria; the readout can still show the raw value via `valueLabel`.
- **Needle reads oddly on a full ring.** — Needle suits ≤270° sweeps. → Use the default arc for full rings; needle for half/three-quarter dials.

## Examples
- **basic** (canonical): A full-ring dial with a centre readout.
- **thresholds** (edge-case): Threshold zones auto-colour the arc + reading; a target tick.
- **needle** (edge-case): A half-circle speedometer with ticks + scale.
- **sizes** (edge-case): sm / md / lg, with a delta.

---

# Heatmap

> A value matrix — rows × columns of cells tinted by value — rendered as a navigable table.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Heatmap } from "@garn/ui/heatmap"`

## Overview
Heatmap renders a value matrix — cohort retention, correlation, hour×day activity — as an actual `<table>` with row and column headers, its cells tinted by value. Building it as a table (not an SVG) means it's navigable and readable to assistive tech for free, while the colour gives sighted users the at-a-glance pattern. For an unlabelled calendar-style density grid, use Activity Grid instead.

## When to use
Show a labelled value matrix — retention cohorts, correlation, hour×day activity.

## When not to use
An unlabelled calendar/contribution density grid (use Activity Grid); a single series trend (use Sparkline/Line).

## Do / Don't
- ✅ Provide row/column labels + a `caption`; use a `valueFormatter`.
- ✅ Keep the matrix modest in size so cells stay legible.
- ❌ Don't drop the headers/caption — they're what makes it accessible.
- ❌ Don't map cells to unrelated hues; intensity is one token.

## Guidelines
**It's tabular data — keep it a table.** Row/column headers and a caption make the matrix navigable; the colour is a second, decorative channel over an accessible base.

**One hue, opacity by value.** Cells tint a single `--garn-chart-*` token; intensity is `value/peak` (floored so low-but-nonzero cells stay visible). Provide a `valueFormatter` (e.g. `%`) so the hover/sr value reads right.

**Constrain the width.** It ships `w-fit` so a global full-width table style doesn't stretch the cells; keep cells squarish for a readable matrix.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `caption` | `string` | — | yes | Accessible table caption (visually hidden). |
| `color` | `string` | — | no | Cell tint (token ref). |
| `columns` | `string[]` | — | yes | Column labels (x axis) — one per column. |
| `max` | `number` | — | no | Value mapped to full intensity (default: the largest value). |
| `rows` | `string[]` | — | yes | Row labels (y axis) — one per row. |
| `valueFormatter` | `(value: number) => string` | — | no | Format a cell's value for the hover title + screen-reader text. |
| `values` | `number[][]` | — | yes | Row-major matrix of values: `values[rowIndex][colIndex]`. |

_Plus 287 inherited native `<table>` attributes._

## Anatomy
- `heatmap`: The `<table>` — column headers + row headers frame the matrix.
- `heatmap-cell`: A `<td>`: a token-tinted square (opacity = value/peak) + an sr-only value + a hover title.

## Accessibility
- **Role:** table
- **WCAG:** 1.3.1 Info and Relationships (A); 1.1.1 Non-text Content (A)
- A real `<table>` with a `<caption>` and scoped row/column headers — navigable by assistive tech.
- Each cell exposes its value via visually-hidden text; the colour is decorative.
- Cell intensity = value / peak opacity of a `--garn-chart-*` token (floored so low values stay visible).

## Related
- **composes** → `utils`
- **alternativeTo** → `activity-grid` (when you want an unlabelled calendar/contribution grid)

## Gotchas
- **Columns spread far apart / table stretches full width.** — A global `table { width: 100% }` overrides. → The component ships `w-fit`; keep it (or set an explicit width) so cells stay square.

## Examples
- **basic** (canonical): Weekly retention by signup cohort (%).

---

# Hover Card

> A floating card of preview detail shown on hover/focus of a trigger.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { HoverCard } from "@garn/ui/hover-card"`
- **Polymorphism:** `asChild`

## Overview
HoverCard previews supplementary detail when a user hovers or focuses a link or name — a profile card, a link preview, a definition peek. `HoverCard` owns open/close delays, `HoverCardTrigger` is the hovered element (keep it focusable), and `HoverCardContent` is the floating card. It's richer than a Tooltip (it can hold layout and media) but still passive and hover-driven — for content the user must click into, use a Popover.

## When to use
Preview supplementary detail when hovering/focusing a link or name — a user/profile card, a link preview, a definition peek.

## When not to use
Essential info or actions a user must reach (put it inline or use popover); a short text hint (use tooltip); a click-triggered surface (use popover / dropdown-menu); touch-first flows.

## Do / Don't
- ✅ Use a focusable trigger (a link or button) so keyboard users can open it.
- ✅ Keep the content supplementary — never the only way to reach important info.
- ✅ Tune openDelay/closeDelay to match intent.
- ❌ Don't put essential or interactive-only content in a hover card.
- ❌ Don't rely on it on touch-first experiences.
- ❌ Don't use it where a plain text tooltip would do.

## Guidelines
**Use it for a glanceable preview, never for essential content.** Hover isn't available on touch and is easy to miss, so anything required must live in the page; the card only enriches. It's the step up from a Tooltip when the preview needs structure (an avatar, a few facts).

**Keep it non-interactive and quick to dismiss.** Don't put buttons or links users must reach inside a hover card — the open/close timing makes targeting fiddly; that's a Popover's job. Tune the delays so it doesn't flicker on incidental hovers.

**Keep the trigger focusable and the content light.** Wrap a real link/button so keyboard and AT users can reach the preview too, and keep the card concise — a peek, not a panel.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Controlled via `open` + `onOpenChange`; otherwise opens on hover/focus after `openDelay` and closes after `closeDelay`.
- Selection: single.

## Anatomy

**Parts**
- `HoverCard` · required: Root — owns the open state and `openDelay`/`closeDelay`.
- `HoverCardTrigger` (`hover-card-trigger`) · required: The hovered/focused element (asChild to wrap a link or button — keep it focusable).
- `HoverCardContent` (`hover-card-content`) · required: The floating preview card (popover-positioned).

## Accessibility
- **WCAG:** 1.4.13 Content on Hover or Focus (AA); 2.1.1 Keyboard (A)
- Radix opens the card on hover AND keyboard focus — so the trigger must be focusable (a link or button), not a bare span.
- The content is supplementary; it isn't a modal and doesn't trap focus.
- Hover has no touch equivalent — never make the card the only path to important content.
- **Focus:** Opens on trigger focus as well as hover; not focus-trapped.

## Tokens
- `padding` → `--garn-pad-panel` (air)

## Related
- **composes** → `utils`
- **pairsWith** → `avatar` (when as a user/profile preview)
- **alternativeTo** → `tooltip` (when a short text hint is enough)
- **alternativeTo** → `popover` (when the surface should open on click and may hold focus/actions)

## Gotchas
- **Keyboard or touch users never see the card.** — The trigger isn't focusable (a bare span), or the flow is touch-first. → Use a focusable trigger (link/button) and keep the content non-essential — or switch to popover.

## Examples
- **basic** (canonical): A profile preview card on a link trigger.

---

# InlineEdit

> Edit a value in place — a value that reads as plain text until you touch it, then becomes a real field. Compound Preview ⟷ Control with click/focus/dblclick activation, quiet or explicit commit, validation, dirty-check, optimistic updates, async save, and a swappable typed control.

- **Status:** beta
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { InlineEdit } from "@garn/ui/inline-edit"`
- **Polymorphism:** `asChild` (default element `<span>`)

## Overview
InlineEdit turns a read-only value editable in place: it reads as plain text until you touch it, then becomes a real field you change without leaving the row. It owns the transition (activation, commit/cancel, focus return, select-on-activate, the save/error announce) and delegates the editing to a real garn field on the shared surface. Compose just `InlineEdit.Preview` + `InlineEdit.Control` for the quiet preset (Enter/blur commits), or add `InlineEdit.SubmitTrigger` / `InlineEdit.CancelTrigger` for the explicit preset — one API, no fork. For picking a value from a known set use BadgeSelect; for an always-open form field use Input; for a read-only detail block use DataList.

## When to use
Editing a single value in place — a field in a detail panel, a table/board cell, an entity property, or a title you rename without a modal. Use the quiet preset for fast edits, the explicit preset (Save/Cancel) for costly-to-mistake data cells.

## When not to use
Picking a value from a known set (use BadgeSelect); a standard always-open form field with a label (use Input / a field); a read-only 'field: value' block (use DataList); a whole multi-field form (use Form + inputs); rows × columns of records (use Table).

## Do / Don't
- ✅ Compose Preview + Control for the quiet preset; add SubmitTrigger + CancelTrigger for the explicit one.
- ✅ Use `validate` / `required` to gate a commit with an inline error, and `onSubmit` (which may be async) to persist.
- ✅ Wire a custom typed field (NumberField / Select) through `useInlineEdit()` inside InlineEdit.Control.
- ✅ Pair the Preview with a `reveal` EditTrigger (or `appearance="outline"`) so the value reads as editable.
- ✅ Let the Preview name itself; give a custom Control field its own aria-label.
- ❌ Don't use it to pick from a known set — that's BadgeSelect.
- ❌ Don't reach for `appearance="outline"/"soft"` by default — it blurs the text-until-touched identity and the InlineEdit↔Input line.
- ❌ Don't re-implement validation around `onSubmit` — use `validate` (it blocks and shows the error for you).
- ❌ Don't hand-manage focus return or blur-commit — the component owns the focus model and the blur-vs-Cancel guard.

## Guidelines
**Pick the commit model for the context.** The quiet preset (Enter/blur commits, no buttons) suits fast, low-stakes edits; the explicit preset (Save/Cancel) suits data cells where an accidental commit is costly. `submitMode` and the optional trigger parts express both on one component.

**Gate before you persist.** Use `validate` (and `required`) to block bad input with an inline error — distinct from `onSubmit`, which persists. An async `onSubmit` keeps the editor open on failure and surfaces the rejection message; add `optimistic` when a snappy save matters more than waiting.

**Keep it discoverable and accessible.** A plain-text value gives no signal it's editable — pair the Preview with a `reveal` EditTrigger, or use `appearance="outline"` where a field affordance is wanted. The Preview names itself 'Edit, {value}' so assistive tech announces editability; keep a custom Control field labelled.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activationMode` | `"click" \| "dblclick" \| "focus" \| "none"` | `click` | no | How the Preview enters edit mode. `none` = only via EditTrigger / programmatic. |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `ghost` | no | Field-surface fill. `ghost` (default) reads as plain text until touched; `outline` / `soft` render a visible field at rest. ⚠️ non-ghost blurs the "text-until-touched" identity — use deliberately. |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no | Field-surface size scale. |
| `submitMode` | `"blur" \| "both" \| "enter" \| "none"` | `both` | no | What commits the draft. `both` = Enter or blur; `none` = only SubmitTrigger. |
| `cancelLabel` | `string` | — | no | Accessible name for the default CancelTrigger. |
| `defaultEditing` | `boolean` | — | no | Whether the editor starts open (uncontrolled). |
| `defaultValue` | `string` | — | no | The initial committed value (uncontrolled). |
| `disabled` | `boolean` | — | no | Disable the whole control. |
| `editing` | `boolean` | — | no | Whether the editor is open (controlled). Pair with `onEditingChange`. |
| `editLabel` | `string` | — | no | Accessible name for the default EditTrigger + the Preview's edit affordance. |
| `error` | `React.ReactNode` | — | no | A validation / commit error; keeps the editor open and wires aria-invalid + the message. |
| `loading` | `boolean` | — | no | External pending state (a controlled async commit). |
| `maxLength` | `number` | — | no | Cap the draft length; renders a live character counter in edit mode. |
| `multiline` | `boolean` | — | no | Edit as a multi-line, auto-growing textarea (Enter inserts a newline; ⌘/Ctrl+Enter submits). |
| `name` | `string` | — | no | Submit the committed value inside a native `<form>` via a hidden input. Reflects the committed (not draft) value. |
| `onCancel` | `() => void` | — | no | Fires when the user reverts (Escape / Cancel / revert-on-blur). |
| `onEditingChange` | `(editing: boolean) => void` | — | no | Fires when the editor opens or closes. |
| `onSubmit` | `(value: string) => void \| Promise<void>` | — | no | Attempt to commit `value`. Return a promise to run async: the editor shows a spinner and stays open until it resolves; a rejection surfaces its message as the error and keeps the editor open. Resolving (or returning void) commits. |
| `onValueChange` | `(value: string) => void` | — | no | Fires with the new committed value after a successful submit. |
| `optimistic` | `boolean` | — | no | Commit the new value optimistically — fire `onValueChange` immediately, and if an async `onSubmit` rejects, roll the value back to what it was before. Default `false` (pessimistic: the value only changes after `onSubmit` resolves). |
| `placeholder` | `React.ReactNode` | — | no | Shown in the Preview when the value is empty (e.g. "Add description"). |
| `required` | `boolean` | — | no | Block committing an empty value (after trimming). Sugar over `validate`. |
| `requiredMessage` | `string` | — | no | Error shown when `required` blocks an empty commit. |
| `savedAnnouncement` | `string` | — | no | Announced (polite) after a successful commit. |
| `selectOnFocus` | `boolean` | — | no | Select the field's text when edit mode opens. |
| `submitLabel` | `string` | — | no | Accessible name for the default SubmitTrigger. |
| `validate` | `(value: string) => string \| null \| undefined \| Promise<string \| null \| undefined>` | — | no | Gate a commit *before* it persists. Return a message (string) to block the commit and show it as the inline error; return null / undefined to allow it. May be async (the editor shows a spinner while it runs). Distinct from `onSubmit`: `validate` gates, `onSubmit` saves. |
| `value` | `string` | — | no | The committed value (controlled). Pair with `onValueChange`. |

_Plus 277 inherited native `<span>` attributes._

### `InlineEdit.Preview` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no | Render as the child element (e.g. a heading), merging the trigger wiring. |
| `label` | `string` | — | no | Override the composed accessible name. By default the button reads "{editLabel}, {value}" (e.g. "Edit, Ada Lovelace") so a SR user knows the value is editable; pass `label` to set it explicitly. |

_Plus 289 inherited native HTML attributes._

### `InlineEdit.Control` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | no | A custom edit-state field (a NumberField / Select), wired via `useInlineEdit`. Omit to render the built-in text input (or textarea when `multiline`), which is auto-wired to the draft. |
| `className` | `string` | — | no |  |

### `InlineEdit.EditTrigger` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `reveal` | `boolean` | — | no | Fade the affordance in on the root's hover / focus-within (and keep it visible on touch), so a plain-text value visibly reads as editable without cluttering the resting state — the `DataList.CopyButton` reveal idiom. |

_Plus 290 inherited native HTML attributes._

## Variants
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`
- **appearance** (default `ghost`): `ghost`, `outline`, `soft`
- **activationMode** (default `click`): `click`, `focus`, `dblclick`, `none`
- **submitMode** (default `both`): `enter`, `blur`, `both`, `none`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The committed value. Controlled via `value` + `onValueChange` (fires after a successful commit); uncontrolled via `defaultValue`.
- `editing` (controlled) / `defaultEditing` (uncontrolled), `onEditingChange` · boolean — Whether the editor is open. Controlled via `editing` + `onEditingChange`; uncontrolled via `defaultEditing`.
- Selection: single.

## Anatomy
- `inline-edit`: The region — a <span> that owns the value/editing state + context and carries the size/appearance/activation-mode/submit-mode/editing/invalid data-attrs. Also hosts the optional hidden form input (`name`) and the sr-only error node.

**Parts**
- `InlineEdit.Preview` (`inline-edit-preview`) · required: The read node — a text-styled <button> shown when not editing. Its accessible name composes '{editLabel}, {value}' so a SR user knows it's editable. Click/focus/dblclick activates per `activationMode`. Falls back to the committed value when given no children; asChild to host a heading/link.
- `InlineEdit.Control` (`inline-edit-control`) · required: The edit node — shown when editing. With no children it renders the built-in text field (an <input>, or a <textarea> when `multiline`) auto-wired to the draft on the field surface. Pass a custom field (NumberField / Select) as children and wire it via `useInlineEdit()`.
- `InlineEdit.EditTrigger` (`inline-edit-edit-trigger`): Optional pencil affordance shown when not editing — enters edit mode. Use with `activationMode="none"`, or set `reveal` to fade it in on hover/focus-within (the DataList.CopyButton idiom) as a discoverability hint.
- `InlineEdit.SubmitTrigger` (`inline-edit-submit-trigger`): Optional commit button (a check) shown when editing. Its presence turns the quiet preset into the explicit one — no boolean needed. Shows a Spinner while an async commit is pending.
- `InlineEdit.CancelTrigger` (`inline-edit-cancel-trigger`): Optional revert button (a ✕) shown when editing — reverts to the last committed value and returns focus to the Preview.

## Accessibility
- **Role:** button
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 3.3.1 Error Identification (A); 4.1.2 Name, Role, Value (A)
- The Preview is a real <button>; its accessible name composes the edit intent with the value ('Edit, Ada Lovelace') so a screen reader knows the value is editable, not just its text. Override with the Preview `label` prop.
- Focus RETURNS to the Preview on commit or cancel (the #1 defect in homegrown inline-edits); the field's text is selected on activate (opt-out `selectOnFocus`).
- Enter commits per `submitMode`; Escape always reverts and is stopPropagation'd so it doesn't also close an enclosing popover/dialog.
- A blur whose focus lands on the Submit/Cancel button does NOT commit (the relatedTarget guard) — the classic blur-fights-cancel-button trap.
- A blocked commit (required / validate / async rejection) keeps the editor open, sets aria-invalid + aria-describedby to the message, and announces it assertively; a success announces politely via a shared live region.
- `required` sets aria-required on the field; a hidden input (`name`) submits the committed value inside a native <form>.
- **Focus:** The Preview and the edit-state field are focusable; on activate focus moves to the field (text selected), and on commit/cancel it returns to the Preview. Triggers each carry a 2px focus-visible ring.
- **Contract (warn):** Give a custom edit-state field an accessible name (aria-label / aria-labelledby). The built-in field is named from `editLabel` automatically. — _when InlineEdit.Control hosts a custom field (children) wired via useInlineEdit, and that field has no aria-label / aria-labelledby_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)

## Related
- **composes** → `utils`
- **composes** → `spinner` (when an async commit is pending)
- **slotAccepts** → `number-field` (when InlineEdit.Control hosts a NumberField wired via useInlineEdit)
- **slotAccepts** → `select` (when InlineEdit.Control hosts a Select wired via useInlineEdit)
- **pairsWith** → `data-list` (when a Preview drops into DataList.Value to make a read-only detail block editable)
- **alternativeTo** → `badge-select` (when the value is picked from a known set (a status/priority), not free-typed)
- **alternativeTo** → `input` (when the field should always be open (a standard labelled form field), not toggle read↔edit)
- **alternativeTo** → `data-list` (when the value is read-only (a detail block), not editable)

## Recipes
- **editable-detail-panel** — An editable detail panel — a DataList whose values are InlineEdits, so a read-only block becomes editable in place without losing its <dl> semantics. _(use when showing one entity's fields as editable label/value pairs)_

## Gotchas
- **Clicking the value doesn't enter edit mode.** — activationMode is `none` (or the InlineEdit is disabled) — the Preview doesn't self-activate. → Use the default `activationMode="click"`, or add an `InlineEdit.EditTrigger` for the `none` case.
- **A custom NumberField / Select in InlineEdit.Control doesn't update or commit.** — The built-in wiring only covers a native input's `onChange`; a typed field reports via `onValueChange`. → Read `useInlineEdit()` inside the control and wire `draft` / `setDraft` / `fieldRef` / `onFieldKeyDown` / `onFieldBlur` onto the field yourself.
- **A custom control overflows into / overlaps the Submit / Cancel triggers.** — The custom field has a fixed width (e.g. `w-28`) wider than the flex-1 control track once the triggers take their share of the row. → Size the custom control flexibly (`w-full`) so it fills the control track and leaves room for the triggers; the built-in field already flexes. Widen the InlineEdit root if the field needs more space.
- **Pressing Enter fires onSubmit even when nothing changed.** — It doesn't — an unchanged value is dirty-checked and closes silently. If you expected a save, the value did change. → Rely on the dirty-check; only real changes run `validate` / `onSubmit` and announce 'Saved'.
- **Validation runs but the value still saves to the server on error.** — `validate` and `onSubmit` are separate: validate gates, onSubmit persists. Persisting inside validate bypasses the gate. → Return the error message from `validate` (persist only in `onSubmit`); a non-null return blocks the commit.
- **The value reads as plain text — users don't know it's editable.** — The default `ghost` appearance is intentionally text-like at rest. → Add an `InlineEdit.EditTrigger reveal` (a hover pencil), or set `appearance="outline"` where a field affordance is wanted.
- **Clicking Save (or Cancel) seems to commit twice / fight the blur.** — It doesn't with the built-in triggers — a blur onto a trigger inside the InlineEdit is guarded. A hand-rolled button outside the component isn't. → Use InlineEdit.SubmitTrigger / .CancelTrigger (they sit inside the region, so the relatedTarget guard applies).

## Examples
- **basic** (canonical): The default — a controlled value, click to edit, Enter/blur to commit.
- **presets** (edge-case): Quiet (Enter/blur, no buttons) vs explicit (Save/Cancel) — one API.
- **activation** (edge-case): click · dblclick · none (EditTrigger only).
- **multiline** (edge-case): An auto-growing textarea — Enter inserts a newline, ⌘/Ctrl+Enter saves.
- **empty** (edge-case): An empty value shows the muted placeholder and still reads as editable.
- **max-length** (edge-case): A capped value with a live character counter.
- **async** (edge-case): An async onSubmit — a spinner while saving, stays open with the error on failure.
- **affordance** (edge-case): A hover-revealed edit pencil (EditTrigger `reveal`) for discoverability.
- **validation** (edge-case): required + validate gate a commit with an inline error before it persists.
- **optimistic** (edge-case): Optimistic commit — closes immediately, rolls back and reopens on failure.
- **typed** (edge-case): A NumberField edit-state control wired through the useInlineEdit() hook.
- **sizes** (edge-case): sm · md · lg.
- **appearances** (edge-case): ghost (text until touched) · outline · soft.
- **form** (edge-case): Form integration — `name` submits the committed value via a hidden input.
- **data-rich** (edge-case): InlineEdits inside a DataList — an editable detail panel.

## Source map

Regions in `inline-edit.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–19 (18 lines) — React, Radix Slot, icons, shared hooks
- `types` L20–63 (44 lines) — overview doc + shared axis aliases
- `utils` L64–91 (28 lines) — text extraction, spinner sizing, error normalization
- `context` L92–160 (69 lines) — value shape, provider, useInlineEdit hook
- `root` L161–633 (473 lines) — props + the state-owning InlineEdit component
- `preview` L634–728 (95 lines) — read node (text-styled button)
- `control` L729–857 (129 lines) — edit node (built-in field or custom slot)
- `variants` L858–911 (54 lines) — size scales + ghost paint class strings
- `triggers` L912–1035 (124 lines) — edit / submit / cancel affordance buttons
- `exports` L1036–1063 (28 lines) — compound assembly + named re-exports

---

# Input OTP

> A segmented input for short fixed-length codes (one-time passwords, 2FA, PINs).

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { InputOTP } from "@garn/ui/input-otp"`
- **Polymorphism:** `renderProp`

## Overview
InputOTP collects a short, fixed-length code — a one-time passcode, 2FA token, email/phone verification, or PIN — as a row of single-character slots. `InputOTP` owns the value (`maxLength` sets the slot count), `InputOTPGroup` clusters slots, `InputOTPSlot` is one cell by `index`, and `InputOTPSeparator` splits a long code (3 + 3). For general or variable-length text use Input; for a secret password use a password Input.

## When to use
Enter a short, fixed-length code — OTP, 2FA, email/phone verification, a PIN.

## When not to use
General or variable-length text (use input); long secrets/passwords (use input type=password).

## Do / Don't
- ✅ Set `maxLength` to the exact code length; group long codes (e.g. 3 + 3) with a separator.
- ✅ Use inputMode/pattern so mobile shows the right keyboard for numeric codes.
- ❌ Don't use it for free text.
- ❌ Don't omit a label — the slots aren't self-describing.

## Guidelines
**Use it only for short, fixed-length codes.** It's built for 4–8 known characters; anything variable-length or freeform belongs in a regular Input. Match `maxLength` to the real code and group long codes (e.g. 3 + 3) for readability.

**Make entry effortless.** Support paste-to-fill-all and auto-advance between slots, set the right `inputMode`/`autoComplete` (`one-time-code`) so mobile keyboards and SMS autofill work, and auto-submit when the last slot fills if that fits the flow.

**Keep it accessible and recoverable.** The field needs an accessible name, and the slots should read as one input to assistive tech, not N anonymous boxes. On a wrong code, show a clear error and let the user retry or request a new code rather than silently clearing.

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onChange` · string — The entered code. Controlled via `value` + `onChange`; `maxLength` sets the length.
- Selection: single.

## Anatomy

**Parts**
- `InputOTP` (`input-otp`) · required: Root — owns the value; `maxLength` sets how many characters/slots.
- `InputOTPGroup` (`input-otp-group`) · required: Visually groups a run of slots.
- `InputOTPSlot` (`input-otp-slot`) · required: One character cell; addressed by its `index`.
- `InputOTPSeparator` (`input-otp-separator`): A divider between groups (e.g. 3 + 3).

## Accessibility
- **Role:** textbox
- **0–9 / A–Z:** Fill the active slot and advance.
- **Backspace:** Clear and step back.
- **Paste:** Distributes a pasted code across the slots.
- **WCAG:** 1.3.1 Info and Relationships (A); 4.1.2 Name, Role, Value (A)
- A single underlying input drives the slots; label it (aria-label / a Label).
- **Focus:** The active slot shows the shared field-surface focus treatment (foreground/40 edge + neutral ring) and a blinking caret; focus stays on the single input.
- **Contract (warn):** Give the OTP input an accessible label (aria-label or a <label>). — _when the InputOTP has no aria-label / aria-labelledby / associated label_

## Tokens
- `slotSize` → `--garn-control-h-md` (air)

## Related
- **composes** → `utils`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `input` (when the value is ordinary, variable-length text)

## Gotchas
- **Slots render but nothing accepts input / wrong count.** — Missing `maxLength`, or the number of InputOTPSlot indexes doesn't match it. → Set `maxLength` and render exactly that many InputOTPSlots with indexes 0…maxLength-1.

## Examples
- **basic** (canonical): A 6-digit code split 3 + 3.

---

# Input

> A single-line text field — with optional in-field leading/trailing slots and built-in clear, password-reveal, and loading affordances.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Input } from "@garn/ui/input"`

## Overview
Input is the single-line text field — the most-used control in any form. In garn it's not a bare `<input>`: it renders the **shared field surface** (the same `appearance` × `size` system as Select, Textarea, and Combobox), so every text control in a form lines up to the same height, radius, and focus ring at a given density. The `appearance` axis sets how much the field asserts itself — `outline` for the default bordered field, `soft` for a filled rest state, `ghost` for a borderless field that only reveals its edge on interaction.

Beyond the bare field, Input ships the affordances you'd otherwise re-build every time: `leading`/`trailing` slots for an icon or unit, a built-in **clear** button, a password **reveal** toggle, a **loading** spinner, and an error treatment that reddens the border and ring when `aria-invalid` is set. Reach past Input only when the data isn't a single line of text — a long message wants Textarea, a fixed-length code wants InputOTP, a choice wants Select or Combobox.

## When to use
Collect a single line of freeform text — name, email, search query, etc. Add a leading/trailing slot for an icon or unit, or the built-in clearable / password-reveal / loading affordances.

## When not to use
Multi-line text (use a textarea); choosing among fixed options (use select or radio-group); a boolean (use checkbox or switch); removable/selectable chips (use Tag).

## Do / Don't
- ✅ Pair every input with a label (visible <label htmlFor> preferred).
- ✅ Set the right `type` (email, password, search, number…) so the keyboard and validation fit; pair `revealable` with type=password and the right autoComplete.
- ✅ Use `leading`/`trailing` for in-field icons/units; reach for the built-in `clearable` / `loading` rather than hand-building affordances.
- ✅ Reflect validation with aria-invalid + a described error message.
- ❌ Don't rely on the placeholder as the label — it disappears on focus.
- ❌ Don't hand-set height/padding; the size variant + --garn-control-* tokens own the grid.
- ❌ Don't use leading/trailing for outside-attached addons with merged borders (a https:// cell, a flanking Select) — that's a future InputGroup.

## Guidelines
**Always pair an Input with a Label.** A placeholder is not a label — it vanishes on focus and fails screen readers. Use the `label` component (or Form's wiring) so clicking the text focuses the field and the accessible name is announced. Reserve the placeholder for an *example* of the expected value, not the field's name.

**Let the field surface carry sizing — don't hand-pad.** Pick a `size` rung and the control-height tokens handle the rest; adding `px-*`/`h-*` utilities breaks alignment with the sibling controls and the density modes. If a field looks too tall or short next to its neighbors, it's almost always a stray height utility, not the token.

**Signal validity through state, not color alone.** Set `aria-invalid` on error so the built-in red border + ring and the error-icon slot engage together, and wire the message via `aria-describedby` (Form does this for you). Use `leading`/`trailing` for units and adornments ($, %, a search icon) rather than baking them into the value.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `cancelLabel` | `string` | — | no | Accessible name for the cancel button. |
| `clearable` | `boolean` | — | no | Show a clear button when the field is non-empty; Escape also clears. |
| `clearLabel` | `string` | — | no | Accessible name for the clear button. |
| `hidePasswordLabel` | `string` | — | no | Accessible name for the reveal toggle when the password is visible. |
| `leading` | `React.ReactNode` | — | no | Decorative or interactive content rendered inside the field, before the text. |
| `loading` | `boolean` | — | no | Show a trailing spinner and mark the field aria-busy. |
| `onCancel` | `() => void` | — | no | When loading, make the spinner a cancel button (spinner → ✕ on hover/focus) that calls this. |
| `onClear` | `() => void` | — | no | Fires after the field is cleared (button or Escape). |
| `onRevealedChange` | `(revealed: boolean) => void` | — | no | Fires when the reveal toggle flips (controlled or uncontrolled). |
| `revealable` | `boolean` | — | no | For a password field, render a show/hide toggle that swaps the input type. |
| `revealed` | `boolean` | — | no | Controlled reveal state (pair with `onRevealedChange`); omit for uncontrolled. |
| `showPasswordLabel` | `string` | — | no | Accessible name for the reveal toggle when the password is hidden. |
| `trailing` | `React.ReactNode` | — | no | Decorative or interactive content rendered inside the field, at the trailing edge (after the built-in affordances). |

_Plus 309 inherited native `<input>` attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onChange` · string — Pass `value` + `onChange` for controlled; `defaultValue` for uncontrolled. `clearable` observes this to show the clear button only when non-empty.
- Selection: single.

## Anatomy
- `input-root`: The focus-within wrapper that becomes the visible control surface when the field is enriched (slots / affordances / invalid / loading). Absent on the bare fast path, where the <input> is the root. Styled by `className`.
- `input`: The native <input> — always the focus/value target; ref and native props land here.
- `input-leading`: In-field leading content (a decorative icon, a unit, or an interactive control). Clicking empty padding / a decorative icon focuses the field.
- `input-trailing`: The trailing zone — the built-in affordances (error-icon · reveal · clear · spinner/cancel), then custom `trailing` content at the outer edge, so an edge-pinned control (e.g. NumberField's stepper) always sits last.
- `input-error-icon`: The auto danger glyph shown when aria-invalid (decorative / aria-hidden; the error is conveyed by aria-invalid + the described message).
- `input-reveal`: The password show/hide toggle (revealable + type=password) — a labelled button with aria-controls + a polite live-region announcement.
- `input-clear`: The clear button (clearable) — shown only when non-empty; Escape also clears, focus stays in the field.
- `input-loading`: The trailing spinner for plain `loading`.
- `input-cancel`: Cancellable loading (loading + onCancel) — a button that shows the spinner and cross-fades to a ✕ on field hover / keyboard focus.

## Accessibility
- **Role:** textbox
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A); 4.1.3 Status Messages (AA)
- Associate a visible <label> (htmlFor) or provide aria-label / aria-labelledby — the placeholder is not a label.
- Reflect validation with aria-invalid (+ an aria-describedby error message); the auto error glyph is decorative (aria-hidden).
- The clear button is a real <button> with an accessible name ('Clear', via clearLabel); it is keyboard-reachable, clears + keeps focus in the field, and Escape clears too.
- The password reveal toggle is a <button aria-controls> with a Show/Hide label swap (not aria-pressed); a visually-hidden aria-live=polite region announces the state, and the type is forced back to password on form submit.
- Loading sets aria-busy on the field; the spinner is aria-hidden. With onCancel the cancel button is named (cancelLabel) and keyboard-operable.
- Leading/trailing slots keep the field a single click target — clicking empty padding or a decorative icon focuses the input, while a real button/link inside a slot still works.
- **Focus:** Border darkens (foreground/40) on any focus; keyboard focus adds a 2px neutral ring (foreground/15). Affordance buttons carry their own focus ring.
- **Contract (warn):** Give every input an accessible label (a <label htmlFor>, or aria-label/aria-labelledby). — _when no associated <label htmlFor>, aria-label, or aria-labelledby_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)
- `borderColor` → `--garn-foreground`
- `iconInset` → `--garn-control-icon-inset`
- **Internal (never externalize):** `--in-px`

## Related
- **composes** → `utils`
- **composes** → `field-variants`
- **composes** → `field-surface` (when enriched fields render the wrapped path on the shared FieldSurface host)
- **composes** → `spinner`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `textarea` (when the value spans multiple lines)
- **alternativeTo** → `select` (when the value is one of a fixed set of options)

## Recipes
- **labeled-field** — A labeled text field — the canonical form row. _(use when collecting a single line of text in a form)_
- **search-field** — A search box — a leading magnifier + a clear button. _(use when filtering or searching a list)_
- **password-field** — A password field with a show/hide toggle. _(use when entering a password or secret)_

## Gotchas
- **Typing does nothing / React warns about a controlled input.** — Passing `value` without `onChange` makes the input read-only. → Use `defaultValue` for uncontrolled, or pass both `value` and `onChange`.
- **The password reveal toggle never appears.** — `revealable` only renders the toggle for a password field. → Set type="password" alongside `revealable`.
- **The clear button never shows.** — Clear is gated by `clearable` AND a non-empty value (and not while disabled/readOnly/loading). → Pass `clearable` and ensure the field has a value (controlled or uncontrolled).
- **The loading spinner isn't cancellable.** — Cancel is derived from the `onCancel` handler. → Pass `onCancel` with `loading`; the spinner becomes a ✕ on field hover / keyboard focus.
- **`className` doesn't style the border / fill on an enriched field.** — When the field is enriched it renders a wrapper; `className` styles that wrapper (the visible control), while ref + native props target the inner <input>. → Expected — style the control via className; reach the input via ref / native props.

## Examples
- **basic** (canonical): Default text input.
- **appearances** (playground): outline · soft · ghost.
- **sizes** (playground): xs · sm · md · lg · xl.
- **labeled** (canonical): Input with an associated label.
- **slots** (edge-case): Leading icon, trailing unit, and an interactive trailing control.
- **search** (edge-case): Leading search icon + clearable.
- **clearable** (edge-case): A clear button (Escape clears, focus retained).
- **password** (edge-case): A password field with a reveal toggle.
- **loading** (edge-case): A spinner, and a cancellable loading field.
- **invalid** (edge-case): aria-invalid — danger edge + auto error glyph.
- **disabled** (edge-case): A disabled field.

---

# Kbd

> Displays a keyboard key or shortcut as a keycap.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Kbd } from "@garn/ui/kbd"`

## Overview
Kbd renders a keyboard key or shortcut inline as a small keycap — in menus, tooltips, command hints, and docs. `appearance` is `default` (muted fill) or `ghost` (transparent for quieter hints), and a `KbdGroup` chains keys into a combo (⌘ K). It's display-only: it shows a shortcut, it doesn't capture or bind one — wire the actual key handler separately.

## When to use
Show a keyboard key or shortcut inline — menus, tooltips, command hints, docs.

## When not to use
To capture key presses or for editable input — Kbd is display-only.

## Do / Don't
- ✅ Use KbdGroup for multi-key shortcuts and pass the separator as children.
- ✅ Keep a keycap to one or two glyphs.
- ❌ Don't put long text in a keycap.
- ❌ Don't rely on Kbd alone to convey an actionable shortcut to assistive tech.

## Guidelines
**Use Kbd to display a shortcut, never to capture input.** It's a visual keycap, not an input — pair it with a real keyboard handler (and a DropdownMenuShortcut is also display-only). For editable text use Input.

**Show the platform's real keys.** Render ⌘ on macOS and Ctrl on Windows/Linux rather than a single hardcoded combo, and use the conventional glyphs (⌘ ⇧ ⌥ ⏎). Group multi-key combos with `KbdGroup` so they read as one shortcut.

**Keep it quiet and legible.** Use `ghost` inside dense menus and tooltips where a filled keycap would shout; reserve `default` for docs and standalone hints. Don't pile shortcut hints onto every control — surface them where discovery actually helps.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"default" \| "ghost"` | `default` | no |  |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |

_Plus 280 inherited native `<kbd>` attributes._

## Variants
- **appearance** (default `default`): `default`, `ghost`
- **size** (default `md`): `sm`, `md`, `lg`

## Anatomy
- `kbd`: The native <kbd> keycap.

**Parts**
- `KbdGroup` (`kbd-group`): Lays out a sequence of keys (⌘ + K, or “g then i”); pass the separators (+ / then) as children.

## Accessibility
- Renders native <kbd> (phrasing content); it is display-only.
- Convey the actionable shortcut where it matters (e.g. in the menu item's accessible name) — Kbd alone isn't announced as a shortcut.

## Tokens
- `background` → `--garn-muted` (identity)
- `foreground` → `--garn-muted-foreground` (identity)

## Related
- **composes** → `utils`
- **pairsWith** → `button` (when as a trailing shortcut hint)

## Gotchas
- **Separators in a shortcut look wrong or are missing.** — KbdGroup doesn't insert separators; consumers control phrasing. → Pass the “+” or “then” between <Kbd> children yourself.

## Examples
- **basic** (canonical): A single keycap.
- **shortcut** (playground): A multi-key shortcut via KbdGroup.
- **ghost** (playground): Quiet inline appearance.

---

# Label

> An accessible caption that names a form control.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** primitive
- **Import:** `import { Label } from "@garn/ui/label"`

## Overview
Label captions a form control so clicking the text focuses the control and assistive tech announces its accessible name. It's the connective tissue of every form: Input, Select, Checkbox, Radio, Switch, and Textarea all expect one. It is not a general text style — for section titles use a heading, for help text use a description element.

## When to use
Caption a form control so clicking the text focuses it and screen readers announce its name.

## When not to use
Section headings or non-control text — use a heading or plain text, not a <label>.

## Do / Don't
- ✅ Set `htmlFor` to the control's id (or wrap the control in the label).
- ✅ Keep labels short and persistent — don't rely on a placeholder as the label.
- ❌ Don't use a label as a generic text style.
- ❌ Don't leave a label unassociated from any control.

## Guidelines
**Associate every label with its control.** Use `htmlFor`/`id` (or wrap the control) so the link is real, not just visual proximity — that's what makes the text a click target and gives the field its name. An unassociated label is invisible to screen readers.

**Keep labels short, persistent, and in sentence case.** A few words naming the field, always visible — don't rely on a placeholder that disappears on focus. Mark optionality explicitly ("(optional)") rather than assuming required-by-default.

**Don't borrow the label for styling.** If you want bold body text or a section heading, use the right element; a stray `<label>` with no control is an accessibility smell. Put requirements and examples in a separate description, not baked into the label.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |

_Plus 283 inherited native `<label>` attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`

## Anatomy
- `label`: The <label> element.

## Accessibility
- **Role:** label
- **WCAG:** 1.3.1 Info and Relationships (A); 3.3.2 Labels or Instructions (A)
- Associate with a control via `htmlFor`={control id}, or by wrapping the control.
- **Contract (warn):** Associate the label with a control (htmlFor matching the control id, or wrap it). — _when the label has no `htmlFor` and does not wrap a control_

## Related
- **composes** → `utils`
- **pairsWith** → `input`
- **pairsWith** → `checkbox`
- **pairsWith** → `radio-group`
- **pairsWith** → `select`
- **pairsWith** → `switch`
- **pairsWith** → `textarea`

## Examples
- **basic** (canonical): Label associated with an input.
- **sizes** (playground): sm / md / lg.

---

# List

> A general-purpose content list — a stack of peer item rows (leading media · title/description · trailing meta/actions) for settings, inbox/notification feeds, file lists, search results, and resource lists. Terse or composed items, surfaces & dividers, grouped sections, truncation, expandable rows, per-row status/unread/tone, and three selection models (navigational overlay, a keyboard GridList for multi-select, a radiogroup for single) with select-all, range, and a bulk-action bar.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { List } from "@garn/ui/list"`
- **Polymorphism:** `asChild` (default element `<ul>`)

## Overview
List is the plain content collection — a stack of peer rows, each a leading-media · title/description · trailing-meta/actions row. `List.Item` is one row (terse props or composed slots); reach for it for settings rows, inbox/notification feeds, file lists, search results, and member/resource lists. It scales from an inert list to navigational rows (the whole row is one link) to full multi-select (a keyboard grid with select-all, range, and a bulk-action bar) — chosen by `selectionMode`, not a pile of booleans. For a term→value detail block use DataList; for a chronology use Timeline; for aligned columns of cells use Table; for a hierarchical tree use Tree.

## When to use
A vertical collection of peer item rows — settings rows, an inbox / notification feed, a file or resource list, search results, a member list. Use terse <List.Item> for the common row; compose the slots for rich rows; set `selectionMode` for selectable lists and `href`/`onActivate` for navigable ones.

## When not to use
A single entity's 'field: value' facts (use DataList); a chronology of events (use Timeline); a ranked top-N metric breakdown (use BarList); rows and columns where alignment/comparison matters (use Table); a hierarchical, multi-level tree (use Tree); picking one option from a popover (use Select / Combobox / Command).

## Do / Don't
- ✅ Give the list an accessible name (label / aria-label).
- ✅ Give every selectable row a stable `value`; drive selection with selectedKeys / onSelectionChange (or defaultSelectedKeys).
- ✅ Put inert meta in List.Trailing and focusable controls in List.Actions (they escape the navigational overlay).
- ✅ Use `size="xs"` for a condensed, dense list; use `density` for ambient tightening — they're different axes.
- ✅ Group long lists with List.Group; show List.Skeleton while loading and an <Empty> (via List.Empty) when cleared.
- ❌ Don't build a navigational row by wrapping the whole <li> in an <a> — use List.Title asChild (the overlay pattern) so nested actions stay valid.
- ❌ Don't forget `value` on selectable rows (they can't be selected or keyed without it).
- ❌ Don't rely on a row's `tone`/colour alone for status — pair it with text and the sr-only cues.
- ❌ Don't reach for List for a tree, a table, or a term:value block — use Tree / Table / DataList.

## Guidelines
**Pick the interaction model deliberately.** Leave rows inert for a read-only list; set `href`/`onActivate` for a navigable list (the whole row becomes one target); set `selectionMode` for selection — `single` is a radiogroup (a form choice), `multiple` is a keyboard grid (bulk actions). Give every selectable row a stable `value`.

**Use the axes, not ad-hoc styling.** `appearance` (plain/divided/card) sets the surface; `size` sets the row identity (`xs` for dense inbox/log rows); `density` tightens ambient spacing. Split inert metadata (List.Trailing) from focusable controls (List.Actions) so the tab model stays honest.

**Keep it accessible.** Name the list; don't nest interactives inside a navigational row's overlay — put secondary actions in List.Actions (they escape it); convey status with text/tone plus the sr-only cues, never colour alone. Long lists reorder via `reorderable` and virtualize via a windowing-library recipe, not built-in props.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"card" \| "divided" \| "plain"` | `plain` | no | Surface treatment: bare rows, hairline dividers, or one bordered card. |
| `selectionMode` | `"multiple" \| "none" \| "single"` | `none` | no | Selection model. `single` → radiogroup; `multiple` → keyboard grid. |
| `size` | `"lg" \| "md" \| "sm" \| "xs"` | `md` | no | Row height / type ladder — `xs` is a condensed, denser row (distinct from `density`). |
| `defaultSelectedKeys` | `string[]` | — | no | Uncontrolled initial selection. |
| `density` | `"compact" \| "spacious"` | — | no | Local density override; omit to inherit the ambient `[data-density]`. |
| `descriptionLines` | `number` | — | no | Lines a clamped description shows before ellipsis (default 2). |
| `disabledKeys` | `string[]` | — | no | Keys that cannot be selected (skipped by select-all and range). |
| `inset` | `boolean` | — | no | Align dividers past the leading gutter (only with `divided`/`card`). |
| `itemValues` | `string[]` | — | no | The item keys in order, for reorderable lists whose rows are WRAPPED in another component (child introspection only sees direct `List.Item`s — without this a wrapper-composed list reorders against an empty order). |
| `keyboardNavigation` | `boolean` | — | no | Opt a non-selectable list into the roving keyboard grid (e.g. a link list). |
| `label` | `React.ReactNode` | — | no | Convenience accessible name for the list. |
| `onReorder` | `(keys: string[]) => void` | — | no | Called with the next key order when a reorder drops. You reorder your data. |
| `onSelectionChange` | `(keys: string[]) => void` | — | no | Called with the next selection whenever it changes. |
| `reorderable` | `boolean` | — | no | Enable drag-reorder (each `List.Item` needs a `value`; add a `List.DragHandle`). Powered by the `useSortable` primitive — keyboard + pointer + announcements. |
| `selectedKeys` | `string[]` | — | no | Controlled selected keys (each `List.Item` needs a `value`). |
| `truncate` | `boolean` | — | no | Ambient truncation: clamp titles to 1 line and descriptions to `descriptionLines`. |

_Plus 279 inherited native `<ul>` attributes._

### `List.Item` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `actions` | `React.ReactNode` | — | no | Terse mode: trailing focusable controls (kept above the row overlay). |
| `defaultExpanded` | `boolean` | — | no | Uncontrolled initial expanded state. |
| `description` | `React.ReactNode` | — | no | Terse mode: the secondary text. |
| `detail` | `React.ReactNode` | — | no | Terse mode: disclosure content revealed when the row is expanded. |
| `disabled` | `boolean` | — | no | Inert, non-selectable row. |
| `expandable` | `boolean` | — | no | Show a disclosure toggle that reveals `detail` / `List.ItemDetail`. |
| `expanded` | `boolean` | — | no | Controlled expanded state (pair with `onExpandedChange`). |
| `href` | `string` | — | no | Make the whole row a navigational link (the overlay pattern). |
| `leading` | `React.ReactNode` | — | no | Terse mode: the leading media (icon / avatar / thumbnail). |
| `onActivate` | `(event: React.MouseEvent) => void` | — | no | Make the whole row activate on click (rendered as a button overlay). |
| `onExpandedChange` | `(expanded: boolean) => void` | — | no | Called when the disclosure opens or closes. |
| `status` | `"error" \| "idle" \| "loading" \| "saving"` | — | no | Per-row liveness: loading/saving show a spinner; error tints the row danger. |
| `title` | `React.ReactNode` | — | no | Terse mode: the primary text (becomes the row's link when interactive). |
| `tone` | `"brand" \| "danger" \| "info" \| "neutral" \| "success" \| "warning"` | — | no | Status tone accent for the row (a leading bar). |
| `trailing` | `React.ReactNode` | — | no | Terse mode: inert trailing metadata (timestamp / badge / count). |
| `unread` | `boolean` | — | no | Emphasise an unread row (bold title + a leading dot). |
| `value` | `string` | — | no | Stable selection key — required for a row to participate in selection. |

_Plus 277 inherited native HTML attributes._

### `List.Title` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no | Render as the child element (e.g. a link, button, or heading), merging props. |

_Plus 280 inherited native HTML attributes._

### `List.Description` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `lines` | `number` | — | no | Clamp to N lines (default from the List's `descriptionLines`). |
| `truncate` | `boolean` | — | no | Clamp to a single line with an ellipsis. |

_Plus 280 inherited native HTML attributes._

### `List.Group` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `React.ReactNode` | — | no | Section header text. |
| `sticky` | `boolean` | — | no | Stick the header to the top of the scroll container while its run is visible. |

_Plus 281 inherited native HTML attributes._

### `List.SelectionBar` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `clearLabel` | `string` | — | no | Label for the clear-selection button (default "Clear"). |
| `renderCount` | `(count: number) => React.ReactNode` | — | no | Label template — `count` is the selected total (default "N selected"). |
| `selectAllLabel` | `string` | — | no | Label for the select-all control (default "Select all"). |

_Plus 280 inherited native HTML attributes._

### `List.Skeleton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `leading` | `boolean` | — | no | Show a leading media placeholder circle. |
| `lines` | `number` | — | no | Description placeholder lines (default 1). |
| `rows` | `number` | — | no | How many placeholder rows to render (default 3). |
| `size` | `ListSize` | — | no |  |

_Plus 280 inherited native HTML attributes._

## Variants
- **appearance** (default `plain`): `plain`, `divided`, `card`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`
- **selectionMode** (default `none`): `none`, `single`, `multiple`

## Anatomy
- `list`: The list — a <ul role=list> (or, in the keyboard grid, a <div role=grid>) carrying appearance/size/density/selection-mode/inset data-attrs. Named via label / aria-label / aria-labelledby.
- `list-label`: Optional convenience heading rendered above the list (when `label` is set).
- `list-row`: The horizontal content cell inside each item (leading · content · trailing · actions). Hosts padding, min-height, the tone accent, the hover/selected fill, and (in grid mode) role=gridcell.
- `list-selection`: The auto-rendered per-row selection control gutter (a Checkbox in `multiple`, a radio in `single`).
- `list-unread`: The leading unread gutter — a fixed-width slot reserved on every row whenever any row in the list is `unread`, so the icon column stays aligned; it paints the dot (+ an sr-only 'Unread' label) only on unread rows.
- `list-disclosure`: The chevron toggle on an `expandable` row — a real <button aria-expanded aria-controls>.
- `list-status`: The trailing Spinner shown while a row's `status` is loading / saving.

**Parts**
- `List.Item` (`list-item`) · required: One row — a <li> (or a <div role=row> in the keyboard grid). Dual-mode: terse (leading/title/description/trailing/actions) or composed children. Carries `value` (selection key), `disabled`, `href`/`onActivate` (navigational overlay), `expandable`/`detail`, `status`/`unread`/`tone`. Reflects data-selected / data-disabled / data-interactive / data-expanded / data-status / data-tone.
- `List.Leading` (`list-leading`): The leading media gutter (icon / avatar / thumbnail). Shrinks its glyph at size `xs`.
- `List.Content` (`list-content`): The text column (title + description), min-w-0 so it truncates.
- `List.Title` (`list-title`): The primary text. `asChild` to become the row's link/button (the navigational overlay) or a heading; bolds when the row is `unread`.
- `List.Description` (`list-description`): The secondary text; `truncate` clamps to one line, `lines` to N (default from the List's `descriptionLines`).
- `List.Trailing` (`list-trailing`): Inert trailing metadata (timestamp / badge / count) — pushed to the row's end, not a tab stop.
- `List.Actions` (`list-actions`): Trailing focusable controls (buttons / overflow menu). Sit above the navigational overlay; in grid mode their tabindex roves with the active row.
- `List.ItemDetail` (`list-item-detail`): The disclosure content an `expandable` row reveals (arbitrary content or a nested <List>). Wired to the toggle via aria-controls; hidden while collapsed.
- `List.Group` (`list-group`): A section run — a header over a nested list of its items (a rowgroup in grid mode), optionally `sticky`; AT announces a sub-list under the heading.
- `List.SelectionBar` (`list-selection-bar`): The bulk-action bar — a tri-state select-all control, the selected count (announced via a polite live region), a clear button, and a slot for bulk actions. Reads the selection from context.
- `List.Empty` (`list-empty`): An empty-state slot — drop a garn <Empty> inside; a full-width list row.
- `List.Skeleton` (`list-skeleton`): A loading preset — rows of a leading circle + title/description placeholders in the row's geometry, hidden from AT.

## Accessibility
- **Role:** list
- **WCAG:** 1.3.1 Info and Relationships (A); 1.4.1 Use of Color (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- Presentational / navigational lists are a real <ul role=list> of <li role=listitem>; a navigational row uses the 'card-with-primary-action' overlay — List.Title becomes the sole <a>/<button> with an ::after spanning the row (one tab stop) while List.Actions sit above the overlay with their own tab stops (no nested interactives).
- `selectionMode="multiple"` (and `keyboardNavigation`) is a real ARIA grid: a <div role=grid aria-multiselectable> of <div role=row aria-selected> rows, each wrapping a <div role=gridcell>. A grid CANNOT be built from <ul>/<li> because ARIA forbids role=row on <li>, so grid mode forks the element types.
- The grid roves row focus with a roving tabindex (one row tabbable at a time): Arrow Up/Down, Home/End, PageUp/PageDown move focus; type-ahead jumps to a title; Space toggles the focused row; Shift+Arrow / Shift+Click extend a range; ⌘/Ctrl+A selects all; Escape clears; Enter activates a navigational row. In-row controls (checkbox, link, actions) rove with the active row so Tab steps through the active row only.
- `selectionMode="single"` flips the <ul> to role=radiogroup, the <li> wrappers take role=presentation, and each row renders a roving role=radio (Arrow keys move + select). It is a single-choice form control, not a grid.
- The bulk-action bar (List.SelectionBar) has a tri-state select-all Checkbox and announces the selected count via a polite live region; disabled keys are skipped by select-all and range.
- An expandable row's disclosure is a real <button aria-expanded aria-controls>; the revealed List.ItemDetail is wired by aria-controls (no role=region — an unnamed region is an anti-pattern).
- Per-row status: loading/saving set aria-busy and show a Spinner; the row tone is a decorative accent (error implies the danger tone) — never the sole signal. Give the list an accessible name via `label`, `aria-label`, or `aria-labelledby` (dev-warns if missing).
- **Focus:** Inert/navigational rows aren't focusable — only the title link and List.Actions are. The keyboard grid puts a roving tabindex on the rows (active row = 0, others = -1) and roves the active row's in-row controls; the radiogroup roves its radios. Every focusable control keeps a 2px --garn-ring focus ring.
- **Contract (warn):** Give the List an accessible name via `label`, `aria-label`, or `aria-labelledby`. — _when a List has no `label`, `aria-label`, or `aria-labelledby`_
- **Contract (warn):** Give every selectable List.Item a stable `value` so it can be selected and keyed. — _when selectionMode is not `none` and a List.Item has no `value`_

## Tokens
- `rowGap` → `--garn-gap-stack` (air)
- `rowHeight` → `--garn-control-h-md` (identity)
- `surfaceRadius` → `--garn-radius`
- `toneAccent` → `--garn-badge-neutral-bold` · brandable
- **Internal (never externalize):** `--list-inset`

## Related
- **composes** → `utils`
- **composes** → `checkbox` (when an auto-rendered per-row Checkbox drives `multiple` selection and the tri-state select-all)
- **composes** → `spinner` (when a row whose `status` is loading/saving shows a Spinner)
- **slotAccepts** → `avatar` (when a List.Leading hosts an avatar for a person/resource row)
- **slotAccepts** → `badge` (when a List.Trailing shows a status/label badge)
- **slotAccepts** → `button` (when a List.Actions row hosts buttons / an overflow menu)
- **slotAccepts** → `empty` (when an empty list renders an Empty inside List.Empty)
- **slotAccepts** → `inline-edit` (when a List.Title asChild hosts an InlineEdit to rename the row in place)
- **pairsWith** → `context-menu` (when a row is wrapped in a ContextMenu for right-click actions)
- **pairsWith** → `pagination` (when a long list is paged (a recipe — no built-in pagination prop))
- **pairsWith** → `scroll-area` (when a height-constrained list gets its own styled scrollbar)
- **alternativeTo** → `data-list` (when the content is one entity's field:value facts rather than a collection of peer rows)
- **alternativeTo** → `table` (when rows share columns where alignment and comparison matter)
- **alternativeTo** → `timeline` (when the rows are events in time rather than peer content)

## Recipes
- **content-list** — A plain content list of leading · title/description · trailing rows. _(use when showing a vertical collection of peer item rows)_
- **multi-select-list** — A selectable list with checkboxes, select-all, range, and a bulk-action bar. _(use when the user selects several rows to act on them in bulk)_
- **navigation-list** — A keyboard-navigable list of links (whole-row targets) with a trailing action. _(use when arrowing through a list of navigable rows)_

## Gotchas
- **Building a multi-select list and expecting <ul>/<li role=row> — or axe flags role=row on <li>.** — A real ARIA grid can't be built from <ul>/<li> (ARIA forbids role=row on <li>). → Nothing to do — `selectionMode="multiple"`/`keyboardNavigation` auto-forks to div[role=grid] > div[role=row] > div[role=gridcell]; inert/single modes stay <ul>/<li>.
- **Rows can't be selected / selection does nothing.** — Selectable rows need a stable `value`; without it a row can't be keyed (a dev warning fires). → Give every selectable <List.Item> a `value`, and drive state with selectedKeys / onSelectionChange (or defaultSelectedKeys).
- **Wrapping the whole row in an <a> to make it clickable — nested buttons break.** — A link around the <li> nests the action buttons inside the anchor (invalid interactives). → Use `href`/`onActivate` (or List.Title asChild) — the title becomes the sole link with a row-spanning ::after overlay, and List.Actions escape it.
- **Reaching for `density="compact"` to get a smaller, denser list.** — `density` only tightens ambient spacing; the row's identity is the `size` axis. → Use `size="xs"` for the condensed row look (shorter rows, xs type); `density` is an orthogonal ambient tweak.
- **Using List for a tree, a table, or a field:value block.** — List is a flat collection of peer rows. → Use Tree for hierarchy, Table for aligned columns, DataList for a single entity's field:value facts.

## Examples
- **basic** (canonical): Terse rows — leading icon + title + description + a trailing badge.
- **appearances** (edge-case): plain · divided (inset) · card surfaces.
- **navigational** (edge-case): An inbox — whole-row links (the overlay) with a trailing kebab action.
- **selection-multiple** (edge-case): A keyboard grid — checkboxes, select-all, range, and a bulk-action bar.
- **selection-single** (edge-case): A radiogroup — single-choice rows (a plan picker).
- **grouped** (edge-case): List.Group section headers over nested lists.
- **sizes** (edge-case): The size ladder — xs (condensed) · sm · md · lg.
- **truncation** (edge-case): Title clamped to one line, description to N lines.
- **loading-empty** (edge-case): List.Skeleton while loading; an Empty state via List.Empty.
- **expandable** (edge-case): Expandable rows — a disclosure chevron reveals List.ItemDetail.
- **status** (edge-case): Per-row status — unread, saving (spinner), error (retry), and a tone accent.
- **keyboard-grid** (edge-case): A navigable link list (keyboardNavigation) — arrow keys + type-ahead.
- **compose-in** (edge-case): Compose-in — a right-click ContextMenu and an InlineEdit title.

## Source map

Regions in `list.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–16 (15 lines) — React, Radix Slot, icons, shared hooks
- `types` L17–56 (40 lines) — component overview doc + shared axis aliases
- `utils` L57–123 (67 lines) — tree-walk helpers + controllable boolean hook
- `context` L124–188 (65 lines) — List and ListItem context contracts
- `root` L189–644 (456 lines) — List root: props, selection, keyboard, role fork
- `variants` L645–692 (48 lines) — per-size row styling maps + tone accents
- `item` L693–1021 (329 lines) — ListItem row: dual-mode anatomy, grid row fork
- `drag-handle` L1022–1074 (53 lines) — reorder grip wired to the sortable primitive
- `selection` L1075–1155 (81 lines) — per-row checkbox + roving radio controls
- `parts` L1156–1338 (183 lines) — item slots: leading, content, title, actions, detail
- `group` L1339–1414 (76 lines) — section run; rowgroup fork in grid mode
- `selection-bar` L1415–1494 (80 lines) — bulk-action bar with tri-state select-all
- `empty` L1495–1529 (35 lines) — grid-aware empty-state row
- `skeleton` L1530–1589 (60 lines) — loading placeholder rows preset
- `exports` L1590–1640 (51 lines) — compound List namespace assembly + exports

---

# Menubar

> A desktop-style horizontal bar of pull-down menus.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** navigation
- **Import:** `import { Menubar } from "@garn/ui/menubar"`

## Overview
Menubar is the persistent application menu bar — File / Edit / View … — for a desktop-like app or editor. `Menubar` is the bar (role=menubar), each `MenubarMenu` a top-level menu with its `MenubarTrigger` label and portaled `MenubarContent` pull-down of items. It's a specialized pattern for command-dense, desktop-style apps; for a single button menu use DropdownMenu, and for website navigation use NavigationMenu.

## When to use
A persistent application menu bar (File / Edit / View …) for a desktop-like app or editor.

## When not to use
Website navigation (use navigation-menu or plain links); a single button-triggered menu (use dropdown-menu); a few actions (use a button group).

## Do / Don't
- ✅ Reserve it for app-style command organization; keep top-level labels short.
- ✅ Group and separate items; show shortcuts with MenubarShortcut (and bind them).
- ✅ Control checkbox/radio item state.
- ❌ Don't use a menubar for site navigation.
- ❌ Don't overload it with rarely-used commands.
- ❌ Don't rely on MenubarShortcut to bind keys.

## Guidelines
**Reserve the menubar for genuinely app-like surfaces.** It belongs in editors and tools with many grouped commands; on a typical website it's the wrong metaphor (use NavigationMenu) and a single overflow menu is a DropdownMenu. Use the conventional menu names where they apply (File/Edit/View).

**Organize commands the way users expect.** Group related actions, separate sections, and surface shortcut hints with `MenubarShortcut` (display-only — bind the keys yourself). Keep destructive items distinct and avoid burying frequent actions deep.

**Honor the full keyboard model.** Arrow keys move across the bar and within a menu, Esc closes, and roving focus follows APG — don't break it. Once one menu is open, hovering the others should open them, matching desktop behavior.

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The value of the currently open menu (Menubar root). Each MenubarMenu can carry its own `value`. CheckboxItem/RadioGroup hold their own item-level state.
- Selection: single.

## Anatomy

**Parts**
- `Menubar` (`menubar`) · required: The persistent bar (role=menubar); owns which menu is open.
- `MenubarMenu` · required: One top-level menu within the bar.
- `MenubarTrigger` (`menubar-trigger`) · required: The top-level label that opens its menu.
- `MenubarContent` (`menubar-content`) · required: The portaled pull-down for a menu.
- `MenubarItem` (`menubar-item`): An action item; `inset` for alignment.
- `MenubarCheckboxItem` (`menubar-checkbox-item`): A toggleable item (controlled via `checked` + `onCheckedChange`).
- `MenubarRadioGroup`: Groups radio items; owns the selected `value`.
- `MenubarRadioItem` (`menubar-radio-item`): A single-select item inside a RadioGroup.
- `MenubarLabel` (`menubar-label`): A non-interactive section heading; `inset` for alignment.
- `MenubarSeparator` (`menubar-separator`): Divider between groups.
- `MenubarShortcut` (`menubar-shortcut`): Right-aligned shortcut hint (display only).
- `MenubarSub`: A submenu container (Sub / SubTrigger / SubContent).
- `MenubarSubTrigger` (`menubar-sub-trigger`): Opens a submenu; `inset` for alignment.
- `MenubarSubContent` (`menubar-sub-content`): The nested submenu surface.

## Accessibility
- **Role:** menubar (APG: menubar)
- **ArrowLeft / ArrowRight:** Move between top-level menus.
- **ArrowDown / Enter / Space:** Open the focused menu.
- **ArrowUp / ArrowDown:** Move between items in an open menu.
- **Escape:** Close the open menu.
- **Home / End:** Jump to the first / last item.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- The bar is role=menubar with roving focus; each menu is role=menu, items are menuitem / checkbox / radio.
- Show real shortcuts with MenubarShortcut and actually bind the keys yourself (the hint is display only).
- **Focus:** Roving focus across the bar and into open menus.

## Tokens
- `barHeight` → `--garn-control-h-md` (air)
- `menuGap` → `--garn-gap-inline` (air)
- `itemMinHeight` → `--garn-control-h-md` (air)

## Related
- **composes** → `utils`
- **slotAccepts** → `kbd` (when rendering shortcut hints in MenubarShortcut)
- **alternativeTo** → `dropdown-menu` (when you need a single button-triggered menu, not a persistent bar)
- **alternativeTo** → `navigation-menu` (when this is website navigation rather than app commands)

## Gotchas
- **Reaching for a menubar to build a website's top nav.** — Menubar is the app-menu (File/Edit/View) pattern, not site navigation. → Use navigation-menu (or a nav + links) for site navigation; reserve menubar for app commands.

## Examples
- **basic** (canonical): File and Edit menus with items and shortcuts.

---

# MultiSelect

> A multi-value / tag input — an editable field-surface holding several values as removable chips, with a searchable stay-open listbox, per-option chip tone, opt-in free-text tags (Create row, paste + delimiter tokenize, dedupe), a per-token validation lifecycle, a max cap, and a '+N' overflow reveal.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { MultiSelect } from "@garn/ui/multi-select"`

## Overview
MultiSelect picks SEVERAL values, held as removable chips in an editable field with a searchable, stay-open listbox. It's the composite between single-select Combobox and display-only Tag/TagGroup: the cmdk search input lives in the field beside the chips, so Backspace removes the last token and typing filters in place. Feed it a data-driven `options` array (each with an optional `tone`) or compound `MultiSelect.Item` children. Opt into `allowCustomValue` for free-text tags — a 'Create …' row, comma/paste tokenizing, case-insensitive dedupe, and an optional `validate` that marks bad tokens as danger chips. Use `max` to cap the count and `visibleLimit` to collapse overflow into a '+N' reveal.

## When to use
Select several values held as removable chips — from a searchable list, or as free-text tags. Use the `options` prop or compound MultiSelect.Item children; opt into `allowCustomValue` for tags (paste/comma tokenize, dedupe, validate); cap with `max` and collapse overflow with `visibleLimit`.

## When not to use
Choosing ONE value (use Combobox for searchable, Select for short lists, BadgeSelect for a badge picker); a fixed handful of always-visible toggles (use Checkbox or a Toggle group); display-only chips with no picker/entry (use Tag / TagGroup); free-form single-line text (use Input).

## Do / Don't
- ✅ Label the field (aria-label / aria-labelledby / id + <label>) — the placeholder isn't a name.
- ✅ Give every MultiSelect.Item a stable, unique `value`; add a `tone` to tint status/priority chips.
- ✅ Enable `allowCustomValue` + `onCreate` for tag/label/recipient inputs where new values are valid.
- ✅ Add `validate` when tokens must be well-formed (e.g. emails) — invalid tokens become danger chips with a reason.
- ✅ For server-side search, set `filter={false}`, drive `inputValue` + `loading`, and feed pre-filtered `options`.
- ✅ Use `max` to enforce a limit and `visibleLimit` (or `hideSelectedOptions`) to keep dense fields compact.
- ❌ Don't treat the search text as a value — `inputValue` is the transient filter; `value` is the committed array.
- ❌ Don't use MultiSelect for a single choice — that's Combobox / Select.
- ❌ Don't reach past the chip: it's a composed Tag inside a roving TagGroup (the component wires removal + roving).
- ❌ Don't disable the live announcer or the focus ring — they're the a11y contract.

## Guidelines
**Reach for MultiSelect when the answer is a set.** For one value use Combobox (searchable) or Select (short list); for a fixed handful of visible toggles use a checkbox/Toggle group; for display-only chips use Tag/TagGroup. MultiSelect earns its weight when users assemble a list from a long/searchable or free-text source (recipients, labels, skills).

**Choose the mode deliberately.** Without `allowCustomValue` it's a pick-from-list MultiSelect; with it, it's a tags input — set `onCreate` to persist new values and `validate` when tokens must be well-formed (emails). Drive `inputValue` + `filter={false}` for server-side search.

**Keep it accessible and compact.** Label the field (the placeholder isn't a name); the roving chip strip, multiselectable listbox, and live announcements are the a11y contract. Use `visibleLimit` (or `hideSelectedOptions`) to keep dense fields from ballooning.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"md" \| "sm" \| "xs"` | `md` | no |  |
| `"aria-invalid"` | `"false" \| "true" \| boolean` | — | no |  |
| `"aria-label"` | `string` | — | no |  |
| `"aria-labelledby"` | `string` | — | no |  |
| `allowCustomValue` | `boolean` | — | no | Allow committing free text that matches no option (tags mode). |
| `children` | `React.ReactNode` | — | no | Compound `MultiSelect.Item` / `MultiSelect.Group` children. |
| `className` | `string` | — | no | Applied to the field surface. |
| `clearable` | `boolean` | — | no | Show a clear-all button when any value is selected. Default true. |
| `clearLabel` | `string` | — | no |  |
| `closeOnSelect` | `boolean` | — | no | Keep the listbox open after a pick (the multi-select default). |
| `contentClassName` | `string` | — | no | Applied to the popup content. |
| `createLabel` | `(inputValue: string) => React.ReactNode` | — | no |  |
| `defaultInputValue` | `string` | — | no |  |
| `defaultOpen` | `boolean` | — | no |  |
| `defaultValue` | `string[]` | — | no |  |
| `disabled` | `boolean` | — | no |  |
| `emptyText` | `React.ReactNode` | — | no | No-results content (used with the `options` prop; ignored if a child Empty is given). |
| `filter` | `MultiSelectFilter \| false` | — | no | Match function, or `false` to disable client filtering (feed pre-filtered `options` for server-side search). Defaults to an accent-insensitive fuzzy match. |
| `hideSelectedOptions` | `boolean` | — | no | Drop chosen options from the list (they already ride as chips). |
| `id` | `string` | — | no |  |
| `inputValue` | `string` | — | no | In-field search text (controlled) — drive this for server-side search. |
| `loading` | `boolean` | — | no | Pending state: a spinner + a loading row + `aria-busy` + an announced "loading". |
| `loadingText` | `string` | — | no |  |
| `max` | `number` | — | no | Cap the number of selected values; further picks are blocked + announced. |
| `name` | `string` | — | no | Name for the hidden inputs mirroring each value on form submit. |
| `onClear` | `() => void` | — | no |  |
| `onCreate` | `(value: string) => void` | — | no | Called for each free-text value committed; also renders a "Create …" row. |
| `onInputValueChange` | `(inputValue: string) => void` | — | no |  |
| `onOpenChange` | `(open: boolean) => void` | — | no |  |
| `onValueChange` | `(value: string[]) => void` | — | no |  |
| `open` | `boolean` | — | no | Popover open state (controlled). |
| `options` | `MultiSelectOption[]` | — | no | Data-driven options — an alternative to compound children (one or the other). |
| `overflowLabel` | `string` | — | no | Accessible name for the "+N" overflow reveal popover. |
| `placeholder` | `string` | — | no | Field text when nothing is selected. |
| `ref` | `React.Ref<HTMLInputElement>` | — | no | The search input's ref. |
| `required` | `boolean` | — | no |  |
| `searchLabel` | `string` | — | no | Accessible name for the search input (role=combobox). |
| `splitChars` | `string[]` | — | no | Characters that commit the current text as a token (on keydown) and split a pasted string into multiple tokens. Tags mode only. Default `[","]`. |
| `toggleLabel` | `string` | — | no | Accessible label for the chevron toggle affordance. |
| `validate` | `(value: string) => boolean \| string \| Promise<boolean \| string>` | — | no | Validate a value as it is added: `true` accepts it, `false` rejects it with a generic reason, a string rejects it with that reason. May be async — the chip shows a pending spinner until it resolves, then a danger chip + reason on rejection. Runs on every added value (picked or free-text). |
| `value` | `string[]` | — | no | The selected values (controlled). |
| `visibleLimit` | `number` | — | no | Collapse chips past this count into a "+N" token that reveals the rest in a popover (each removable). Keeps the field compact in dense layouts. |

_Plus 3 inherited native `<input>` attributes._

### `MultiSelect.Item` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `description` | `React.ReactNode` | — | no | Secondary line under the label. |
| `leading` | `React.ReactNode` | — | no | Leading glyph; mirrors into the chip when this option is selected. |
| `textValue` | `string` | — | no | String used for chip display + matching when `children` is a non-string node. |
| `tone` | `"brand" \| "danger" \| "discovery" \| "info" \| "neutral" \| "success" \| "warning"` | — | no | Chip tone applied when this option is selected. |
| `value` | `string` | — | yes | Stable value toggled on select (required). |

_Plus 283 inherited native HTML attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string[] — The selected values (an array). Toggled by picking options, added by tags mode, removed by the chip ✕ / Backspace / clear-all.
- `inputValue` (controlled) / `defaultInputValue` (uncontrolled), `onInputValueChange` · string — The in-field SEARCH text — separate from `value`. Drive it for server-side search; it resets after a pick.
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Whether the listbox popover is open.
- Selection: multiple.

## Anatomy
- `multi-select`: The cmdk Command root that wraps the whole control (owns filtering + listbox keyboard model).
- `multi-select-field`: The editable field surface + Popover anchor — a min-height, wrapping box holding the chips + the input. Clicking anywhere on it (but a chip/button) focuses the input and opens the listbox.
- `multi-select-input`: The editable cmdk CommandInput (role=combobox) living in the field — the transient search AND the tags-mode entry point.
- `multi-select-clear`: The clear-all button (a real sibling, centered on the first row); shown when clearable + any value.
- `multi-select-toggle`: The chevron toggle — a labelled button (kept out of the tab order) that opens/closes the listbox on click; the input owns keyboard expansion.
- `multi-select-overflow`: The '+N' token shown when the count exceeds `visibleLimit`; opens the overflow reveal.
- `multi-select-overflow-list`: The popover listing the hidden tokens (each removable).
- `multi-select-list`: The scrollable filtered listbox (cmdk CommandList, aria-multiselectable).
- `multi-select-loading-row`: The pending row — a spinner + loadingText while async results resolve.
- `multi-select-create`: The free-text 'Create …' row, shown in tags mode when the trimmed search matches no option/value.
- `multi-select-item-match`: The <mark> wrapping the matched substring in an option label.

**Parts**
- `MultiSelect.Item` (`multi-select-item`) · required: A selectable option row — leading + label (+ description) + a check when chosen. Requires a stable `value`; optional `tone` tints the chip when selected.
- `MultiSelect.Group` (`multi-select-group`): A labelled section of options (cmdk CommandGroup with a heading).
- `MultiSelect.Separator` (`multi-select-separator`): A divider between groups.
- `MultiSelect.Empty` (`multi-select-empty`): The no-results state — cmdk auto-renders it when the filtered count is 0 (or pass emptyText with the options prop).

## Accessibility
- **Role:** combobox (APG: combobox)
- **A–Z:** Type in the field to filter (accent-insensitive contains).
- **ArrowDown / ArrowUp:** Move the active option (opens the list if closed; tracked via aria-activedescendant, focus stays in the input).
- **Enter:** Toggle the active option, or commit the 'Create …' row (tags mode). The listbox stays open.
- **, / (splitChars):** Commit the current text as a token (tags mode); pasting a delimited string tokenizes all of it.
- **Backspace:** On an empty input, remove the last chip.
- **ArrowLeft:** At the caret start, move focus into the chip strip (the roving TagGroup).
- **ArrowLeft / ArrowRight / Home / End:** Rove between chips once focus is in the strip (logical, RTL-aware).
- **Delete / Backspace:** Remove the focused chip and move focus to its neighbour (or back to the input if none remain).
- **Escape:** Close the listbox; focus stays in the input.
- **WCAG:** 1.3.1 Info and Relationships (A); 1.4.1 Use of Color (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The in-field input is the real role=combobox (cmdk) with aria-expanded / aria-controls / aria-activedescendant / aria-autocomplete=list; the listbox is aria-multiselectable=true.
- Chosen options carry aria-selected=true (true membership — the vendored cmdk lets the consumer value through; the active row is conveyed via data-selected), a visible check, and an sr-only ', selected' appended to the accessible name.
- The selected tokens are a labelled role=grid (Tag TagGroup) with one roving tab stop; each chip's remove is a gridcell <button> named 'Remove {label}'.
- A visually-hidden aria-live region announces the result count / no-results / loading, plus token events — 'N added · M duplicate' on paste, 'Already added', and 'Maximum of N reached'.
- The chevron toggle is a labelled button kept out of the tab order (tabIndex=-1) — the input owns keyboard expansion; the listbox stays mounted while closed (hidden) so aria-controls never dangles.
- Invalid tokens are danger-toned with the failure reason on a leading warning icon's title.
- The placeholder is NOT an accessible name — label the field via aria-label, aria-labelledby, or an `id` paired with <label htmlFor>.
- **Focus:** Focus stays in the in-field input; the field border darkens (foreground/40) + a subtle ring via :has(input:focus-visible). ArrowLeft moves focus into the roving chip strip and removal returns it to the input.
- **Contract (warn):** Give the field an accessible name via aria-label, aria-labelledby, or an id + <label htmlFor>. — _when the MultiSelect field has no `aria-label`, `aria-labelledby`, or an `id` paired with a <label htmlFor> (the placeholder doesn't count)_

## Tokens
- `fieldMinHeight` → `--garn-control-h-md` (air)
- `fieldPaddingInline` → `--garn-control-px-md` (air)
- `itemMinHeight` → `--garn-control-h-md` (air)

## Related
- **composes** → `utils`
- **composes** → `field-surface` (when the field consumes the shared fieldSurface recipe (border/fill/focus, identical to Input/Combobox))
- **composes** → `tag` (when each selected value renders as a Tag inside a roving TagGroup)
- **composes** → `popover` (when the listbox + the overflow reveal live in Radix Popovers)
- **composes** → `spinner` (when loading + pending-token states show a Spinner)
- **composes** → `cmdk` (when the search input + filtered listbox are a cmdk Command (the vendored, boundary-patched engine in lib/cmdk — no npm dep))
- **pairsWith** → `label` (when a <Label htmlFor> names the field)
- **pairsWith** → `form` (when hidden inputs mirror each value on submit)
- **alternativeTo** → `combobox` (when only one value is needed (single-select searchable))
- **alternativeTo** → `tag` (when the chips are display-only with no picker / entry)
- **alternativeTo** → `select` (when a short single-choice list fits without search)

## Recipes
- **labeled-multi-select** — A labelled multi-value picker over a searchable option list. _(use when assembling several values from a long, searchable list in a form)_
- **tags-input** — Free-text tags — allowCustomValue with dedupe + delimiter/paste tokenizing. _(use when users type/paste arbitrary tokens (keywords, labels, recipients))_
- **validated-recipients** — An email/recipient field — allowCustomValue + validate marks bad tokens as danger chips. _(use when tokens must be well-formed (emails) before they count)_

## Gotchas
- **The value is a string, or only the last pick sticks.** — MultiSelect's value is an ARRAY (`string[]`), not a single string like Combobox. → Bind `value: string[]` + `onValueChange(next: string[])`; use `defaultValue={[]}` uncontrolled.
- **Typing a new value can't be committed as a tag.** — Free-text is opt-in; without it, only existing options toggle. → Set `allowCustomValue` (+ `onCreate` to persist). A 'Create …' row appears, and comma/paste tokenize.
- **Pasted or typed tokens aren't validated / bad ones still count.** — No `validate` provided, so every added value is accepted. → Pass `validate` (sync or async): return true to accept, or false/a string to reject — the chip turns into a danger token with the reason.
- **The search text becomes a chip / the selection resets.** — Conflating `value` (the committed array) with `inputValue` (the transient search). → Keep them separate — only drive `inputValue` for server-side search (`filter={false}` + `loading`).
- **Server results never show, or show double-filtered.** — The client fuzzy filter is still on top of your pre-filtered results. → Set `filter={false}`, drive `inputValue` + `loading`, and feed the already-filtered `options`.
- **Screen readers announce the field with no name.** — The placeholder is not an accessible name (a dev console warns). → Pass aria-label / aria-labelledby, or an `id` paired with <label htmlFor>.

## Examples
- **basic** (canonical): Controlled multi-select over a list of fruits.
- **with-label** (edge-case): A <Label htmlFor> wired to the field via id.
- **options** (edge-case): The data-driven `options` prop with leading glyphs.
- **grouped** (edge-case): Options grouped into labelled sections.
- **tones** (edge-case): Per-option `tone` — chips tint by status/priority.
- **tags** (edge-case): Free-text tags mode — allowCustomValue with a Create row.
- **emails** (edge-case): Validated recipients — validate marks bad tokens as danger chips; paste tokenizes.
- **max** (edge-case): A `max` cap that blocks further picks + announces.
- **overflow** (edge-case): `visibleLimit` collapses chips into a '+N' reveal.
- **appearances** (playground): outline · soft · ghost (shared field surface).
- **sizes** (edge-case): xs · sm · md field heights.
- **states** (edge-case): Disabled · invalid · loading.
- **hide-selected** (edge-case): hideSelectedOptions drops chosen rows from the list.

## Source map

Regions in `multi-select.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L3–42 (40 lines) — deps, icons, garn primitives
- `types` L43–126 (84 lines) — overview doc + size/tone maps + filter type
- `utils` L127–235 (109 lines) — fold/tokenize/textOf, Highlight, item collection
- `context` L236–255 (20 lines) — MultiSelect context + hook
- `item` L256–352 (97 lines) — MultiSelectItem row
- `parts` L353–398 (46 lines) — group / separator / empty
- `internal` L399–449 (51 lines) — cmdk live-status + active-scroll helpers
- `root` L450–1291 (842 lines) — MultiSelect field, listbox, tokens
- `exports` L1292–1315 (24 lines) — compound namespace + types

---

# Navigation Menu

> Primary site navigation with optional dropdown panels.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** navigation
- **Import:** `import { NavigationMenu } from "@garn/ui/navigation-menu"`
- **Polymorphism:** `asChild`

## Overview
NavigationMenu is primary site navigation with optional rich dropdown panels — a top header nav or mega-menu. `NavigationMenu` owns which item is open and hosts a shared Viewport; each `NavigationMenuItem` is either a direct link or a `NavigationMenuTrigger` + `NavigationMenuContent` panel for grouped destinations. It's for navigating *to* places; for menus of *actions* use DropdownMenu/Menubar, and for in-page section switching use Tabs.

## When to use
Primary site navigation with optional rich dropdown panels — a top header nav or mega-menu.

## When not to use
Application command menus (use menubar); a single button-triggered menu (use dropdown-menu); in-page view switching (use tabs); a plain list of links (just use a <nav> + links).

## Do / Don't
- ✅ Use NavigationMenuLink (asChild) for real navigation, and navigationMenuTriggerStyle() so links match triggers.
- ✅ Reserve NavigationMenuTrigger/Content for items that actually reveal a panel.
- ✅ Mark the current destination with `active`; label the nav if the page has more than one.
- ❌ Don't use it for in-page tabs or app command bars.
- ❌ Don't put a trigger on items that are just links.
- ❌ Don't bury primary destinations behind triggers unnecessarily.

## Guidelines
**Use it to navigate, not to run actions.** Its items lead to pages/sections; commands belong in a DropdownMenu or Menubar. Keep the top level short and label items by destination, not feature jargon.

**Keep dropdown/mega panels scannable.** When an item expands a panel, group links under clear headings and keep the panel shallow — a wall of links is as hard to use as no menu. Mark the current section so users know where they are.

**Make every destination reachable by keyboard and on mobile.** Triggers open on focus/Enter and the panel is navigable; don't gate links behind hover-only reveals. Provide a responsive collapse (a Sheet/drawer) so the nav still works on small screens.

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The value of the open top-level item. Controlled via `value` + `onValueChange`; uncontrolled otherwise.
- Selection: single.

## Anatomy

**Parts**
- `NavigationMenu` (`navigation-menu`) · required: Root — owns which item is open and renders the shared Viewport.
- `NavigationMenuList` (`navigation-menu-list`) · required: The horizontal list of top-level items.
- `NavigationMenuItem` (`navigation-menu-item`) · required: One top-level entry — a link, or a trigger + content panel.
- `NavigationMenuTrigger` (`navigation-menu-trigger`): Opens an item's dropdown panel (with a rotating chevron).
- `NavigationMenuContent` (`navigation-menu-content`): The dropdown panel; rendered into the shared Viewport.
- `NavigationMenuLink` (`navigation-menu-link`): A navigation link (asChild to wrap your router's Link). Apply navigationMenuTriggerStyle() to match trigger styling.
- `NavigationMenuIndicator` (`navigation-menu-indicator`): The little arrow pointing at the active trigger.
- `NavigationMenuViewport` (`navigation-menu-viewport`): The shared, animated container all panels render into (rendered by the Root).
- `navigationMenuTriggerStyle`: A cva() class helper (no variants) so plain links can match the trigger's look.

## Accessibility
- **Role:** navigation
- **Tab:** Move between links and triggers.
- **Enter / Space / ArrowDown:** Open the focused item's panel.
- **Escape:** Close the open panel.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.5 Multiple Ways (AA); 4.1.2 Name, Role, Value (A)
- The Root is a <nav> landmark; items are links or disclosure triggers that reveal aria-controlled panels.
- Use NavigationMenuLink for real navigation (asChild to wrap a router Link); mark the current page with `active`.
- Only use a trigger for items that reveal a panel — plain destinations are just links.
- **Focus:** Triggers and links show a focus ring; panels animate in the shared Viewport.

## Tokens
- `triggerHeight` → `--garn-control-h-md` (air)
- `listGap` → `--garn-gap-inline` (air)
- `motion` → `--garn-motion-base`

## Related
- **composes** → `utils`
- **slotAccepts** → `link` (when NavigationMenuLink asChild wraps a router Link)
- **alternativeTo** → `menubar` (when this is app command organization, not site navigation)
- **alternativeTo** → `tabs` (when switching between in-page views rather than navigating)

## Gotchas
- **A simple destination opens an empty/needless dropdown.** — It was built with a Trigger + Content instead of a plain link. → Use NavigationMenuLink (with navigationMenuTriggerStyle()) for plain destinations; reserve triggers for panels.
- **Client-side routing doesn't fire from a nav link.** — A raw <a> was used instead of the router's Link. → Wrap your router's Link with NavigationMenuLink asChild.

## Examples
- **basic** (canonical): A trigger with a link panel plus a plain top-level link.

---

# NumberField

> A typed numeric input — Intl-formatted (decimal/currency/percent/unit) with a stepper, spinbutton a11y, and a raw number value.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { NumberField } from "@garn/ui/number-field"`

## Overview
NumberField is the typed numeric control — the number-side sibling of TimeField. It reuses **Input** wholesale (the wrapped focus surface, `appearance` × `size`, leading slot, and the invalid treatment), adding a trailing **+/− stepper** and the number logic. Under the hood it is a `type="text"` input with `role="spinbutton"` — never native `type="number"` — so it can **format** the value with `Intl.NumberFormat` (`formatOptions`: decimal, currency, percent, unit) while keeping the raw string editable while focused. The value is a real `number`: `min`/`max` **clamp** on blur, an explicit `step` **snaps** to the grid on blur, and stepping (↑/↓, PageUp/Down, Home/End, or the buttons) is float-safe and clamped.

Reach for a plain **Input** when the value is a code or identifier rather than a quantity, and a **Slider** when a coarse value is best chosen by dragging within a fixed range.

## When to use
Enter a quantity, price, percentage, or measurement by typing or stepping — with locale-correct formatting and a real number value.

## When not to use
A code/identifier that isn't a quantity (use Input); a coarse value best dragged within a range (use Slider); a one-time-code (use InputOTP).

## Do / Don't
- ✅ Pair with a label and pass `formatOptions` for currency/percent/unit.
- ✅ Set `min`/`max` (and `step` when snapping) to constrain the value.
- ✅ Hold the value in state (or `defaultValue`) and read it as a `number`.
- ❌ Don't reach for native <input type="number"> — it can't format and has unstyleable steppers.
- ❌ Don't hand-set height/padding — the size variant owns the grid.
- ❌ Don't rely on the placeholder as the label.

## Guidelines
**Pair with a Label** and pass `formatOptions` that matches the quantity (currency, percent, a unit) — it drives both display and parsing. **Set `min`/`max`** to clamp and to disable the stepper at each bound, and an explicit **`step`** when the value should snap to a grid (percent defaults to 0.01). **Read the value as a `number`** (percent as its fraction); on form submit a hidden input carries the raw number. Let the field surface own sizing — pick a `size` rung rather than hand-padding.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `decrementLabel` | `string` | — | no | Accessible name for the decrement button. |
| `defaultValue` | `number` | — | no | Initial value for the uncontrolled case. |
| `formatOptions` | `Intl.NumberFormatOptions` | — | no | `Intl.NumberFormatOptions` — decimal · currency · percent · unit. |
| `hideStepper` | `boolean` | — | no | Hide the +/− stepper buttons (keyboard stepping still works). |
| `incrementLabel` | `string` | — | no | Accessible name for the increment button. |
| `largeStep` | `number` | — | no | PageUp/PageDown increment. Defaults to `step * 10`. |
| `locale` | `string` | — | no | BCP-47 locale for formatting/parsing. Defaults to the runtime locale. |
| `max` | `number` | — | no | Upper bound — clamped on blur/step; increment disables at it. |
| `min` | `number` | — | no | Lower bound — clamped on blur/step; decrement disables at it. |
| `onValueChange` | `(value: number \| undefined) => void` | — | no | Fires with the committed number (or `undefined` when cleared). |
| `step` | `number` | — | no | ArrowUp/ArrowDown increment. Defaults to 0.01 for percent, else 1. |
| `value` | `number` | — | no | The numeric value. Controlled via `value` + `onValueChange`. |

_Plus 312 inherited native `<input>` attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · number — The numeric value. Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`. Fires `undefined` when cleared. For percent style the value is the fraction (0.2 ↔ "20%").
- Selection: single.

## Anatomy
- `input-root`: Reuses Input's wrapped field surface (border, focus-within ring, invalid/disabled). Styled by `className`.
- `input`: The <input type="text"> carrying role="spinbutton"; ref + the raw editable string land here.
- `number-field-stepper`: The trailing increment/decrement column.
- `number-field-increment`: Steps the value up by `step` (disabled at max).
- `number-field-decrement`: Steps the value down by `step` (disabled at min).

## Accessibility
- **Role:** spinbutton
- **ArrowUp / ArrowDown:** Step the value by `step`.
- **PageUp / PageDown:** Step the value by `largeStep` (default `step` × 10).
- **Home / End:** Jump to `min` / `max` (when set).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The field is role=spinbutton with aria-valuenow / aria-valuemin / aria-valuemax and an aria-valuetext carrying the formatted display.
- Give the field an accessible label — <label htmlFor>, aria-label, or aria-labelledby.
- The stepper buttons are out of the tab order (keyboard users step with the arrows); they stay labelled for pointer + screen-reader users.
- Reflect validation with aria-invalid + a described error message.
- **Focus:** Inherits Input's focus surface (border darkens on focus; keyboard focus adds a neutral ring).
- **Contract (warn):** Give every number field an accessible label. — _when no associated <label htmlFor>, aria-label, or aria-labelledby_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)

## Related
- **composes** → `input`
- **composes** → `use-controllable-state`
- **composes** → `number-parse`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `input` (when the value is a code/identifier, not a quantity)
- **alternativeTo** → `slider` (when a coarse value is best chosen by dragging within a range)

## Gotchas
- **A percent field's value looks 100× too small (0.2, not 20).** — Percent style stores the fraction; Intl renders 0.2 as "20%". → Treat the value as a fraction (0.2 = 20%); multiply by 100 only for your own display outside the field.
- **Typed decimals get rounded on blur.** — An explicit `step` turns on snap-to-grid on blur. → Drop `step` (or widen it) if you want free decimal entry; `step` is opt-in for plain numbers.
- **The form submits a formatted string like "$1,499.99".** — That's the display; the value layer is separate. → Pass `name` — NumberField renders a hidden input carrying the raw number.
- **The stepper arrows are invisible on a ghost field until you interact with it.** — By design — `appearance="ghost"` is a seamless field that only surfaces on hover/focus, so the stepper follows suit. → This is expected; keyboard stepping (↑/↓) still works even when the buttons are hidden. Use `outline` or `soft` if the stepper should always be visible.

## Examples
- **basic** (canonical): A labelled quantity field with a floor of 0.
- **currency** (edge-case): Currency formatting via formatOptions.
- **percent** (edge-case): Percent style — the value is the fraction, displayed as a percentage.
- **bounded** (edge-case): min/max clamp; the stepper disables at each bound.
- **states** (edge-case): Disabled and invalid.
- **affordances** (edge-case): clearable and loading — both render to the left of the stepper, which always stays pinned at the trailing edge.
- **appearances** (edge-case): outline · soft · ghost — the shared field-appearance axis, inherited from Input.
- **sizes** (edge-case): xs · sm · md · lg · xl.

---

# Pagination

> Page-by-page navigation across a long, splittable set of results.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** navigation
- **Import:** `import { Pagination } from "@garn/ui/pagination"`

## Overview
Pagination splits a long, ordered result set into pages and lets users move between them. `Pagination` is the `nav` landmark, `PaginationContent` the list, `PaginationLink` each page number (`active` sets `aria-current`), with `PaginationPrevious`/`PaginationNext` controls. Use it when users benefit from stable, addressable pages (search results, tables); for continuously-growing feeds, infinite scroll or a "load more" button often fits better.

## When to use
Split a long, ordered result set into pages and let users move between them.

## When not to use
A continuous feed (use infinite scroll / load-more); a handful of items that fit on one screen; a linear wizard (use a stepper).

## Do / Don't
- ✅ Mark the current page's link with `active` (sets aria-current="page" and data-active).
- ✅ Collapse long ranges with PaginationEllipsis rather than rendering every number.
- ✅ Wrap your router's Link via PaginationLink for real client navigation.
- ❌ Don't render every page number for huge ranges — collapse the middle.
- ❌ Don't show pagination for a single page of results.
- ❌ Don't leave the boundary ambiguous — convey when Previous/Next are unavailable.

## Guidelines
**Choose pagination when position and addressability matter.** Numbered pages let users bookmark, jump, and sense the set's size — ideal for results and data tables. For exploratory, endless feeds, consider load-more/infinite scroll instead.

**Mark the current page and disable the ends.** `active` carries `aria-current="page"`; disable Previous on page one and Next on the last page rather than letting them dead-end. Show enough context (first/last, neighbors, an ellipsis) without a giant row of numbers.

**Keep it a labelled, keyboard-navigable nav.** It's a navigation landmark — every control needs an accessible name ("Go to page 3", "Next page"). Pair it with a clear "N–M of T" indicator so users know where they are in the set.

## Props
### `PaginationLink` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean` | — | no | Marks the current page — `aria-current="page"` + a `data-active` reflect. |

_Plus 289 inherited native HTML attributes._

## Anatomy

**Parts**
- `Pagination` (`pagination`) · required: The <nav role="navigation" aria-label="pagination"> landmark.
- `PaginationContent` (`pagination-content`) · required: The list of page items (a <ul>).
- `PaginationItem` (`pagination-item`) · required: One list item wrapping a link or control.
- `PaginationLink` (`pagination-link`): A page-number link; `active` marks the current page (aria-current="page" + a `data-active` reflect). Styled via buttonVariants.
- `PaginationPrevious` (`pagination-previous`): Labeled "previous page" link.
- `PaginationNext` (`pagination-next`): Labeled "next page" link.
- `PaginationEllipsis` (`pagination-ellipsis`): Collapsed-range indicator; aria-hidden with an sr-only "More pages".

## Accessibility
- **Role:** navigation
- **Tab:** Move between page links and the previous/next controls.
- **Enter:** Follow the focused page link.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The root <nav> is labeled "pagination" so it's a distinct landmark.
- The active page link sets aria-current="page" (via `active`).
- Previous/Next carry their own aria-labels; the ellipsis is aria-hidden with an sr-only label.

## Tokens
- `itemGap` → `--garn-gap-inline` (air)
- `ellipsisSize` → `--garn-control-h-md` (air)

## Related
- **composes** → `utils`
- **composes** → `button`
- **slotAccepts** → `link` (when PaginationLink wraps a router Link / anchor)

## Gotchas
- **Screen readers don't announce which page is current.** — No PaginationLink was given `active`. → Pass `active` to the current page's link so it sets aria-current="page".

## Examples
- **basic** (canonical): Previous · 1 2 3 · ellipsis · Next, page 2 active.

---

# Popover

> Non-modal floating content anchored to a trigger — rich detail or a small form.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { Popover } from "@garn/ui/popover"`
- **Polymorphism:** `asChild`

## Overview
Popover floats a small, interactive surface anchored to a control without blocking the page behind it — a quick form, a settings cluster, a date picker. `Popover` owns open state, `PopoverTrigger` toggles it, and `PopoverContent` is the portaled surface (configurable `side`/`align`/`sideOffset`). Unlike a Dialog it's non-modal: the rest of the page stays live. For a non-interactive text hint use Tooltip; for a list of commands use DropdownMenu; for a focused, page-blocking task use Dialog.

## When to use
Show contextual detail or a small interactive form anchored to a control, without blocking the page.

## When not to use
A task that must be completed/acknowledged first (use dialog); a static text hint (use tooltip); a list of commands/actions (use dropdown-menu).

## Do / Don't
- ✅ Anchor to the control that opened it; keep the content compact.
- ✅ Allow click-away and Escape to dismiss.
- ❌ Don't put a long, blocking workflow in a popover — that's a dialog.
- ❌ Don't use a popover for a plain text hint — that's a tooltip.

## Guidelines
**Use a popover for interactive content, not a passive hint.** If the surface only shows a sentence of help, that's a Tooltip; reserve Popover for things the user clicks into. Open on click/press — never on hover, which makes the content impossible to reach.

**Keep it small and self-contained.** A popover is for one quick task; if it grows into a multi-section form or needs its own scroll, promote it to a Dialog or Sheet. Position it near its trigger and let it flip to stay on-screen rather than forcing a side.

**Preserve focus and dismissal.** Move focus into the content on open and return it to the trigger on close; Escape and outside-click should both dismiss. Give the content an accessible name when it isn't obvious from context.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen` (or just a PopoverTrigger).
- Selection: single.

## Anatomy

**Parts**
- `Popover` · required: Root — owns the open state.
- `PopoverTrigger` (`popover-trigger`) · required: The control that toggles the popover (asChild to wrap your own button).
- `PopoverContent` (`popover-content`) · required: The floating, portaled surface (side/align/sideOffset configurable).
- `PopoverAnchor` (`popover-anchor`): Optional positioning anchor when it differs from the trigger.

## Accessibility
- **Role:** dialog (APG: dialog (non-modal))
- **Enter / Space:** Toggle the popover from the trigger.
- **Escape:** Close and return focus to the trigger.
- **Tab:** Move through the content; focus is NOT trapped (non-modal).
- **WCAG:** 2.1.1 Keyboard (A); 2.4.3 Focus Order (A); 4.1.2 Name, Role, Value (A)
- Trigger gets aria-expanded / aria-controls; focus moves into the content on open and back on close.
- **Focus:** Non-modal: focus enters the content but the rest of the page stays interactive.

## Tokens
- `padding` → `--garn-pad-panel` (air)

## Related
- **composes** → `utils`
- **pairsWith** → `button` (when as the trigger)
- **alternativeTo** → `tooltip` (when the content is plain text and non-interactive)
- **alternativeTo** → `dropdown-menu` (when the content is a list of actions/commands)
- **alternativeTo** → `dialog` (when the task must block the page until done)

## Recipes
- **anchored-form** — A small form (e.g. quick settings) anchored to a button. _(use when a quick, non-blocking edit anchored to a control)_

## Examples
- **basic** (canonical): Trigger → anchored content panel.

---

# Progress

> A determinate bar showing how far a known-length task has advanced.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** feedback
- **Import:** `import { Progress } from "@garn/ui/progress"`

## Overview
Progress shows the determinate progress of a task with a known percentage — an upload, an install, multi-step completion — as a filled bar with a `tone` that can shift at thresholds, and it doubles as a capacity meter (storage used, quota). Use it when you can report a real fraction; for an indeterminate wait use a Spinner, and to hold a content shape while loading use a Skeleton.

## When to use
Show determinate progress of a task with a known percentage — upload, install, multi-step completion.

## When not to use
An indeterminate wait with no measurable percentage (use a spinner); a static ratio or score (use plain text or a meter).

## Do / Don't
- ✅ Pass `value` as 0–100 and give the bar an accessible name (aria-label or aria-labelledby).
- ✅ Pair it with a visible percentage or step label when the number matters.
- ❌ Don't use Progress for unknown-duration loading — that's a Spinner.
- ❌ Don't animate a fake value just to look busy.

## Guidelines
**Use Progress only when you know the fraction.** A determinate bar that actually advances reassures users; faking it (or snapping 0→100) erodes trust. For unknown-duration work, a Spinner is the honest choice.

**Pair the bar with a real number and context.** Show the percentage or "3 of 5", and label what's progressing — a bar alone leaves users guessing. As a capacity meter, make the tone shift meaningful (e.g. warning as a quota fills).

**Wire it for assistive tech.** Expose the value via the progress role (`aria-valuenow`/min/max) and an accessible name so the state is announced, not just shown. Keep updates smooth and avoid jarring jumps; respect reduced-motion on any animation.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `format` | `(value: number, max: number) => string` | — | no | Format the read-out + `aria-valuetext`. Default: rounded percent. |
| `indeterminate` | `boolean` | — | no | Force indeterminate even with no value (the unknown-progress mode). |
| `label` | `React.ReactNode` | — | no | A visible caption (rendered in a ProgressLabel; becomes the accessible name). |
| `showValue` | `boolean` | — | no | Show the value read-out beside the label. |
| `size` | `"lg" \| "md" \| "sm"` | — | no | Track height. |
| `thresholds` | `ProgressThreshold[]` | — | no | Ascending value→tone map for `tone="auto"`. Default: 0 success · 75 warning · 90 danger. |
| `tone` | `"auto" \| ProgressTone` | — | no | `neutral | brand | success | warning | danger | info`, or `"auto"` to drive the tone from the value via `thresholds`. Default `brand`. |
| `value` | `number` | — | no | 0–`max`. `null`/`undefined` → indeterminate (or set `indeterminate`). |

_Plus 282 inherited native `<div>` attributes._

## Anatomy
- `progress`: The track (rounded rail with a subtle primary tint).
- `indicator`: The fill bar; width follows `value` via a translateX transform. Internal — no data-slot.

## Accessibility
- **Role:** progressbar
- **WCAG:** 1.3.1 Info and Relationships (A); 4.1.2 Name, Role, Value (A)
- Radix sets aria-valuenow / aria-valuemin / aria-valuemax from `value` and `max`.
- The bar carries no text — give it an accessible name via aria-label or aria-labelledby.

## Related
- **composes** → `utils`
- **alternativeTo** → `spinner` (when the wait is indeterminate (no measurable percentage))

## Gotchas
- **The bar renders but is announced with no name.** — Progress has no text content of its own. → Pass aria-label (or aria-labelledby pointing at a visible label).

## Examples
- **basic** (canonical): A labeled determinate bar at 60%.

---

# Radio Group

> Choose exactly one option from a small set of visible choices.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { RadioGroup } from "@garn/ui/radio-group"`

## Overview
RadioGroup lets a person pick exactly one option from a few mutually-exclusive choices that are all worth showing at once (≈2–5). `RadioGroup` owns the selected value and propagates `size` to each `RadioGroupItem`. Once the list grows past a handful or the options stop fitting on screen, switch to Select; for a binary on/off setting, a Switch or single Checkbox reads better than two radios.

## When to use
Pick one option from a few (≈2–5) mutually exclusive choices, all visible at once.

## When not to use
A long list (use select); independent on/off items (use checkbox); a single instant setting (use switch).

## Do / Don't
- ✅ Give every RadioGroupItem a unique value and a clickable Label.
- ✅ Pre-select a sensible default with defaultValue when one exists.
- ❌ Don't use radios for many options — switch to a select past ~5.
- ❌ Don't use radios for multi-select — that's checkboxes.

## Guidelines
**Always show one option as selected.** A radio group should have a sensible default rather than starting empty — an all-blank group makes "no choice" look like a valid state when it usually isn't. Give each `RadioGroupItem` a unique `value` and its own Label.

**Keep options parallel and exhaustive.** Phrase choices in the same grammatical form and at the same level of specificity, and cover the full space (add an "Other"/"None" when the set isn't complete). Order them logically — by magnitude, frequency, or convention — not at random.

**Don't use radios for multi-select or instant actions.** Several selectable items → Checkboxes; a setting that takes effect immediately → Switch. Arrow keys move selection within the group (roving focus), so don't nest interactive controls inside an item.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |

_Plus 288 inherited native HTML attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The selected option's value. Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`.
- Selection: single.

## Anatomy

**Parts**
- `RadioGroup` (`radio-group`) · required: Root — owns the selected value and the `size` (propagated to items).
- `RadioGroupItem` (`radio-group-item`) · required: One option; needs a unique `value`. Pair each with a Label.

## Accessibility
- **Role:** radiogroup (APG: radio group)
- **Tab:** Move focus into the group (lands on the selected, or first, radio).
- **ArrowUp / ArrowDown / ArrowLeft / ArrowRight:** Move to and select the next/previous option.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- role=radiogroup wraps role=radio items; label the group (aria-labelledby / a Label).
- **Focus:** Roving tabindex; arrow keys move + select within the group.
- **Contract (warn):** Label the group and each option (a Label per item, plus a group label). — _when the group has no accessible name (aria-labelledby / aria-label) and items have no labels_

## Tokens
- `size` → `--garn-box-md` (identity)
- `fill` → `--garn-brand-solid` · brandable
- `ring` → `--garn-ring` · brandable

## Related
- **composes** → `utils`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `select` (when there are many options or space is tight)
- **alternativeTo** → `checkbox` (when more than one option may be selected)

## Recipes
- **labeled-radio-group** — A labeled set of mutually-exclusive options. _(use when choosing one of a few visible options)_

## Gotchas
- **Selecting an option does nothing.** — Passing `value` without `onValueChange` makes the group controlled and frozen. → Use `defaultValue` for uncontrolled, or pass `value` + `onValueChange`.

## Examples
- **basic** (canonical): Three labeled options, one preselected.

---

# Rating

> A star/score control for collecting or displaying a rating.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { Rating } from "@garn/ui/rating"`

## Overview
Rating collects or shows a score on a small fixed scale — the five-star review, the thumbs-worth of a helpfulness vote, a difficulty out of ten. It is one component in two modes: interactively it's a radiogroup of real (hidden) radios, so keyboard, focus and form submission are native; read-only it's an image that announces a fractional average and clips the fill to any decimal. Symbols fill *cumulatively* up to the value, with a live hover-preview that reverts on leave. When the scale is large or the exact number matters, a number field or slider is clearer; for a single yes/no reaction, use a Toggle.

## When to use
Collect or display a score on a small fixed scale — a star review, a helpfulness vote, a difficulty rating — where cumulative symbols read faster than a number.

## When not to use
A precise value on a large scale (use a number input); an approximate position on a continuum (use slider); a single on/off reaction (use toggle or switch).

## Do / Don't
- ✅ Give the interactive rating an accessible name (aria-label / aria-labelledby).
- ✅ Use `readOnly` + `precision={0.5}` to display fractional averages like 4.3.
- ✅ Keep it clearable for optional input, or `required` to force a choice in a form.
- ✅ Show a count or word-scale label alongside, driven by `onHoverChange`.
- ❌ Don't leave an interactive rating unlabeled.
- ❌ Don't use a rating for a large or precise scale — reach for a number input.
- ❌ Don't recolour the symbols for decoration; tone should carry meaning.

## Guidelines
**Name the control.** An interactive rating is a radiogroup and needs an accessible name — pass `aria-label` ("Rate this product") or `aria-labelledby`. It warns in dev when unnamed.

**Pick the right mode.** Collecting input → interactive (keep it clearable so people can un-rate, or set `required` in a form to force a choice). Showing an aggregate like 4.3★ → `readOnly` with `precision={0.5}`; read-only clips the fill to the exact decimal and announces "4.3 of 5".

**Surface the meaning.** Pair the stars with a count or a word scale ("Terrible…Excellent") driven by `onHoverChange`, and keep `max` small (5 is the convention) — a 10- or 100-point scale is better as a number field.

**Tone is intent, not decoration.** Amber (`warning`) is the default star; use another tone only when it carries meaning (a red heart for favourites). Empty symbols stay neutral grey by design.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |
| `tone` | `"brand" \| "danger" \| "discovery" \| "info" \| "neutral" \| "success" \| "warning"` | `warning` | no |  |
| `clearable` | `boolean` | — | no | Re-selecting the current value resets it to 0 (ignored when `required`). |
| `defaultValue` | `number` | — | no | Uncontrolled initial rating. |
| `disabled` | `boolean` | — | no |  |
| `emptyIcon` | `React.ReactNode` | — | no |  |
| `getValueText` | `(value: number, max: number) => string` | — | no | Spoken label for a value — defaults to `"{value} of {max}"`. |
| `icon` | `React.ReactNode` | — | no | Filled symbol; also the empty symbol unless `emptyIcon` is given. |
| `max` | `number` | — | no | Number of symbols. |
| `name` | `string` | — | no | Groups the radios and names the form field. |
| `onHoverChange` | `(value: number \| null) => void` | — | no | Fires with the previewed value on hover, `null` on leave. |
| `onValueChange` | `(value: number) => void` | — | no | Fires with the committed rating; `0` when cleared. |
| `precision` | `0.5 \| 1` | — | no | Selection granularity — whole or half symbols. |
| `readOnly` | `boolean` | — | no | Render-only: no inputs, `role="img"`, fractional fill for averages. |
| `required` | `boolean` | — | no | Form validation — a value must be picked; implies not clearable. |
| `value` | `number` | — | no | Controlled rating (0…max, in `precision` steps). |

_Plus 277 inherited native HTML attributes._

## Variants
- **tone** (default `warning`): `neutral`, `brand`, `info`, `success`, `warning`, `danger`, `discovery`
- **size** (default `md`): `sm`, `md`, `lg`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · number — The rating, 0…`max` in `precision` steps (0 = unrated). Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`. `onHoverChange` reports the pointer-preview value separately.
- Selection: single.

## Anatomy
- `rating`: The control. Interactive → role=radiogroup (needs an accessible name); read-only → role=img announcing the score. Carries `tone` + `size`.
- `symbol`: One star per `max` — a muted base glyph with a tone-filled overlay clipped to the fill fraction (internal). The focus ring frames the whole symbol.
- `radio`: A visually-hidden native radio per selectable step (two per symbol at half precision) plus a 'no rating' clear anchor — the source of native keyboard + form submission (internal).

## Accessibility
- **Role:** radiogroup (APG: radiogroup)
- **ArrowRight / ArrowUp:** Select the next value (native radio behaviour).
- **ArrowLeft / ArrowDown:** Select the previous value.
- **Home:** Jump to the lowest value.
- **End:** Jump to `max`.
- **PageUp / PageDown:** Nudge by one whole symbol.
- **WCAG:** 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- Interactive: role=radiogroup built from real (visually-hidden) radios — give it an accessible name via aria-label or aria-labelledby.
- Each radio is named for its value (e.g. "3 of 5"); a 'No rating' radio anchors the empty state (omitted when `required`).
- Read-only: role=img with an aria-label announcing the score (e.g. "4.3 of 5").
- **Focus:** A focused radio rings its whole symbol.
- **Contract (warn):** Give the interactive rating an accessible name (aria-label or aria-labelledby). Warns in dev. — _when an interactive Rating has no aria-label / aria-labelledby_

## Tokens
- `fill` → `--garn-badge-warning-bold` · brandable
- `ring` → `--garn-ring` · brandable
- `symbolSize` → `--garn-box-lg` (identity)
- **Internal (never externalize):** `--r-fill`, `--r-size`

## Related
- **composes** → `utils`
- **pairsWith** → `form`
- **pairsWith** → `field`
- **alternativeTo** → `slider` (when the value is an approximate position on a continuum)
- **alternativeTo** → `number-field` (when a precise value on a large scale must be typed)

## Gotchas
- **Type error or nothing selected when passing an array to `value`.** — Rating's value is a single number, not an array like Slider. → Pass a number — `value={3}` / `defaultValue={2.5}`.
- **Console warns that the rating has no accessible name.** — An interactive rating is a radiogroup and needs a name. → Add `aria-label` or `aria-labelledby` (read-only mode names itself from the score).
- **A fractional value like 4.3 renders as a whole/half star only.** — Fractional fill is a read-only display concern; interactive selection snaps to `precision`. → Use `readOnly` for averages (any decimal fills exactly); `precision={0.5}` only affects what a user can pick.
- **`required` never blocks form submission.** — The default clear anchor keeps a value (0) checked, satisfying required. → Set `required` — it drops the clear anchor so an unrated field is invalid (and implies not-clearable).

## Examples
- **basic** (canonical): A five-star rating with an accessible name.
- **controlled** (playground): Controlled value with a hover-driven word-scale label.
- **half** (playground): Half-star precision.
- **read-only** (playground): Read-only fractional average (4.3) with a review count.
- **required** (edge-case): Required in a form — no clear anchor, native validation, submits its value.
- **tones** (playground): The tone axis, plus a custom heart icon.

---

# Resizable

> Split panels the user can drag to resize, horizontally or vertically.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** layout
- **Import:** `import { Resizable } from "@garn/ui/resizable"`

## Overview
Resizable lets users rebalance space between adjacent regions — a sidebar/content split, an editor/preview, a multi-pane layout. `ResizablePanelGroup` sets the `direction`, each `ResizablePanel` takes `defaultSize`/`minSize`/`maxSize` (percentages), and `ResizableHandle` is the draggable divider (`withHandle` shows a grip). Use it where users genuinely benefit from controlling proportions; for fixed structure, a normal grid/flex layout is simpler.

## When to use
Let users rebalance space between adjacent regions — a sidebar/content split, an editor/preview, multi-pane layouts.

## When not to use
An overlay panel (use sheet/drawer); collapsible content (use collapsible/accordion); a fixed layout that shouldn't be user-resized (use CSS grid/flex).

## Do / Don't
- ✅ Give the PanelGroup a height (panels fill it) and set `defaultSize`/`minSize` per panel.
- ✅ Use `withHandle` so the divider is visible and grabbable.
- ✅ Persist sizes with the library's `autoSaveId` / onLayout when the split should be remembered.
- ❌ Don't ship a resizable layout the keyboard can't operate — the handle is keyboard-resizable; keep it reachable.
- ❌ Don't use it for overlay or collapsible patterns.
- ❌ Don't nest deep panel trees that confuse the resize model.

## Guidelines
**Add resizing only where users will actually want it.** Power layouts — code editor + preview, list + detail — benefit; most pages don't, and a draggable seam everywhere adds complexity for no gain. Set sensible defaults so it's usable before anyone drags.

**Constrain panels with min/max sizes.** Floors and ceilings stop a pane from collapsing to nothing or swallowing the layout; pick limits that keep every region functional. Persist the user's chosen split where it makes sense.

**Make the handle reachable and operable.** Show a grip affordance, give the separator an accessible name, and support keyboard resizing (arrow keys) — not just pointer drag. Keep the hit area comfortable on touch.

## Anatomy

**Parts**
- `ResizablePanelGroup` (`resizable-panel-group`) · required: The container; `direction` sets horizontal vs vertical and flows into the handle styling.
- `ResizablePanel` (`resizable-panel`) · required: One pane; size with `defaultSize` / `minSize` / `maxSize` (percentages).
- `ResizableHandle` (`resizable-handle`): The draggable divider between panels; `withHandle` shows a grip affordance.

## Accessibility
- **Role:** separator
- **ArrowLeft / ArrowRight:** Resize a horizontal handle.
- **ArrowUp / ArrowDown:** Resize a vertical handle.
- **Enter:** Collapse / expand a collapsible panel.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A)
- The handle is a focusable separator with aria-valuenow/min/max — it's resizable by keyboard, not just drag.
- Use `withHandle` (or otherwise signal the divider) so the resize affordance is discoverable.
- **Focus:** The handle shows a ring and accepts arrow-key resizing.

## Related
- **composes** → `utils`
- **alternativeTo** → `sheet` (when the secondary region should overlay rather than share space)
- **alternativeTo** → `collapsible` (when you only need to show/hide a region, not resize it)

## Gotchas
- **Panels collapse to nothing or the group is invisible.** — The PanelGroup has no height (panels size relative to it). → Give the ResizablePanelGroup an explicit height (and use percentage `defaultSize`s).

## Examples
- **basic** (canonical): Two horizontal panels with a grip handle.

---

# Scheduler

> A day/week/month/agenda event-grid — a time-canvas that positions, packs and edits events, with timezone/DST-correct math and recurrence.

- **Status:** beta
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** layout
- **Import:** `import { Scheduler } from "@garn/ui/scheduler"`
- **Polymorphism:** `asChild` (default element `<div>`)

## Overview
Scheduler is a **time canvas**, not a date picker. In its day / week / work-week views it draws a vertical hour axis with day columns, slot lines, an all-day lane and a live now-line, and positions events by their start/end — packing overlapping events side-by-side. `view="month"` switches to a day-grid with multi-day **spanning bars**, and `view="agenda"` to a chronological list. It is a full editor: drag empty time to create, drag a block to move it (even across days), drag its edges to resize — by pointer *or* keyboard — with optimistic callbacks so you own the `events`. All time math flows through one `clock`, so a `timeZone` and DST transitions stay correct, and events with an `rrule` expand to occurrences for the visible span. For picking a single date, use `calendar`/`date-picker` — Scheduler can't shrink to that, and DayPicker can't stretch to this.

## When to use
Displaying and editing events against time — a day/week planner, a booking/availability grid, a team calendar, a room/resource schedule, or an agenda feed.

## When not to use
Picking a single date or range (use `date-picker` / `calendar` / `date-range` picker); a read-only month wall-calendar with no time axis (a `calendar` may suffice); a plain list of items with no temporal layout (use `list` / `table` / `timeline`).

## Do / Don't
- ✅ Keep `events` in your own state and apply the move/resize/range callbacks optimistically.
- ✅ Crop the band with `slotMinTime`/`slotMaxTime` and land the scroll with `scrollTime` (e.g. business hours).
- ✅ Give overlapping-heavy days a `maxStack` so dense clusters collapse into a “+N more”.
- ✅ Pass a `timeZone` when events are anchored to a fixed zone; pass `date`/`defaultDate` for SSR.
- ✅ Build a toolbar from `useScheduler` (or drive it via `apiRef`).
- ❌ Don't mutate the passed events in a callback and expect a re-render — update your source of truth.
- ❌ Don't hardcode event colors or positions — use `tone`/`appearance` and let the canvas place them.
- ❌ Don't remove the composed event accessible name inside a custom `renderEvent`.
- ❌ Don't use it as a date picker — it won't shrink to that role.

## Guidelines
**Own the data; treat the callbacks as intents.** `events` is a controlled data prop — `onEventMove` / `onEventResize` / `onRangeSelect` hand you the proposed range (plus a `meta` identifying the recurrence occurrence via `baseId` + `occurrenceStart`); apply it to your own state. Nothing mutates until you do.

**Style only through tone × appearance and the render slot.** Give events a `tone` (the shared vocabulary) and `appearance` (solid/soft/outline); reach for `renderEvent` when you need custom content — it applies in every placement (column, all-day, month cell, agenda row). Don't hand-position or hardcode colors; the canvas computes geometry into CSS variables.

**Keep it operable and honest.** The keyboard model is the differentiator — arrow-navigate events, Enter to open, Shift/Alt+arrows to reschedule; don't strip the focus ring or the sr-only instructions. Pass `date`/`defaultDate` for SSR-deterministic output, and a `timeZone` when events live in a fixed zone.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `agendaDays` | `number` | — | no | Days spanned by the agenda view. Default 14. |
| `apiRef` | `React.Ref<SchedulerApi>` | — | no | An imperative handle for driving the scheduler from outside a child. |
| `date` | `Date` | — | no |  |
| `defaultDate` | `Date` | — | no |  |
| `defaultSelectedId` | `string` | — | no |  |
| `defaultView` | `SchedulerView` | — | no |  |
| `editable` | `boolean` | — | no |  |
| `events` | `E[]` | — | yes |  |
| `firstDay` | `number` | — | no |  |
| `hour12` | `boolean` | — | no |  |
| `locale` | `string` | — | no |  |
| `maxStack` | `number` | — | no |  |
| `monthMax` | `number` | — | no | Max events shown in a month-view day cell before "+N more". Default 3. |
| `nowIndicator` | `boolean` | — | no |  |
| `onDateChange` | `(date: Date) => void` | — | no |  |
| `onEventClick` | `(event: E, meta: SchedulerEditMeta) => void` | — | no |  |
| `onEventMove` | `(event: E, range: { start: Date; end: Date; }, meta: SchedulerEditMeta) => void` | — | no |  |
| `onEventResize` | `(event: E, range: { start: Date; end: Date; }, meta: SchedulerEditMeta) => void` | — | no |  |
| `onExternalDrop` | `(info: { start: Date; end: Date; }) => void` | — | no | Fired when something is dropped onto the grid from outside (native drag). |
| `onRangeSelect` | `(range: { start: Date; end: Date; allDay: boolean; }) => void` | — | no |  |
| `onSelectedChange` | `(id: string \| null) => void` | — | no |  |
| `onSlotClick` | `(at: Date) => void` | — | no |  |
| `onViewChange` | `(view: SchedulerView) => void` | — | no |  |
| `ref` | `React.Ref<HTMLDivElement>` | — | no |  |
| `renderEvent` | `(event: E, ctx: SchedulerEventContext) => React.ReactNode` | — | no |  |
| `scrollTime` | `string` | — | no |  |
| `selectable` | `boolean` | — | no |  |
| `selectedId` | `string` | — | no |  |
| `slotDuration` | `number` | — | no |  |
| `slotMaxTime` | `string` | — | no |  |
| `slotMinTime` | `string` | — | no |  |
| `snapDuration` | `number` | — | no |  |
| `timeZone` | `string` | — | no | IANA time zone for display + positioning. Default: the runtime's local zone. |
| `view` | `SchedulerView` | — | no |  |

_Plus 278 inherited native `<div>` attributes._

### `SchedulerEvent` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no |  |
| `onResizeStart` | `(edge: "start" \| "end", e: React.PointerEvent) => void` | — | no |  |
| `ref` | `React.Ref<HTMLButtonElement>` | — | no |  |
| `resizable` | `boolean` | — | no |  |

_Plus 291 inherited native HTML attributes._

## State model
- `view` (controlled) / `defaultView` (uncontrolled), `onViewChange` · day | week | work-week | month | agenda — The active view.
- `date` (controlled) / `defaultDate` (uncontrolled), `onDateChange` · Date — The anchor date (the day / week / month shown). Uncontrolled default is picked once — pass `date`/`defaultDate` for SSR determinism.
- `selectedId` (controlled) / `defaultSelectedId` (uncontrolled), `onSelectedChange` · string | null — The selected event id (click selects; reflected via data-selected + aria-pressed).

## Anatomy
- `scheduler`: The role=group frame; carries an accessible name for the visible range and the sr-only keyboard-model description.
- `scheduler-header`: Day-column headings (weekday + date pill) for the time views.
- `scheduler-day-heading`: A single day-column heading; `data-today` marks today.
- `scheduler-all-day`: The all-day / multi-day lane above the scroll body — its own labelled group.
- `scheduler-axis`: The presentational (aria-hidden) hour-label gutter.
- `scheduler-body`: The scrollable time-canvas whose height is the visible band; the drag/measure surface.
- `scheduler-day-column`: One day's column — slot lines, positioned events, ghosts and the now-line; the drag-create + external-drop target.
- `scheduler-event`: A positioned/chip event control (SchedulerEvent). Focusable + richly labelled, or an aria-hidden continuation segment on later days of a multi-day event.
- `scheduler-now-indicator`: The live current-time line + dot on today's column (aria-hidden).
- `scheduler-overflow`: A “+N more” affordance (a Popover of the hidden events) when a cluster exceeds the column/lane cap.
- `scheduler-month`: The month day-grid (role=grid) with weekday columnheaders and spanning event bars.
- `scheduler-day-cell`: A month gridcell — roving-focusable, labelled with its date + event count/titles; Enter fires onSlotClick.
- `scheduler-agenda`: The agenda list — events grouped by day heading; each row a focusable button.

**Parts**
- `Scheduler` (`scheduler`) · required: Root + provider (generic over the event type). Owns view/date/selection + the drag machine and the `clock`; renders whichever view (time-canvas / month / agenda) `view` selects. Lifts `useScheduler` for a consumer toolbar.
- `SchedulerEvent` (`scheduler-event`): The default event block — `tone` × `appearance` (badge tokens), a leading tone rail, optional resize handles, and `asChild` to render an <a>/custom card. Exported for use inside `renderEvent`.

## Accessibility
- **Role:** group (APG: grid)
- **Tab:** Enter the events; one event is tabbable (roving tabindex). In month, cells are the tab stops.
- **ArrowUp / ArrowDown / ArrowLeft / ArrowRight:** Time/agenda views: traverse events in chronological reading order. Month: move by day cell (±1 / ±7).
- **Home / End:** First / last event (or start/end of the month row).
- **Enter / Space:** Activate the focused event (onEventClick); in month, fire onSlotClick for the focused day.
- **Shift / ArrowUp:** Move the focused event earlier by one snap (when editable).
- **Shift / ArrowDown:** Move the focused event later by one snap.
- **Shift / ArrowLeft:** Move the focused event back one day (wall-clock preserved).
- **Shift / ArrowRight:** Move the focused event forward one day.
- **Alt / ArrowUp:** Shorten the focused event by one snap.
- **Alt / ArrowDown:** Lengthen the focused event by one snap.
- **Escape:** Cancel an in-progress pointer drag (no commit).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A); 2.4.7 Focus Visible (AA); 1.4.10 Reflow (AA)
- The root is role=group with an accessible name for the visible range (aria-roledescription="event scheduler") and an sr-only aria-describedby that states the keyboard model.
- The decorative grid, hour axis and now-line are presentational (aria-hidden); the real semantics live on the events.
- Each event is a focusable control with a composed accessible name ("{title}, {start} to {end}, {weekday date}"); a recurring occurrence appends "(repeats)", a clipped multi-day segment "(continues)".
- One event is tabbable at a time (roving tabindex); a multi-day event is focusable only on its first covered day — later days are aria-hidden continuation segments (one control per event).
- Selection is exposed via aria-pressed="true" on the selected event (not visual-only).
- All-day events are a separate labelled group. The month view is role=grid with weekday columnheaders and gridcell days whose labels carry the date + event count/titles.
- Navigation and view changes are announced in a polite live region; drag/resize results are announced too. Focus is restored to the view region after navigating.
- Geometry uses logical properties, so columns and event boxes mirror under dir="rtl".
- **Focus:** Roving tabindex over events (time/agenda) and over day cells (month); focus is restored to the view region on nav; focus-visible rings preserved.
- **Contract (warn):** The root exposes an accessible name describing the visible range (default: "Schedule, {range}"). — _when always_
- **Contract (warn):** Every focusable event control has a composed accessible name including its title and time; a custom renderEvent must not remove it. — _when an event is rendered_
- **Contract (warn):** The event is a single focusable control (its first covered day); other segments are aria-hidden and not tabbable. — _when a multi-day event spans columns/weeks_
- **Contract (warn):** The month is role=grid with columnheaders and roving-focusable gridcell days carrying date + event labels. — _when view="month"_

## Tokens
- `hourHeight` → `--garn-scheduler-hour` (identity)
- `axisWidth` → `--garn-scheduler-axis` (identity)
- `nowLine` → `--garn-danger-solid`
- `surface` → `--garn-card`
- `hairline` → `--garn-border`
- `selectedRing` → `--garn-brand-solid` · brandable
- **Internal (never externalize):** `--ev-start`, `--ev-span`, `--ev-col`, `--ev-colspan`, `--ev-cols`, `--bc`, `--bs`, `--ln`, `--e-rail`

## Related
- **composes** → `utils`
- **composes** → `popover` (when the “+N more” overflow lists hidden events)
- **alternativeTo** → `calendar` (when you need a time canvas / editor, not a month date-picker)
- **alternativeTo** → `date-picker` (when the task is scheduling against a time axis, not selecting a date)
- **pairsWith** → `button` (when prev/next/today + view toggle in a toolbar (built from useScheduler))
- **pairsWith** → `dialog` (when confirm/edit an event on create or click)
- **pairsWith** → `select` (when a view or timezone switcher in the toolbar)
- **pairsWith** → `list` (when an outside backlog whose items drag onto the grid (onExternalDrop))
- **slotAccepts** → `hover-card` (when a detail peek on an event via renderEvent)

## Recipes
- **book-a-slot** — A booking / availability grid: drag empty time to propose a slot, then confirm it in a Dialog before committing to your events. _(use when a user picks a time range on a calendar to create an appointment/booking and confirms details before it is saved, unless creation is immediate with no confirmation (just push the range from onRangeSelect straight into events))_
- **event-detail** — Open an event's detail/edit surface on click — a Popover peek or a Dialog form — driven by onEventClick + the selectedId. _(use when clicking an event should reveal or edit its details)_
- **backlog-drag-in** — Drag an unscheduled item from an outside list onto the grid to schedule it (onExternalDrop gives the dropped start/end). _(use when unscheduled tasks in a side list should be draggable onto a time grid to schedule them)_

## Gotchas
- **Dragging or resizing an event does nothing — it snaps back.** — `events` is a controlled data prop; the callbacks are intents, not mutations. The component never changes your data for you. → In onEventMove / onEventResize, apply the returned range to your own state (setEvents(prev => prev.map(...))).
- **An event doesn't appear, or lands at the wrong height.** — It falls outside the visible band (slotMinTime/slotMaxTime) so it's cropped, or it's an all-day event shown in the all-day lane rather than the time grid. → Widen the band, or set `allDay: true` for date-spanning events. Positioning is wall-clock based, so also check the event's `timeZone` interpretation.
- **A recurring event's drag/click hands back a synthetic id like "sync::1720000000000".** — RRULE occurrences are generated per visible span with a composite id; that's the on-screen occurrence, not your base event. → Use the 3rd `meta` arg — `{ recurring, baseId, occurrenceStart }` — to map back to the base event you own and decide "this" vs "all".
- **SSR hydration warning about the calendar showing a different week on the server.** — With no `date`/`defaultDate`, the uncontrolled anchor defaults to "now", which differs between server and client render. → Pass `date` (controlled) or `defaultDate` for deterministic SSR output.
- **Custom `renderEvent` content shows in day/week but not in month or agenda.** — Older assumption — renderEvent now runs in every placement and receives `ctx.placement`. → Branch on `ctx.placement` ("column" | "all-day" | "month" | "agenda") to render appropriately for each surface.
- **On a phone, trying to drag-create just scrolls the grid.** — Touch uses a long-press to start a drag so a quick swipe can still scroll. → Press and hold (~350ms) on empty time to begin drag-create; a normal swipe scrolls as expected.

## Examples
- **week-editor** (canonical): The full editor: a week canvas with a useScheduler toolbar, all-day lane, overlap packing, drag/keyboard create-move-resize, selection and the live now-line.
- **day** (playground): A single day — dense overlaps show the interval-graph column packing.
- **month** (playground): The month day-grid — spanning bars for multi-day events, per-cell “+N more”, role=grid keyboard navigation.
- **agenda** (playground): The agenda list — events grouped by day, including a recurring (rrule) sync.
- **dense** (edge-case): Heavy overlaps with `maxStack` — extra columns collapse into a “+N” Popover.
- **tones** (playground): The event tone × appearance range (solid / soft / outline).

## Source map

Regions in `scheduler.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–16 (15 lines) — React, Radix Slot, cva, garn lib hooks
- `types` L17–110 (94 lines) — overview banner, constants, event and view types
- `timezone` L111–235 (125 lines) — Clock, proxy-day helpers, wall-clock math
- `recurrence` L236–395 (160 lines) — RRULE parsing and occurrence expansion
- `event-layout` L396–559 (164 lines) — day column packing + month week lanes
- `context` L560–588 (29 lines) — SchedulerContext store + useScheduler hook
- `event-block` L589–700 (112 lines) — cva tone variants + SchedulerEvent part
- `drag-model` L701–725 (25 lines) — drag gesture kinds and state shape
- `props` L726–795 (70 lines) — SchedulerProps and SchedulerApi handle types
- `root` L796–2121 (1326 lines) — Scheduler component: state, drag editor, view renderers
  - `state` L837–885 (49 lines) — hooks, controllable view/date/selection, band config
  - `derived` L886–975 (90 lines) — day grids, visible span, recurrence, formatters
  - `navigation` L976–1036 (61 lines) — focus refs, date/view nav, context, event buckets
  - `drag-editor` L1037–1310 (274 lines) — pointer create/move/resize machine, external drop
  - `effects` L1311–1369 (59 lines) — now tick, auto-scroll, announcements, apiRef handle
  - `keyboard` L1370–1475 (106 lines) — roving tabindex, arrow-key editing, selection
  - `view-data` L1476–1541 (66 lines) — packed columns, month lanes, cell roving, helpers
  - `render-helpers` L1542–1714 (173 lines) — timed block painter, month chips, all-day chips
  - `views` L1715–2119 (405 lines) — time canvas, month grid, agenda, root JSX

---

# Scroll Area

> A height-constrained region with a styled, cross-browser scrollbar.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** layout
- **Import:** `import { ScrollArea } from "@garn/ui/scroll-area"`

## Overview
ScrollArea gives a height-constrained region its own consistently-styled scrollbar — a sidebar, a long list, a code block, a chat log — instead of the OS default that varies by platform. `ScrollArea` is the root + viewport (children scroll inside), and `ScrollBar` is the track/thumb (vertical by default; add a horizontal one for horizontal overflow). Use it for a bounded scrolling pane; for whole-page scrolling, let the document scroll natively.

## When to use
Give a height-constrained region its own styled scrollbar — a sidebar, a long list, a code block, a chat log.

## When not to use
The whole page (let the document scroll natively); content that must never be clipped (let it flow); a few items that already fit.

## Do / Don't
- ✅ Set an explicit height / max-height on the ScrollArea (or its container) so there's something to scroll.
- ✅ Keep important content reachable — don't hide the only copy of critical info behind a scroll region.
- ✅ Use the Root `type` (auto / always / scroll / hover) to decide when the bar shows.
- ❌ Don't wrap the entire page — use native document scroll.
- ❌ Don't set a height that clips content without leaving a scroll affordance.
- ❌ Don't rely on `type="hover"` as the only hint that more content exists.

## Guidelines
**Use it for bounded regions, not the whole page.** It shines on a fixed-height panel that needs to scroll independently with a tidy scrollbar; hijacking the document scroll is the wrong call. Give the region a real height constraint so there's something to scroll.

**Never trap content behind a scrollbar users can't see.** Ensure the area is keyboard-scrollable and that important content isn't hidden with no scroll cue; on touch, native momentum should still work. Add a horizontal `ScrollBar` only when content truly overflows sideways.

**Keep the scrollbar legible and unobtrusive.** Style it to read clearly against the surface without dominating it, and don't shrink the thumb so far it's hard to grab. Respect reduced-motion for any scroll animations.

## Anatomy

**Parts**
- `ScrollArea` (`scroll-area`) · required: Root + Viewport; renders a vertical ScrollBar and a Corner. Children render inside the scrolling viewport.
- `ScrollBar` (`scroll-bar`): The scrollbar track + thumb. `orientation` vertical (default) | horizontal — compose a horizontal bar for horizontal overflow.

## Accessibility
- **WCAG:** 1.4.10 Reflow (AA); 2.1.1 Keyboard (A)
- Native scrolling is preserved — wheel, touch, and keyboard (when the viewport has focus) all still work; the styled bar is an overlay.
- Set the Root `type` to control when the scrollbar appears; `auto`/`always` keep it discoverable for everyone.

## Related
- **composes** → `utils`
- **pairsWith** → `separator` (when dividing items in a scrolled list)
- **pairsWith** → `card` (when making a card's body region scroll)

## Gotchas
- **No scrollbar appears and content is cut off.** — The ScrollArea (or its parent) has no bounded height, so there's no overflow to scroll. → Give the ScrollArea an explicit height / max-height.
- **Horizontal content doesn't get a scrollbar.** — ScrollArea renders a vertical ScrollBar by default. → Compose a `<ScrollBar orientation="horizontal" />` (and let the content exceed the viewport width).

## Examples
- **basic** (canonical): A fixed-height vertical list with a styled scrollbar.

---

# Select

> Choose one option from a list, presented in a popover.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Select } from "@garn/ui/select"`

## Overview
Select lets a person pick one option from a list that's too long to show inline but short enough to scan in a popover (roughly 5–15 choices). It's a **compound** component: `Select` owns the value and open state, `SelectTrigger` is the button you see (it renders the shared field surface, so it carries the same `appearance` × `size` variants as Input and lines up with the rest of a form), and `SelectContent` is the portaled listbox of `SelectItem`s — optionally organized with `SelectGroup` + `SelectLabel`.

Because it's built on Radix, the keyboard and ARIA model — typeahead, arrow navigation, `aria-activedescendant`, focus return — comes for free. Reach for Select when the choices are predefined and the user just needs to *pick*; if they need to *search* a long list, that's a Combobox, and if there are only two-to-five always-visible options, a RadioGroup reads better.

## When to use
Pick one option from a medium-to-long list (~5+) where the choices fit in a popover.

## When not to use
A few options where seeing them all helps (use radio-group); free text (use input); choosing many (Select is single-select — use a command / multi-select pattern).

## Do / Don't
- ✅ Label the trigger; give SelectValue a clear placeholder for the empty state.
- ✅ Give each SelectItem a unique, non-empty `value`.
- ✅ Group long lists with SelectGroup + SelectLabel.
- ❌ Don't rely on the placeholder as the field's label.
- ❌ Don't use a Select for 2–4 options the user benefits from seeing at once — that's radio-group.
- ❌ Don't expect multi-select — Select is single-value.

## Guidelines
**Give every SelectItem a unique, non-empty `value`.** An empty string collides with the placeholder slot and will throw; use a real key. Keep the visible label short — the trigger truncates, and a wall of long options is hard to scan.

**Use a placeholder for the empty state, a label for the name.** `SelectValue`'s placeholder says *what to pick* ("Choose a country"); it is not a substitute for an external `label`. Wire the field's accessible name with a Label or Form, the same as any other control.

**Group only when it earns its keep.** `SelectGroup` + `SelectLabel` help when options fall into a few clear buckets; for a flat list they add noise. Don't nest a Select inside another popover/menu — if you're tempted, the pattern probably wants a Command palette or a Combobox instead.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |

_Plus 13 inherited native HTML attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The selected option's value. Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`.
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Whether the listbox popover is open.
- Selection: single.

## Anatomy

**Parts**
- `Select` · required: State container (Radix Root) — owns value + open. No DOM of its own.
- `SelectTrigger` (`select-trigger`) · required: The button that opens the listbox; renders the shared field surface (carries the `appearance` + `size` variants).
- `SelectValue` (`select-value`): Renders the selected value, or the placeholder when empty.
- `SelectContent` (`select-content`) · required: The portaled popover listbox.
- `SelectItem` (`select-item`) · required: A selectable option. Requires a unique, non-empty `value`.
- `SelectGroup`: Groups related items under a SelectLabel.
- `SelectLabel` (`select-label`): A heading inside a group (not the field's label).
- `SelectSeparator` (`select-separator`): A divider between groups.

## Accessibility
- **Role:** combobox (APG: combobox)
- **Space / Enter / ArrowDown / ArrowUp:** Open the listbox.
- **ArrowUp / ArrowDown / Home / End:** Move between options.
- **A–Z:** Type-ahead to the matching option.
- **Enter:** Select the highlighted option and close.
- **Escape:** Close without changing the value.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A); 2.4.7 Focus Visible (AA)
- Trigger exposes aria-expanded / aria-controls; the selected option has aria-selected.
- The placeholder is NOT an accessible name — label the trigger explicitly.
- **Focus:** Trigger border darkens (foreground/40) on focus; keyboard focus adds a 2px neutral ring (foreground/15). Focus moves into the listbox on open and returns to the trigger on close.
- **Contract (warn):** Give the SelectTrigger an accessible label (a <label>, or aria-label/aria-labelledby). — _when SelectTrigger has no associated <label>, aria-label, or aria-labelledby (the placeholder doesn't count)_

## Tokens
- `triggerHeight` → `--garn-control-h-md` (air)
- `triggerPaddingInline` → `--garn-control-px-md` (air)
- `itemMinHeight` → `--garn-control-h-md` (air)
- `borderColor` → `--garn-foreground`

## Related
- **composes** → `utils`
- **composes** → `field-variants`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `radio-group` (when there are only a few options and showing them all helps)
- **alternativeTo** → `command` (when the list is long and benefits from search)

## Recipes
- **labeled-select** — A labeled single-select field. _(use when choosing one option from a list in a form)_

## Gotchas
- **Runtime error or an option that can't be selected.** — A SelectItem with an empty `value` — Radix reserves the empty string to clear the selection. → Give every SelectItem a unique, non-empty `value`.
- **Screen readers announce the field with no name.** — The SelectValue placeholder is not an accessible label. → Associate a <label> with the trigger, or pass aria-label to SelectTrigger.

## Examples
- **basic** (canonical): Trigger + placeholder + three options.
- **appearances** (playground): outline · soft · ghost (shared field surface).
- **sizes** (edge-case): xs · sm · md · lg · xl trigger heights.
- **grouped** (edge-case): Grouped options with labels and a separator.
- **invalid** (edge-case): aria-invalid — danger edge + danger focus ring (shared field surface).
- **disabled** (edge-case): A disabled trigger.

---

# Separator

> A thin rule that divides content into groups.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** layout
- **Import:** `import { Separator } from "@garn/ui/separator"`

## Overview
Separator draws a thin rule that divides content groups — between list items, sections, or toolbar clusters — horizontally or vertically. It's a lightweight visual boundary, decorative by default (so it's skipped by assistive tech) but able to carry a semantic `separator` role when the division is meaningful. When the goal is just breathing room, use spacing; when it's a named section boundary, a heading communicates more.

## When to use
Visually divide content groups — between list items, sections, or toolbar clusters.

## When not to use
Plain spacing (use a gap); a labeled section boundary (use a heading).

## Do / Don't
- ✅ Use `orientation="vertical"` inside a flex row (the parent needs a height).
- ✅ Set `decorative={false}` when the separation carries meaning for assistive tech.
- ❌ Don't use a separator purely for margin.
- ❌ Don't stack multiple separators for thickness.

## Guidelines
**Separate only when grouping isn't already clear.** Whitespace usually does the job; add a rule when adjacent groups would otherwise blur together (toolbar clusters, a menu's sections). A page sliced by lines everywhere reads busier, not clearer.

**Pick the right semantics.** Leave it decorative when it's purely visual; mark it a real separator only when it represents a genuine content boundary that a screen-reader user should perceive. Don't use a separator as a heading substitute.

**Match orientation and weight to context.** Vertical separators divide inline clusters (toolbar groups), horizontal ones divide stacked sections. Keep it a hairline on a token border color — a heavy divider competes with the content it's meant to organize.

## Anatomy
- `separator`: The 1px rule (full width or full height).

## Accessibility
- **Role:** separator
- **WCAG:** 1.3.1 Info and Relationships (A)
- `decorative` defaults to true → it's hidden from the a11y tree (purely visual).
- Set `decorative={false}` to expose role=separator + aria-orientation when the divide is meaningful.

## Related
- **composes** → `utils`
- **pairsWith** → `button-group` (when to split clustered actions)

## Examples
- **basic** (canonical): Horizontal + vertical.

---

# Sheet

> A panel that slides in from a screen edge for a secondary task or navigation.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { Sheet } from "@garn/ui/sheet"`
- **Polymorphism:** `asChild`

## Overview
Sheet slides a panel in from a screen edge for a secondary task or navigation that shouldn't replace the page — a filter panel, a detail/edit form, a mobile nav. `SheetContent` carries the `side` variant (top/right/bottom/left), portals its overlay, and ships a built-in close X; `SheetTitle` (required) names it, with optional `Description`/`Header`/`Footer`. Use it for longer or side-anchored tasks than a Dialog suits; on touch/mobile a bottom Drawer with a drag handle often feels more native.

## When to use
Slide a panel in from a screen edge for a secondary task or navigation that shouldn't replace the page — filters, a detail/edit panel, a nav drawer.

## When not to use
A small focused confirmation (use dialog / alert-dialog); contextual content anchored to a control (use popover); a mobile bottom-sheet with drag (use drawer); content that needn't overlay.

## Do / Don't
- ✅ Always include a SheetTitle (sr-only if you don't want it visible).
- ✅ Pick `side` to fit the mental model — right for details/edit, left for nav, bottom for mobile.
- ✅ Keep it dismissible: Escape, the close button, and overlay click all close it.
- ❌ Don't put a destructive forced choice in a sheet — use alert-dialog.
- ❌ Don't omit the SheetTitle.
- ❌ Don't nest sheets or stack a sheet over a dialog.

## Guidelines
**Reach for a Sheet when a Dialog would feel cramped.** It's the right home for a multi-field edit form, a filter set, or a side nav — content that benefits from height and an edge anchor. Pick the `side` that matches intent: right for detail/edit, left for nav, bottom for mobile actions.

**Always render a `SheetTitle`.** It's the panel's accessible name and the contract is enforced; hide it visually (sr-only) if the design has no heading, but keep it. Pin primary actions in `SheetFooter` so they stay reachable as the body scrolls.

**Keep the modal contract honest.** Focus traps inside while open and returns to the trigger on close; Escape and the close X both dismiss. Don't stack sheets and dialogs — resolve one surface before opening another.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `side` | `"bottom" \| "left" \| "right" \| "top"` | `right` | no |  |

_Plus 5 inherited native HTML attributes._

## Variants
- **side** (default `right`): `top`, `bottom`, `left`, `right`

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen` (or just a SheetTrigger).
- Selection: single.

## Anatomy

**Parts**
- `Sheet` · required: Root — owns the open state. No DOM of its own.
- `SheetTrigger` (`sheet-trigger`): Opens the sheet (asChild to wrap your own button).
- `SheetContent` (`sheet-content`) · required: The edge panel; carries the `side` variant, portals its overlay, and includes a built-in close X.
- `SheetClose` (`sheet-close`): Closes the sheet (e.g. a Cancel button).
- `SheetTitle` (`sheet-title`) · required: Accessible name for the panel (required; sr-only if visually hidden).
- `SheetDescription` (`sheet-description`): Supplementary description, wired to aria-describedby.
- `SheetHeader` (`sheet-header`): Layout wrapper for title + description.
- `SheetFooter` (`sheet-footer`): Layout wrapper for actions (right-aligned on ≥sm).

## Accessibility
- **Role:** dialog (APG: dialog (modal))
- **Escape:** Close the sheet.
- **Tab / Shift+Tab:** Cycle focus within the sheet (focus is trapped).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.3 Focus Order (A); 4.1.2 Name, Role, Value (A)
- aria-modal; labelled by SheetTitle and (if present) described by SheetDescription.
- Focus moves into the panel on open and returns to the trigger on close.
- A built-in close button (sr-only "Close") sits in the corner; Escape and overlay click also close.
- **Focus:** Focus trapped inside the panel; returns to the trigger on close.
- **Contract (warn):** Every SheetContent must contain a SheetTitle (wrap it in sr-only to hide it visually). — _when SheetContent has no SheetTitle_

## Tokens
- `padding` → `--garn-pad-surface` (air)
- `gap` → `--garn-gap-stack` (air)
- `headerGap` → `--garn-gap-field` (air)
- `closeSize` → `--garn-control-h-xs` (air)
- `motion` → `--garn-motion-base`

## Related
- **composes** → `utils`
- **pairsWith** → `button` (when as the trigger and the footer actions)
- **alternativeTo** → `dialog` (when a centered modal fits the task better than an edge panel)
- **alternativeTo** → `drawer` (when you want a mobile bottom-sheet with drag-to-dismiss)

## Recipes
- **detail-panel** — A right-side panel for viewing/editing a record without leaving the list. _(use when a secondary task should overlay the page without replacing it)_

## Gotchas
- **Console warning about a missing Title/Description; screen readers can't name the panel.** — SheetContent without a SheetTitle (Radix Dialog requires it). → Add a SheetTitle (sr-only if hidden); add SheetDescription to silence the description warning.
- **The panel slides from the wrong edge.** — `side` defaults to "right". → Pass side="left" | "top" | "bottom" on SheetContent.

## Examples
- **basic** (canonical): Trigger → right-side edit panel with footer actions.
- **sides** (edge-case): Open from any edge — top, right, bottom, or left.

---

# Skeleton

> A pulsing placeholder that preserves layout while content loads.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** feedback
- **Import:** `import { Skeleton } from "@garn/ui/skeleton"`

## Overview
Skeleton holds the page's shape while content loads, mirroring the size and shape of the incoming text or media so the layout doesn't jump when data arrives. It's the right loading pattern when you know the structure ahead of time — a list, a card, a profile. For an indeterminate spot with no known shape use a Spinner, and for a genuinely empty result (not loading) use Empty.

## When to use
Hold the page's shape while content loads — mirror the size/shape of the incoming text or media.

## When not to use
An indeterminate spinner inside a control (use spinner); a blank state with nothing to load (use empty).

## Do / Don't
- ✅ Match the skeleton's dimensions to the real content to avoid layout shift.
- ✅ Wrap the loading region in aria-busy and swap to content when ready.
- ❌ Don't leave skeletons up indefinitely on error — show an error/empty state.
- ❌ Don't animate so strongly it distracts.

## Guidelines
**Shape the skeleton like the real content.** Match the blocks to the text lines, avatar, and media that will replace them so the swap is seamless — a generic grey box that resizes on load defeats the purpose. Reuse the real layout's spacing.

**Use it for structured, short waits.** Skeletons suit content whose shape you can predict; for an unknown or very brief wait, a Spinner is simpler. Don't leave skeletons up indefinitely — fall through to an error or empty state if the load fails.

**Keep it quiet and accessible.** Mark the placeholder region `aria-busy` (and hide the decorative shapes from screen readers) so assistive tech announces "loading" rather than reading empty boxes. Keep the shimmer subtle and respect reduced-motion.

## Anatomy
- `skeleton`: The pulsing block; size it with h-*/w-*/rounded-* classes.

## Accessibility
- **WCAG:** 4.1.3 Status Messages (AA)
- Skeletons are decorative — mark the loading region with aria-busy=true and aria-hidden the placeholders.
- Announce completion by swapping to real content (and clearing aria-busy).

## Related
- **composes** → `utils`
- **alternativeTo** → `spinner` (when you want to preserve the content's shape rather than a generic indicator)

## Examples
- **basic** (canonical): A card placeholder (avatar + two lines).

---

# Slider

> A draggable track for choosing a number or a range.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Slider } from "@garn/ui/slider"`

## Overview
Slider lets a person pick a number — or a range, with one thumb per value — where the *approximate* position matters more than an exact figure: volume, brightness, a price band. The filled range gives instant feedback on how far along the value sits. When the precise number is what matters (a quantity, a price to the cent), a number field is clearer; for a few discrete choices, use a RadioGroup or Select.

## When to use
Let users pick a number (or a range) where the approximate position matters more than an exact figure — volume, brightness, a price range.

## When not to use
A precise numeric entry (use a number input); an on/off (use switch); a few discrete choices (use radio-group); progress display (use progress).

## Do / Don't
- ✅ Give the slider an accessible label; set sensible `min`/`max`/`step`.
- ✅ Pass two values for a range, and label each thumb.
- ✅ Show the current value nearby when the exact number matters.
- ❌ Don't use a slider when an exact value is required — pair it with a number input or use one.
- ❌ Don't leave it unlabeled.
- ❌ Don't use it to show progress — that's the progress bar.

## Guidelines
**Give the slider an accessible name and visible value.** A bare track tells a screen-reader user nothing — wire a Label and surface the current value (a readout or tooltip) so the number isn't hidden in the handle position. For a range, label both thumbs ("minimum"/"maximum").

**Match step and bounds to the real range.** Choose a `step` that makes every reachable value sensible and set min/max to the true limits; arrow keys nudge by one step, so a too-fine step makes keyboard use tedious. Keep the track wide enough to be draggable on touch.

**Don't use a slider for precision or for two states.** Exact entry → a number input beside it; on/off → a Switch. Avoid long sliders where a 1px drag changes the value a lot — pair coarse dragging with keyboard fine-tuning.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |

_Plus 293 inherited native HTML attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · number[] — The thumb position(s). Always an array — one entry per thumb; two entries make it a range. Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`.
- Selection: multiple.

## Anatomy
- `slider`: The control; carries `size` and renders the track + range + one thumb per value.
- `track`: The rail (internal).
- `range`: The filled portion from min to the value (internal).
- `thumb`: A draggable handle — one per value in `value`/`defaultValue` (internal).

## Accessibility
- **Role:** slider (APG: slider)
- **ArrowLeft / ArrowDown:** Decrease by one step.
- **ArrowRight / ArrowUp:** Increase by one step.
- **Home / End:** Jump to min / max.
- **PageUp / PageDown:** Step by a larger increment.
- **WCAG:** 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- Each thumb is role=slider with aria-valuenow/min/max; give the control an accessible name (aria-label or a <label>).
- For a range, label the thumbs (e.g. aria-label "Minimum"/"Maximum") so they're distinguishable.
- **Focus:** 1px ring on the focused thumb.
- **Contract (warn):** Give the slider an accessible name (aria-label or a <label>). — _when the Slider has no aria-label / aria-labelledby / associated <label>_

## Tokens
- `thumbSize` → `--garn-box-md` (identity)
- `ring` → `--garn-ring` · brandable
- **Internal (never externalize):** `--st`, `--tk`

## Related
- **composes** → `utils`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `input` (when an exact numeric value must be typed)

## Gotchas
- **`value`/`defaultValue` type errors or no thumb appears.** — Slider values are arrays, not numbers. → Pass an array — `defaultValue={[50]}` (single) or `value={[20, 80]}` (range).
- **Screen readers announce the slider with no name.** — No accessible label. → Add aria-label (or associate a <label>); for ranges, label each thumb.

## Examples
- **basic** (canonical): A single-value slider with a label.

---

# Sonner (Toast)

> Transient, stacking notifications fired imperatively with toast().

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** feedback
- **Import:** `import { Sonner(Toast) } from "@garn/ui/sonner"`

## Overview
Sonner confirms an action or surfaces a transient, non-blocking message that auto-dismisses — "Saved", "Copied", "Undo". Mount exactly one `Toaster` near the app root, then fire toasts imperatively with `toast(message, opts)` and its `.success` / `.error` / `.promise` helpers. It's for moments that don't need a response; for a persistent message that stays on the page use Alert, and for a decision the user must make use a Dialog.

## When to use
Confirm an action or surface a transient, non-blocking message that auto-dismisses — 'Saved', 'Copied', 'Undo'.

## When not to use
A persistent inline status (use alert); a decision the user must make (use alert-dialog); a critical error that must not be missed (don't rely on an auto-dismissing toast).

## Do / Don't
- ✅ Render exactly one <Toaster /> near the app root; call toast() from anywhere.
- ✅ Keep messages short; attach an action (e.g. Undo) when useful.
- ✅ Use toast.success / toast.error / toast.promise to match intent.
- ❌ Don't mount multiple Toasters.
- ❌ Don't put essential, time-limited actions only in a toast.
- ❌ Don't use a toast where a persistent banner (alert) belongs.

## Guidelines
**Use toasts for confirmation, not for anything required.** A toast disappears — never put an error a user must act on, or the only copy of important information, in one. `toast.promise` is ideal for tying a toast to an async action's pending/success/error states.

**Keep them short and offer Undo over confirm-first.** One line is plenty; where an action is reversible, ship it optimistically with an Undo toast instead of interrupting with a dialog. Don't stack many toasts at once — collapse or queue them.

**Mount one Toaster and respect timing.** A single host keeps positioning and theming consistent; let messages auto-dismiss but give error toasts a longer dwell (or an explicit close) so they're readable. They're announced politely — don't rely on them as the sole signal for critical state.

## Anatomy
- `toaster`: The host region (rendered once at the app root) where toasts portal in and stack.

**Parts**
- `Toaster` (`toaster`) · required: The provider/host — mount exactly one near the app root (themed via toastOptions classNames).
- `toast`: The imperative API: toast(message, opts) plus toast.success / .error / .promise / .dismiss. Not a component.

## Accessibility
- **Role:** status
- **WCAG:** 4.1.3 Status Messages (AA); 2.2.1 Timing Adjustable (A)
- Sonner renders toasts in an aria-live region so they're announced without stealing focus.
- Keep toast text self-contained; if an action is essential, don't make a brief auto-dismissing toast the only way to reach it.
- Toasts are reachable/dismissable via the keyboard (focus the region with the hotkey, default Alt/⌥ + T).

## Related
- **alternativeTo** → `alert` (when the message should persist inline rather than auto-dismiss)
- **alternativeTo** → `alert-dialog` (when the user must stop and make a choice)

## Gotchas
- **toast() does nothing / no toast appears.** — No <Toaster /> is mounted in the tree. → Render a single <Toaster /> once at the app root; then toast() works from anywhere.
- **Duplicate or misplaced toasts.** — More than one Toaster is mounted. → Mount exactly one Toaster for the whole app.

## Examples
- **basic** (canonical): A button that fires a toast (with the Toaster mounted).

---

# Sortable

> The foundational drag-and-drop reorder primitive — a zero-dependency, accessible engine that makes any collection reorderable: a single vertical/horizontal list, a wrapping 2D grid, or a Kanban board (cross-container). Keyboard drag mode and screen-reader announcements come for free; edge auto-scroll, a touch long-press sensor, a drop indicator, and multi-item drag are built in. A `useSortable` hook wires the same engine into List, Tree, and Table.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Sortable } from "@garn/ui/sortable"`
- **Polymorphism:** `asChild` (default element `<div>`)

## Overview
Sortable is garn's foundational drag-and-drop — the accessible reorder engine everything else composes. It has zero runtime dependency: a Pointer-Events + keyboard machine that ships in the registry as source. Reach for it to make a collection reorderable — a single vertical or horizontal list, a wrapping 2D grid, or a Kanban board where items move between columns. A `Sortable` wraps items keyed by `value`; drag by the whole item, or add a `Sortable.Handle` so interactive row content stays clickable. It is accessible by default — a full keyboard drag mode (lift → move → drop / cancel) and live-region announcements come for free, not as an opt-in. Consumers that already own their rows (List's `reorderable`, Tree's drag-reparent) wire in the same engine through the headless `useSortable` hook.

## When to use
Making a collection reorderable by drag (and keyboard): a to-do / priority list, a Kanban board that moves cards between columns, a tile/image grid, a settings list of pinned items. Use it directly with <Sortable> + <Sortable.Item>, or wire the `useSortable` hook into a component that owns its own rows.

## When not to use
You just need to render a list or tree without reordering (use List / Tree). Reordering a paginated / server-sorted table where order isn't user-owned. Generic drag from one arbitrary place to another, or external file drop (Sortable is for reordering known items, not arbitrary drag sources). A single fixed pair of swappable panes (use Resizable).

## Do / Don't
- ✅ Control order with `value`/`onValueChange` (or `defaultValue`) and apply the reported order to your data.
- ✅ Add a `Sortable.Handle` when the row has interactive content, and always on semantic <li>/<tr>/treeitem rows.
- ✅ Override the four screen-reader messages via `announcements` for domain language (e.g. "Moved to Done") — the shared keyboard-instructions node is injected by the root, so there's nothing to render for the describedby.
- ✅ Use a `Sortable.Group` + `Sortable.Overlay` for a Board; `orientation="grid"` for a 2D grid; `selectedValues` for multi-item drag.
- ✅ Leave `autoScroll` on for long lists and set `touchDelay` (long-press) for touch — a swipe should still scroll.
- ❌ Don't put `role="button"` on a semantic <li>/<tr>/treeitem to make it draggable — it breaks list/grid/tree semantics; drag via a Sortable.Handle instead.
- ❌ Don't build a Board without a Sortable.Overlay — the dragged card gets clipped by a column's overflow.
- ❌ Don't lock touch scrolling — the whole-item touch sensor is long-press so the list still scrolls; don't set touch-action:none on rows yourself.
- ❌ Don't silence the live-region announcements or remove the focus ring — the keyboard drag model depends on both.

## Guidelines
**One `Sortable` = one list; a `Sortable.Group` = a Board.** A standalone Sortable owns its ordered `value` and the drag machine; wrapping several in a Sortable.Group hoists one machine across columns so items move between them (add a Sortable.Overlay so the ghost escapes each column's clipping).

**Drag the whole item, or add a handle.** A bare Sortable.Item is the activator — good for simple rows. When the row has buttons/links/inputs, add a `Sortable.Handle` so only the grip drags; on semantic <li>/<tr>/treeitem rows a handle is required (a role=button on the row breaks their semantics).

**Own your data.** Reorder is controlled via `value`/`onValueChange` (or uncontrolled `defaultValue`); apply the reported order to your state. In a Board, each column owns its own `value`.

**Reach for the built-ins before a recipe.** `orientation="grid"` for 2D; `selectedValues` for multi-item drag; `dropIndicator` for an insertion line; `autoScroll` (on by default) for long lists; `touchDelay` long-press for mobile. The keyboard describedby wires itself up — the root injects the shared instructions node on mount, so there's nothing to render for it; just don't strip the focus ring or silence the announcements.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activationDistance` | `number` | — | no | Pointer travel (px) before a mouse/pen drag begins — guards clicks. |
| `announcements` | `Partial<SortableAnnouncements>` | — | no |  |
| `asChild` | `boolean` | — | no |  |
| `autoScroll` | `boolean` | — | no | Auto-scroll the nearest scroll container when dragging near its edge (default true). |
| `collision` | `"closest-center" \| "pointer"` | — | no | Drop-index projection: `pointer` (1D) or `closest-center` (2D reading order). |
| `defaultValue` | `string[]` | — | no | Ordered item keys (uncontrolled initial). |
| `disabled` | `boolean` | — | no |  |
| `dropIndicator` | `boolean` | — | no | Show a built-in insertion line at the drop position (default false). |
| `getItemLabel` | `(value: string) => string` | — | no | Map an item key to the label screen readers announce. |
| `id` | `string` | — | no | Container id — auto-generated; set it when composing a Board by hand. |
| `lockAxis` | `boolean` | — | no | Constrain the self-translate follow to the main axis (default true). |
| `onDragCancel` | `(e: { value: string; }) => void` | — | no |  |
| `onDragEnd` | `(e: ReorderMeta) => void` | — | no |  |
| `onDragMove` | `(e: DragMoveEvent) => void` | — | no | Fires for every drag point: rAF-throttled moves, auto-scroll re-projections, and a synchronous final point at the drop. |
| `onDragOver` | `(e: DragOverEvent) => void` | — | no | Fires when the projected drop slot (container/index) changes. |
| `onDragStart` | `(e: { value: string; }) => void` | — | no |  |
| `onValueChange` | `(value: string[], meta: ReorderMeta) => void` | — | no | Fires with the next order and what moved. |
| `orientation` | `"grid" \| "horizontal" \| "vertical"` | — | no | Layout + axis: `vertical` (default), `horizontal`, or a wrapping 2D `grid`. |
| `selectedValues` | `string[]` | — | no | Selected item values — dragging one moves the whole set (multi-item drag). |
| `touchDelay` | `number` | — | no | Long-press (ms) before a *touch* drag begins — a quick swipe scrolls instead. |
| `value` | `string[]` | — | no | Ordered item keys (controlled). |

_Plus 275 inherited native `<div>` attributes._

### `Sortable.Item` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no |  |
| `disabled` | `boolean` | — | no | Make this item non-draggable (a pinned/locked row). |
| `hasHandle` | `boolean` | — | no | Declare that a `Sortable.Handle` lives somewhere in this item's rendered output. The automatic detection only walks the JSX you pass as children — a handle rendered *inside* one of your own components is invisible to it, which would silently make the whole item the activator. |
| `value` | `string` | — | yes | The item's stable key — its identity in the ordered `value`. |

_Plus 280 inherited native HTML attributes._

### `Sortable.Handle` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no |  |
| `label` | `string` | — | no | Accessible name for the icon-only handle (default "Drag to reorder"). |

_Plus 290 inherited native HTML attributes._

### `Sortable.Overlay` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `(activeValue: string) => React.ReactNode` | — | yes | Render the ghost for the active key (clip-free; follows the pointer). |
| `className` | `string` | — | no |  |

### `Sortable.Group` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activationDistance` | `number` | — | no | Pointer travel (px) before a mouse/pen drag begins. |
| `announcements` | `Partial<SortableAnnouncements>` | — | no |  |
| `asChild` | `boolean` | — | no |  |
| `autoScroll` | `boolean` | — | no | Auto-scroll the nearest scroll container near an edge (default true). |
| `collision` | `"closest-center" \| "pointer"` | — | no | Drop-index projection: `pointer` (1D) or `closest-center` (2D reading order). |
| `disabled` | `boolean` | — | no |  |
| `dropIndicator` | `boolean` | — | no | Show a built-in insertion line at the drop position (default false). |
| `getItemLabel` | `(value: string) => string` | — | no |  |
| `lockAxis` | `boolean` | — | no | Constrain the self-translate follow to the main axis (default true). |
| `onDragCancel` | `(e: { value: string; }) => void` | — | no |  |
| `onDragEnd` | `(e: ReorderMeta) => void` | — | no |  |
| `onDragMove` | `(e: DragMoveEvent) => void` | — | no | Fires for every drag point: rAF-throttled moves, auto-scroll re-projections, and a synchronous final point at the drop. |
| `onDragOver` | `(e: DragOverEvent) => void` | — | no | Fires when the projected drop slot (container/index) changes. |
| `onDragStart` | `(e: { value: string; }) => void` | — | no |  |
| `orientation` | `"grid" \| "horizontal" \| "vertical"` | — | no | Layout + axis for the columns' items: `vertical` (default), `horizontal`, or `grid`. |
| `selectedValues` | `string[]` | — | no | Selected item values — dragging one moves the whole set (multi-item drag). |
| `touchDelay` | `number` | — | no | Long-press (ms) before a touch drag begins. |

_Plus 277 inherited native HTML attributes._

## Anatomy
- `sortable`: A sortable container — the droppable region and, standalone, the drag machine. A vertical/horizontal flex list (or a wrapping grid); reflects data-orientation / data-dragging / data-disabled.

**Parts**
- `Sortable.Item` (`sortable-item`) · required: A `value`-keyed reorderable cell. When it holds no handle it IS the drag activator (a role=button with an accessible name + keyboard); with a nested Sortable.Handle the row body stays free. Handle detection walks the JSX children — a handle rendered inside one of your own components is invisible to the walk, so declare it with the `hasHandle` prop. Reflects data-dragging / data-placeholder / data-drop-edge / data-orientation / data-disabled, and (multi-item) shows a count badge (sortable-drag-count).
- `Sortable.Handle` (`sortable-handle`): The optional drag affordance — a real <button> (default name "Drag to reorder"). When present, only it starts a drag, so interactive row content (buttons, links, inputs) stays clickable and semantic <li>/<tr> rows keep their role.
- `Sortable.Overlay` (`sortable-overlay`): A portal ghost that follows the pointer, render-prop `(activeValue) => node`. Clip-free — required for a Board so the dragged item can escape a column's overflow; when present the source item hides.
- `Sortable.Group` (`sortable-group`): A Board coordinator — hoists ONE drag machine across the child Sortable columns so an item can move between them. Pair with a Sortable.Overlay.

## Accessibility
- **Space / Enter:** On the drag activator: pick the item up; press again to drop it at the chosen position.
- **ArrowUp / ArrowDown:** Move the lifted item (main axis of a vertical list / a whole row in a grid / between columns in a horizontal Board).
- **ArrowLeft / ArrowRight:** Move the lifted item along the horizontal axis / one cell in a grid / between Board columns (RTL-aware).
- **Home / End:** Send the lifted item to the first / last position.
- **Escape:** Cancel the drag and restore the item to its original position. Works for pointer drags too — a window-level listener for the drag's duration, so it cancels even when the activator isn't focused (Safari doesn't focus buttons on mousedown).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 2.5.7 Dragging Movements (AA); 4.1.2 Name, Role, Value (A); 4.1.3 Status Messages (AA)
- The drag activator — a dedicated Sortable.Handle button, or the Sortable.Item itself when it has no handle — is a real button with an accessible name, aria-roledescription="sortable", and aria-describedby pointing at a shared visually-hidden keyboard-instructions node that the Sortable root injects into document.body on mount (id `garn-sortable-instructions`, idempotent by id) — consumers render nothing for it. Composing a handle keeps semantic <li>/<tr>/treeitem rows intact (a role=button on the row would break their list/grid/tree semantics), so headless integrations (List, Tree) drag via a handle.
- Keyboard drag mode: Space or Enter on the activator lifts the item; the arrow keys move it (↑/↓ for a vertical list, ←/→ for horizontal, the cross-axis hops between columns in a Board, spatial in a grid); Home/End jump to the first/last position; Space or Enter drops and commits; Escape cancels and restores. Focus follows the item throughout.
- A polite aria-live region announces pick-up, each position change, drop, and cancel ("Picked up X. Position 2 of 5." … "Dropped X. Position 3 of 5."). The four messages are overridable via `announcements` for domain language (e.g. "Moved to Done"). Multi-item drags announce the count.
- Motion is not required to operate: the dragged item follows the pointer with no transition (the drag itself), sibling gaps smooth under `--garn-motion-fast` and collapse to instant under prefers-reduced-motion; on touch a long-press (default 140ms) starts a drag so a swipe still scrolls the list.
- **Focus:** The drag activator (a Sortable.Handle, or the bare Sortable.Item) is a focusable button; focus stays on the moved item after a keyboard drop or cancel. Don't strip the focus ring.
- **Contract (error):** The drag activator must have an accessible name (Sortable.Handle defaults to "Drag to reorder"; override via `label`, or name the item). — _when a Sortable.Handle (or a bare-item activator) is icon-only_
- **Contract (warn):** No consumer markup is needed: the Sortable root injects one shared visually-hidden keyboard-instructions node (id `garn-sortable-instructions`) into document.body on mount — idempotent by id — and every activator's aria-describedby points at it. Don't remove that node or hand-render a duplicate; to change the spoken text, override `announcements`. — _when any Sortable (or the useSortable hook) is rendered_

## Tokens
- `itemGap` → `--garn-gap-stack` (air)
- `columnGap` → `--garn-gap-inline` (air)
- `motion` → `--garn-motion-fast` (air)
- `easing` → `--garn-ease-standard`
- `indicator` → `--garn-brand-solid`

## Related
- **composes** → `utils`
- **composes** → `use-controllable-state` (when each container's ordered `value` is controlled/uncontrolled)
- **composes** → `use-announce` (when pick-up / move / drop / cancel are announced to a shared polite live region)
- **pairsWith** → `list` (when List's `reorderable` + List.DragHandle drive row reorder through the useSortable hook)
- **pairsWith** → `tree` (when Tree's drag-reparent (`reorderable` + Tree.DragHandle) drives node move-between-parents through the useSortable hook)
- **pairsWith** → `table` (when row reorder in a data table composes the useSortable hook (a recipe))
- **pairsWith** → `badge` (when a dragged card / row carries a status badge)
- **alternativeTo** → `resizable` (when the interaction is dragging a divider to resize panes, not reordering items)

## Recipes
- **sortable-list** — A single reorderable list — drag items (or a grip handle) to change their order, keyboard-operable. _(use when letting users reorder a list of items by drag)_
- **kanban-board** — A Kanban board — cards reorder within a column and move between columns via a Sortable.Group of columns; a portal overlay follows the pointer. _(use when moving cards between columns and reordering within them)_
- **sortable-grid** — A wrapping 2D grid of tiles reordered by drag — spatial arrow-key keyboard, drop indicator. _(use when reordering tiles/images in a wrapping grid)_
- **multi-item-drag** — Select several items and drag them together — the set gathers contiguously at the drop, a count badge on the grabbed item. _(use when moving multiple selected items at once)_

## Gotchas
- **A row's button/link isn't clickable, or clicking it starts a drag.** — The bare Sortable.Item is the drag activator, so an interactive child conflicts with the drag (and the activation guard blocks the drag when you press a child button). → Add a <Sortable.Handle> to the row — only the handle starts a drag, and the rest of the row (buttons, links, inputs) stays interactive.
- **Wiring Sortable onto a semantic <li>/<tr>/treeitem breaks its list/grid/tree accessibility (axe flags role=button on li).** — The bare-item activator adds role=button, which is invalid on <li>/<tr>/treeitem. → Use the useSortable hook with a handle: spread getItemProps(id, { handle: true }) on the row (ref + drag data only, NOT role) and getHandleProps(id) on a grip button. This is exactly how List.DragHandle / Tree.DragHandle work.
- **The whole row drags (role=button, double tab stop) even though a handle is rendered — the handle lives inside your own component.** — Handle auto-detection walks the JSX passed as Sortable.Item children; a Sortable.Handle rendered *inside* one of your components never appears in that JSX, so the item can't see it. → Declare it: <Sortable.Item hasHandle> (or Board.Card hasHandle). The walk stays as the fallback for directly-nested handles.
- **In a Board, the dragged card gets clipped when it leaves a column.** — Cross-container drags need a portal ghost; a column's overflow clips the self-translated item. → Render a <Sortable.Overlay>{(value) => <Card id={value}/>}</Sortable.Overlay> inside the Sortable.Group.
- **The list can't be scrolled by touch on mobile.** — Setting touch-action:none on rows, or expecting an immediate touch drag. → Don't set touch-action yourself — the whole-item touch sensor is a long-press (touchDelay, default 140ms), so a quick swipe scrolls and a hold picks up. Use a handle for immediate touch drag.
- **Dragging one of several selected items only moves that one.** — The selection isn't passed to Sortable. → Pass the selected keys as `selectedValues` — grabbing a selected item then drags the whole set contiguously to the drop.
- **You can't find a `Sortable.Instructions` component to render, or wonder how each activator's aria-describedby resolves.** — There is no Sortable.Instructions part — the keyboard-instructions node is not something you render. → Render nothing for it: the Sortable root injects one shared visually-hidden node (id `garn-sortable-instructions`) into document.body on mount, and every activator's aria-describedby points at it. To customize the spoken pick-up/move/drop/cancel text, pass `announcements`.

## Examples
- **basic** (canonical): A single vertical list — whole-item drag, keyboard-operable, with the shared instructions node.
- **handle** (edge-case): A list with a grip handle + interactive row content (badge, menu button) — only the handle drags, so the button stays clickable.
- **horizontal** (edge-case): Horizontal reorder — a row of chips, ←/→ keyboard.
- **board** (edge-case): A Kanban board — Sortable.Group of columns + a Sortable.Overlay; cards move between columns.
- **multi-item** (edge-case): Multi-item drag — click to select, then drag one selected item to move the whole set (count badge).
- **grid** (edge-case): A wrapping 2D grid (orientation=grid) — closest-center projection, spatial ←/→ ↑/↓ keyboard, drop indicator.
- **drop-indicator** (edge-case): The built-in insertion line (dropIndicator) + onDragOver reporting the live target slot.
- **scrollable** (edge-case): A tall list in a fixed-height scroll container — edge auto-scroll drags past the fold; long-press on touch.
- **headless** (edge-case): The useSortable hook wired onto a consumer's own <ul>/<li> markup (the List/Tree integration pattern).

## Source map

Regions in `sortable.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–19 (18 lines) — React, DOM, icon, and lib imports
- `types` L20–87 (68 lines) — overview doc, orientation, announcements vocabulary
- `model` L88–184 (97 lines) — machine model: containers, drag state, coordinator
- `context` L185–200 (16 lines) — coordinator/container/item contexts and guard hook
- `utils` L201–245 (45 lines) — reorder, activation guard, keyboard instructions node
- `prop-builders` L246–396 (151 lines) — shared item/handle DOM prop builders
- `options` L397–498 (102 lines) — machine options, defaults, prop splitting
- `machine` L499–1315 (817 lines) — drag machine: projection, auto-scroll, pointer, keyboard
- `root` L1316–1467 (152 lines) — Sortable root, standalone machine, droppable container
- `group` L1468–1525 (58 lines) — Sortable.Group: cross-column Board coordinator
- `item` L1526–1665 (140 lines) — Sortable.Item, drop line, handle detection
- `handle` L1666–1722 (57 lines) — Sortable.Handle drag-affordance button
- `overlay` L1723–1756 (34 lines) — Sortable.Overlay portal ghost
- `use-sortable` L1757–1926 (170 lines) — headless useSortable core: order + prop getters
- `exports` L1927–1952 (26 lines) — compound component assembly and exports

---

# Sparkline

> A compact, inline trend line/area/bar — a chart small enough to sit in a sentence or a tile.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Sparkline } from "@garn/ui/sparkline"`

## Overview
Sparkline is the mini-viz of the chart group: a small, axis-less line, area, bar, or win/loss strip that shows shape and direction at a glance — trends in a table cell, a KPI tile, or a Stat. It reserves none of a full chart's chrome (no axes, legend, or tooltip); when you need those, reach for Chart. Because it's pure SVG with no hooks, it renders on the server and stays essentially free to drop in anywhere.

## When to use
Show a trend inline — in a Stat tile, a table row, or beside a KPI — where a full chart's axes and legend would be overkill.

## When not to use
You need axes, a tooltip, a legend, or precise reads (use Chart); a single value vs a target (use Gauge or Bullet).

## Do / Don't
- ✅ Tone it with a `text-*` token utility and give it an accessible label (or `aria-hidden` when decorative).
- ✅ Use `showEndDot`/`showExtrema` to mark the current value and the high/low.
- ❌ Don't expect exact values to be readable — a sparkline shows shape.
- ❌ Don't reach for it when the data needs axes or interaction — that's Chart.

## Guidelines
**Show shape, not exact values.** A sparkline conveys direction and volatility; pair it with a real number (a Stat value, a delta) when the precise figure matters — the spark alone isn't readable to the decimal.

**Tone it with a token.** Colour comes from `currentColor`, so set it with a `text-*` utility (`text-chart-1`, `text-success`). The `winloss` variant is the exception — it's sign-coloured with the positive/negative tokens, so its up/down meaning holds without relying on colour alone.

**Label it honestly for assistive tech.** Standalone, give it an `aria-label`. When it sits next to a value that already names it (Stat.Trend), mark it `aria-hidden` so screen readers aren't told the same thing twice.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `curve` | `"linear" \| "monotone" \| "natural"` | — | no | Smoothing for `line` / `area`. |
| `data` | `number[]` | — | yes | The series, in order. Empty renders nothing; one point renders a dot. |
| `fillOpacity` | `number` | — | no | Fill alpha for the `area` variant. |
| `height` | `number` | — | no |  |
| `referenceBand` | `[number, number]` | — | no | A shaded "normal range" band behind the trend, in data units: `[low, high]`. |
| `referenceLine` | `number` | — | no | A dashed horizontal reference/threshold line, in data units (target, 0, …). |
| `showEndDot` | `boolean` | — | no | Mark the last (current) value with a solid dot. |
| `showExtrema` | `boolean` | — | no | Mark the min (faded) and max (solid) points with dots. |
| `variant` | `"area" \| "bar" \| "line" \| "winloss"` | — | no | `line` (default), filled `area`, discrete value `bar`s, or `winloss` — equal ± ticks from a centre line for binary outcomes (up/down days, wins/losses). |
| `width` | `number` | — | no | viewBox coordinate space; the SVG scales to its CSS box (e.g. `w-full`). |

_Plus 484 inherited native `<svg>` attributes._

## Anatomy
- `sparkline`: The `<svg>` (role=img). One stroked path (line), a fill path + line (area), rects (bar), or ± ticks (winloss).

## Accessibility
- **Role:** img
- **WCAG:** 1.1.1 Non-text Content (A)
- role=img with an `aria-label` names the trend for a standalone spark.
- Beside an already-labelled value (e.g. inside Stat.Trend) mark it `aria-hidden` — the value carries the meaning.
- Colour is inherited via currentColor; winloss uses the positive/negative tokens, so its meaning survives without colour.

## Related
- **composes** → `utils`
- **pairsWith** → `stat` (when docked in Stat.Trend as the tile's trend visual)
- **alternativeTo** → `chart` (when the data needs axes, a tooltip, or a legend)

## Gotchas
- **Empty output.** — `data` is empty — a sparkline needs points. → Pass a non-empty `number[]`; a single value renders a dot.
- **Screen readers announce the spark twice next to a Stat.** — Both the Stat value and the spark carry a name. → Mark a decorative spark `aria-hidden`.
- **Setting `text-*` didn't recolour the winloss bars.** — winloss is sign-coloured with the positive/negative tokens by design. → That's intended — winloss ignores the inherited colour so up/down reads without colour alone.

## Examples
- **basic** (canonical): A toned line sparkline trending up.
- **variants** (edge-case): line · area · bar side by side.
- **in-stat** (edge-case): An area spark docked in Stat.Trend (aria-hidden).
- **reference** (edge-case): A normal-range band + a dashed target line.
- **markers** (edge-case): End dot + min/max extrema.
- **win-loss** (edge-case): Binary ± ticks, sign-coloured.

---

# Spinner

> An animated indicator for an indeterminate loading state.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** feedback
- **Import:** `import { Spinner } from "@garn/ui/spinner"`

## Overview
Spinner indicates an indeterminate loading or pending state — inline, beside a label, or inside a control — when you can't report a percentage. Its `size` follows the same glyph ramp as button icons so it sits cleanly within text and buttons. Use it for short, unknown-duration waits; for a known fraction use Progress, and to reserve a known content shape use a Skeleton.

## When to use
Indicate an indeterminate loading or pending state, inline or inside a control.

## When not to use
For determinate progress (use a progress bar) or content placeholders (use a skeleton).

## Do / Don't
- ✅ Give it an accessible name describing what's loading.
- ✅ Match the size to the surrounding control.
- ❌ Don't block the whole UI with a bare spinner where a skeleton would preserve layout.

## Guidelines
**Use a spinner when duration is unknown and brief.** It says "working" without a number; if you can show real progress, a determinate bar is more reassuring, and for laying out incoming content a Skeleton prevents the jump.

**Show it in context and accompany long waits.** Put the spinner where the result will appear (in the button, beside the row) rather than blanking the whole screen; past a couple of seconds, add a word of context so users aren't left guessing.

**Announce loading and respect motion.** Give the loading region an accessible "loading" state (e.g. `aria-busy`/label) so it's not a silent spin, and honor reduced-motion. Don't leave a spinner running forever — resolve to content, empty, or an error.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |

_Plus 489 inherited native `<svg>` attributes._

## Variants
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## Anatomy
- `spinner`: The spinning <svg> (a lucide LoaderCircle).

## Accessibility
- **Role:** status
- **WCAG:** 2.3.3 Animation from Interactions (AAA)
- role=status with a default aria-label of “Loading”.
- Override aria-label to describe the specific action (e.g. “Saving changes”).
- Animation is paused under prefers-reduced-motion (library-wide guard).

## Related
- **composes** → `utils`
- **alternativeTo** → `progress` (when the duration is known (determinate))
- **alternativeTo** → `skeleton` (when loading content that has a known layout)
- **pairsWith** → `button` (when Button renders its own spinner via `loading`)

## Gotchas
- **Screen reader announces nothing useful while loading.** — The default aria-label is the generic “Loading”. → Pass a specific aria-label, or rely on Button's `loading` (which sets aria-busy) inside a control.

## Examples
- **basic** (canonical): The default spinner.
- **sizes** (playground): The size ramp (xs–xl).
- **labeled** (edge-case): Override the default aria-label.

---

# Stat

> The KPI / metric tile a dashboard opens with — a labelled number with an optional sentiment-aware delta, an icon, a description, and a chart-agnostic trend slot. Terse one-liner or full slot composition; Stat.Group lays a responsive row of tiles.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Stat } from "@garn/ui/stat"`
- **Polymorphism:** `asChild` (default element `<div>`)

## Overview
Stat is a headline metric for a dashboard, overview, or report — a labelled number with an optional period-over-period delta, an icon, supporting copy, and a trend slot. `Stat.Value` Intl-formats a numeric child (tabular-nums), `Stat.Label` names it (and the value `aria-describedby`s it), and `Stat.Delta` colors itself by good/bad with a directional arrow announced in words. `Stat.Group` lays out a responsive row of related KPIs. It's for a single key figure — for many rows of records use a Table.

## When to use
A headline metric on a dashboard / overview / report — a labelled number with an optional period-over-period delta, an icon, supporting copy, and a trend slot. Use Stat.Group for a responsive row of related KPIs.

## When not to use
An inline numeric token next to a label (use Counter or Badge); a single progress bar toward a goal (use Progress); a generic surface or content panel (use Card — Stat composes onto it); tabular numbers in rows and columns (use Table).

## Do / Don't
- ✅ Name every metric (label / Stat.Label / aria-label) — the value alone is unscannable.
- ✅ Use `sentiment="inverse"` for metrics where up is bad (churn, latency, cost, error rate) so the delta colours correctly.
- ✅ Wrap a Stat in Card when you want a surface — Stat stays surface-less so it also lives in a cell / list / popover.
- ✅ Format numbers in-component (format / currency / precision / locale) rather than pre-stringifying, so tabular-nums and locale stay consistent.
- ✅ Use `loading` to hold the tile's footprint while data resolves.
- ❌ Don't encode good/bad with a raw colour prop — there is none by design; let direction × sentiment resolve the tone.
- ❌ Don't bake a surface into the Stat — compose Card around it.
- ❌ Don't put a chart library inside Stat.Value; drop the visual into Stat.Trend (the reserved, chart-agnostic slot).
- ❌ Don't strip the sr-only direction phrase or the focus ring on an asChild tile.

## Guidelines
**Show the few numbers that matter, with context.** A KPI tile earns attention only if it's genuinely headline; a wall of stats dilutes them all. A bare number means little — pair it with a label and, where relevant, a delta or comparison period.

**Make the delta's meaning unambiguous.** Up isn't always good (churn, cost), so let the tone follow good/bad sentiment rather than direction alone, and state the comparison ("vs last week"). The arrow and sr-only wording keep it accessible.

**Keep figures aligned and formatted.** Lean on the Intl formatting and tabular numerals so digits line up across a `Stat.Group`, use consistent units/precision, and let `Stat.Description` carry caveats instead of cramming them into the value.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `align` | `"center" \| "end" \| "start"` | `start` | no |  |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |
| `asChild` | `boolean` | — | no | Render as the child element (a link/button drill-down tile). |
| `delta` | `React.ReactNode` | — | no | Terse: the change. Number infers direction from its sign. |
| `deltaAppearance` | `StatDeltaAppearance` | — | no | Delta presentation — `text` (default) or `soft` lozenge. |
| `deltaFormat` | `StatNumberFormat` | — | no | How the terse `delta` is formatted. Default `percent` (the KPI convention). |
| `deltaPrecision` | `number` | — | no | Fraction digits for the terse `delta`. |
| `description` | `React.ReactNode` | — | no | Terse: supporting copy under the value. |
| `direction` | `StatDirection` | — | no | Override the delta's inferred direction. |
| `icon` | `React.ReactNode` | — | no | Terse: leading icon (decorative). |
| `label` | `React.ReactNode` | — | no | Terse: the metric's name. |
| `loading` | `boolean` | — | no | Swap the value/label/delta for sized Skeleton blocks; keeps the footprint. |
| `prefix` | `React.ReactNode` | — | no | Rendered before the value. |
| `sentiment` | `StatSentiment` | — | no | What "good" means for the delta. Default `positive`. |
| `suffix` | `React.ReactNode` | — | no | Rendered after the value. |
| `trend` | `React.ReactNode` | — | no | Terse: a trend visual slot (sparkline / progress) at the foot. |
| `value` | `React.ReactNode` | — | no | Terse: the headline value (number → Intl-formatted, or any node). |

_Plus 282 inherited native `<div>` attributes._

### `Stat.Value` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | no | A number (formatted via Intl) or any node (rendered verbatim, e.g. "—"). |
| `prefix` | `React.ReactNode` | — | no | Rendered before the value (a unit, "$"). |
| `suffix` | `React.ReactNode` | — | no | Rendered after the value (a unit, "ms", "/mo"). |

_Plus 282 inherited native HTML attributes._

### `Stat.Delta` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `StatDeltaAppearance` | — | no | `text` (coloured inline arrow, default) or `soft` (a tinted lozenge). |
| `children` | `React.ReactNode` | — | no | The change. A number formats via Intl + infers direction from its sign. |
| `direction` | `StatDirection` | — | no | Override the inferred direction (defaults to the sign of a numeric child). |
| `hideIcon` | `boolean` | — | no | Hide the directional arrow glyph. |
| `label` | `string` | — | no | Accessible phrasing of the change, when the value alone isn't self-describing. |
| `sentiment` | `StatSentiment` | — | no | What "good" means — flips which direction reads green. Default `positive`. |
| `trailing` | `React.ReactNode` | — | no | Trailing context, rendered muted ("vs. last week"). |

_Plus 282 inherited native HTML attributes._

### `Stat.Group` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `columns` | `number` | — | no | Number of columns. Default: auto-fit by min tile width. |
| `divided` | `boolean` | — | no | Seam separators between tiles (the divided stat-row look). |
| `label` | `React.ReactNode` | — | no | Accessible name for the group of metrics. |
| `minTileWidth` | `number` | — | no | Min tile width for the auto-fit grid (when `columns` is unset). Default 220. |
| `size` | `StatSize` | — | no | Ambient size inherited by child Stats (each may override). Default `md`. |

_Plus 280 inherited native HTML attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`
- **align** (default `start`): `start`, `center`, `end`

## Anatomy
- `stat`: The tile — a surface-less role=group <div> (or the asChild element, e.g. a drill-down link). Composes onto Card; never bakes a surface in.

**Parts**
- `Stat.Icon` (`stat-icon`): Leading glyph (decorative, aria-hidden). Sizes with the tile.
- `Stat.Label` (`stat-label`): The metric's name. Registers itself so the value can aria-describedby it; truncates.
- `Stat.Value` (`stat-value`): The headline number — a numeric child is Intl-formatted; any node renders verbatim. tabular-nums. Hosts stat-value-prefix / stat-value-suffix.
- `Stat.Delta` (`stat-delta`): The change indicator — tone follows good/bad (direction × sentiment), shows a directional arrow, and announces the direction in words (sr-only). Hosts an optional stat-delta-trailing.
- `Stat.Description` (`stat-description`): Supporting copy under the value.
- `Stat.Trend` (`stat-trend`): A bare, presentational slot for a trend visual (sparkline / progress / mini bar). Stat ships no charting dep — it only reserves the box for the future Chart recipe.
- `Stat.Group` (`stat-group`): A responsive role=group grid of tiles. Props: columns (fixed tracks) or minTileWidth (auto-fit), divided (seam separators), size (ambient, inherited by child Stats), label (accessible name). Hosts stat-group-label.

## Accessibility
- **Role:** group
- **WCAG:** 1.3.1 Info and Relationships (A); 1.4.1 Use of Color (A); 1.4.3 Contrast (Minimum) (AA); 4.1.2 Name, Role, Value (A)
- The tile is a role=group named by its label (or aria-label); the value is aria-describedby its label so screen readers read 'label, value' together.
- The delta's direction reaches AT in words via an sr-only phrase ('up 12.5%') — colour and the arrow glyph are never the only signal (WCAG 1.4.1).
- The icon and the directional arrow are decorative (aria-hidden); the trend slot is role=presentation.
- asChild turns the whole tile into a focusable drill-down link/button — keep the focus ring; the label/value/delta are injected as that element's children.
- **Focus:** No focus of its own unless asChild makes it a link/button, which keeps a 2px --garn-ring focus ring.
- **Contract (warn):** Give the metric a name via `label`, a <Stat.Label>, or `aria-label` so the value is scannable and announced. — _when a Stat has no `label`, no <Stat.Label>, and no `aria-label` (and isn't loading)_

## Tokens
- `gap` → `--garn-gap-stack` (air)
- `deltaPositive` → `--garn-success`
- `deltaNegative` → `--garn-danger`
- **Internal (never externalize):** `--d-fg`

## Related
- **composes** → `utils`
- **composes** → `skeleton` (when the `loading` preset swaps in sized Skeleton blocks)
- **pairsWith** → `card` (when Card is the surface and Stat is the content (<Card><Stat …/></Card>))
- **pairsWith** → `progress` (when a Progress drops into the Stat.Trend slot as a goal bar)
- **pairsWith** → `table` (when a bare Stat renders inside a summary table cell)
- **alternativeTo** → `counter` (when the figure is an inline numeric token beside a label, not a headline tile)
- **alternativeTo** → `progress` (when the metric is progress toward a single goal rather than a value + delta)

## Recipes
- **kpi-tile** — A carded KPI tile — Card surface around a terse Stat with an icon and a sentiment-aware delta. _(use when showing a single headline metric on a dashboard)_
- **dashboard-stat-row** — A responsive row of related KPIs with seam separators. _(use when a dashboard opens with a row of 3–5 related metrics)_

## Gotchas
- **An up-is-bad metric (churn / latency / cost) shows green when it rises.** — Direction maps to tone through `sentiment`, which defaults to `positive` (up = good). → Pass `sentiment="inverse"` so a rise reads red and a fall reads green.
- **The terse `delta` prints as a tiny fraction or the wrong unit.** — The delta defaults to `percent` formatting (the KPI convention), independent of the value's format. → Pass an absolute number for percent (0.125 → 12.5%), or set `deltaFormat="standard"` / `"currency"` for a non-percent change.
- **The tile has no border / background.** — Stat is surface-less by design so it composes anywhere. → Wrap it in a Card (or any surface) — don't add ad-hoc padding/border to the Stat.
- **A dev console warns the Stat has no name.** — No `label`, <Stat.Label>, or `aria-label` was provided. → Give the metric a name so the value is scannable and announced.
- **asChild throws or doesn't render the number.** — Slot needs exactly one element child; the label/value/delta are injected into it. → Pass a single element (e.g. an <a>) as the child; keep terse props on the Stat for the injected stack.

## Examples
- **basic** (canonical): The terse one-liner — label, compact value, percent delta.
- **carded** (edge-case): Composed onto Card with an icon, currency value, and description.
- **delta-sentiment** (edge-case): Same numbers, different meaning — sentiment="inverse" colours an up-is-bad metric red.
- **delta-appearance** (edge-case): text (inline coloured arrow) vs soft (a tinted lozenge).
- **formats** (edge-case): currency · compact · percent · suffix unit · a raw node value.
- **sizes** (edge-case): sm · md · lg.
- **trend** (edge-case): A token-styled sparkline dropped into the chart-agnostic Trend slot.
- **loading** (edge-case): The loading preset holds the footprint with Skeleton blocks.
- **group** (edge-case): Stat.Group — a four-column responsive row of KPIs.
- **group-divided** (edge-case): Stat.Group with seam separators inside a Card.
- **group-cards** (edge-case): A row of individually carded tiles (auto-fit by minTileWidth).
- **composed** (edge-case): Full control via slots — Stat.Icon / .Label / .Value / .Delta / .Description.
- **link** (edge-case): asChild turns the whole tile into a drill-down link with a focus ring.

---

# Stepper

> Guide a user through an ordered, often-gated process — showing where they are, what's done, and what's left.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** navigation
- **Import:** `import { Stepper } from "@garn/ui/stepper"`
- **Polymorphism:** `asChild` (default element `<button>`)

## Overview
Stepper guides a user through an ordered, often-gated process — a checkout, an onboarding wizard, a multi-section form — showing where they are, what's done, and what's left. `StepperList` holds each `Step` (with its `StepIndicator`, `StepTitle`, and `StepSeparator`), reflecting complete / current / upcoming state. Use it for sequential, dependent steps; for switching between peer views use Tabs, and to show where a page sits in a site hierarchy use Breadcrumb.

## When to use
Guide a user through an ordered, often-gated process — a checkout, an onboarding wizard, a multi-section form — showing where they are, what's done, and what's left.

## When not to use
Switching between peer views in any order (use tabs); showing where a page sits in a hierarchy (use breadcrumb); moving through a paged result set (use pagination); a single open/close region (use collapsible).

## Do / Don't
- ✅ Give the step list an accessible name (the Stepper `label`, or aria-label on StepperList).
- ✅ Control the active step via `value` + `onValueChange`, or leave it uncontrolled with `defaultValue` — the value is the 0-based INDEX.
- ✅ Gate forward moves with `onBeforeStepChange` (return false / a Promise of it); Back is always free.
- ✅ Add StepContent panels (matched by position) to own the content, or omit them for a route-based wizard.
- ✅ Use `linear` (default) for a gated flow; pass `linear={false}` to let any step be clicked.
- ❌ Don't use a stepper for unordered peer views — that's tabs.
- ❌ Don't pass a step id to `value`; it's the 0-based step index.
- ❌ Don't combine `variant="dot"` with `look` expecting a change — dots are look-agnostic.
- ❌ Don't strip the focus ring or the aria-current wiring — they are the keyboard + screen-reader contract.

## Guidelines
**Use a stepper only for a genuine sequence.** It implies order and progress — right for a flow with dependent stages, wrong for independent sections (that's Tabs). Keep the number of steps small and group sub-tasks rather than exposing a dozen.

**Always communicate position and status.** Make the current step, completed steps, and what remains obvious; name each step by its outcome ("Shipping", "Payment") so users can anticipate the path. Show validation per step before advancing.

**Be clear about gating and back-navigation.** If steps are gated, explain why a later step is locked; let users go back to completed steps without losing data. Keep it keyboard-navigable and announce step changes for assistive tech.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `labelPlacement` | `"bottom" \| "end"` | `end` | no | Horizontal only: label beside the indicator (`end`) or under it (`bottom`). |
| `look` | `"filled" \| "outline"` | `filled` | no | Visual language for numbered indicators: solid `filled` circles (default) or the Carbon-style `outline` look (dashed upcoming, dark-neutral complete, `!` on error, per-step top tails in horizontal). Dots are look-agnostic. |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | no |  |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |
| `variant` | `"dot" \| "numbered"` | `numbered` | no | Indicator shape: numbered circle (default) or a dot. |
| `defaultValue` | `number` | — | no | Uncontrolled initial active step index. |
| `label` | `string` | — | no | Accessible name for the step list (the `nav` landmark). |
| `linear` | `boolean` | — | no | Gate forward navigation (default true); non-linear lets any step be clicked. |
| `onBeforeStepChange` | `(details: BeforeStepChangeDetails) => boolean \| Promise<boolean>` | — | no | Async forward-gate. Return `false` (or a Promise of it) to block the move; the target indicator shows a spinner while pending. Back is never gated. |
| `onValueChange` | `(index: number) => void` | — | no |  |
| `value` | `number` | — | no | Controlled active step index (0-based). |

_Plus 278 inherited native `<button>` attributes._

### `Step` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `completedIcon` | `React.ReactNode` | — | no | Custom completed indicator (overrides the check). |
| `description` | `React.ReactNode` | — | no | Terse mode: secondary text under the title. |
| `disabled` | `boolean` | — | no |  |
| `error` | `boolean` | — | no | Mark the step as failed. |
| `icon` | `React.ReactNode` | — | no | Custom indicator content (overrides the number/dot). |
| `loading` | `boolean` | — | no | Show a spinner in the indicator (e.g. this step is processing). |
| `optional` | `boolean` | — | no | Mark the step optional (renders an "Optional" caption). |
| `subStep` | `boolean` | — | no | Render as a smaller sub-step dot in the rail (a finer-grained marker that still counts in the sequence). Best in vertical orientation. |
| `title` | `React.ReactNode` | — | no | Terse mode: the step's label. |
| `value` | `string` | — | no | Stable id, used to match a `StepContent` panel by value (optional). |

_Plus 278 inherited native HTML attributes._

### `StepContent` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `string` | — | no | Match this panel to a step by its `value` (otherwise matched by position). |

_Plus 280 inherited native HTML attributes._

## Variants
- **orientation** (default `horizontal`): `horizontal`, `vertical`
- **variant** (default `numbered`): `numbered`, `dot`
- **look** (default `filled`): `filled`, `outline`
- **size** (default `md`): `sm`, `md`, `lg`
- **labelPlacement** (default `end`): `end`, `bottom`

## Anatomy
- `stepper`: The state container (a <div>) — owns the active step index, the async gate, and reflects data-orientation / data-variant / data-look / data-size. Holds the polite live region.

**Parts**
- `StepperList` (`stepper-list`) · required: The step rail — a <nav> landmark wrapping an <ol>. Give it an accessible name via `aria-label` (or the Stepper `label` prop). Counts and indexes its Step children.
- `Step` (`step`) · required: One step — an <li>. Terse mode: pass title / description / icon / completedIcon / optional / error / disabled / loading / subStep. Compound mode: compose StepIndicator / StepTitle / … as children. The active step's li carries aria-current="step"; data-state reflects upcoming | current | complete | error | disabled.
- `StepIndicator` (`step-indicator`): The circle/dot (aria-hidden). Numbered renders the step number → ✓ on complete → ✕/! on error → a custom icon → a spinner while the async gate is pending. Dots are look-agnostic.
- `StepSeparator` (`step-separator`): The connector between steps. Fills (scaleX/scaleY of --stepper-progress) once the preceding step is complete; data-state = complete | incomplete.
- `StepTitle` (`step-title`): The step's label; its id labels the matching StepContent panel.
- `StepDescription` (`step-description`): Secondary text under the title (also renders the 'Optional' caption).
- `StepContent` (`step-content`): A per-step panel (role=region) matched to a step by position; labelled by its StepTitle, hidden when inactive, tabIndex=0 when active. Omit for an indicator-only or route-based stepper.
- `StepperCompleted` (`stepper-completed`): The done-state panel — rendered only once the active index passes the last step.
- `StepperPrevTrigger` (`stepper-prev-trigger`): A back button — auto-disabled at the start. asChild to wrap a custom Button. Back is never gated.
- `StepperNextTrigger` (`stepper-next-trigger`): A next button — auto-disabled at the end and while the async gate is pending (data-loading). asChild to wrap a custom Button.

## Accessibility
- **Role:** navigation
- **Tab:** Move between interactive controls — clickable steps and the Prev/Next triggers.
- **Enter / Space:** Activate the focused step (non-linear) or Prev/Next trigger.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The root is a <nav> landmark > <ol>; each Step is an <li>; the active step's <li> (and its trigger, if interactive) carries aria-current="step".
- Indicators are aria-hidden; status reaches assistive tech via a single role=status, aria-live=polite region announcing "Step N of M: <title>".
- StepContent is role=region, aria-labelledby its StepTitle id, hidden when inactive; an interactive step aria-controls its panel ONLY when one exists.
- The tablist model is deliberately avoided — it implies free navigation that conflicts with linear gating, and the roles-without-keyboard-contract trap.
- Give the step list an accessible name via the Stepper `label` prop or aria-label on StepperList.
- **Focus:** 2px ring in --garn-ring + offset on interactive step triggers, Prev/Next, and the active panel.
- **Reviewed:** 2026-06-26 by design-systems
- **Contract (warn):** Give the step list an accessible name via the Stepper `label` prop, or `aria-label` on StepperList. — _when the StepperList has no `aria-label` / `aria-labelledby` and the Stepper has no `label`_

## Tokens
- `sectionGap` → `--garn-gap-section` (air)
- `motion` → `--garn-motion-base`
- `ring` → `--garn-ring` · brandable
- **Internal (never externalize):** `--stepper-progress`

## Related
- **composes** → `utils`
- **composes** → `spinner` (when the target indicator shows a spinner while the async gate is pending)
- **pairsWith** → `button` (when StepperPrevTrigger / StepperNextTrigger wrap a Button via asChild)
- **pairsWith** → `form` (when onBeforeStepChange maps to react-hook-form's await trigger() to validate a step before advancing)
- **alternativeTo** → `tabs` (when the views are peers reachable in any order, not an ordered/gated sequence)
- **alternativeTo** → `breadcrumb` (when the goal is showing location in a hierarchy, not progress through a flow)
- **alternativeTo** → `pagination` (when the goal is moving through a paged result set, not completing steps)

## Recipes
- **form-wizard** — A multi-step form: position-matched StepContent panels, Prev/Next triggers, and an async forward-gate that validates each step. _(use when a user must complete an ordered set of steps, validating before advancing)_

## Gotchas
- **Passing a step name/id to `value` does nothing or jumps to the wrong step.** — `value` / `defaultValue` is the 0-based step INDEX, not a step id. → Pass the index (0, 1, 2…); read the index back from onValueChange.
- **variant="dot" + look="outline" looks identical to look="filled".** — Dots are look-agnostic — `look` only affects numbered indicators. → Use `look` with the default numbered variant; for dots, drop `look`.
- **Next advances immediately even though validation should block it.** — onBeforeStepChange isn't returning false (or a Promise resolving to false) to veto the move. → Return false / Promise<false> to block; the target indicator shows a spinner while the promise is pending. Back is never gated.
- **Clicking Back runs the validation gate.** — Expecting the gate to fire on both directions. → By design, only forward moves are gated; Back is always free.
- **The StepContent panel never shows.** — Panels are matched to steps by POSITION (declaration order), not by a value prop. → Render StepContent panels in the same order as the Steps; the Nth panel pairs with the Nth step.
- **A dev console warns the step list has no accessible name.** — Neither the Stepper `label` nor StepperList aria-label is set. → Pass `label` on Stepper (or aria-label on StepperList).

## Examples
- **horizontal** (canonical): A horizontal checkout — labels beside the indicators, filled connectors behind completed steps.
- **label-below** (edge-case): labelPlacement="bottom" — labels under each indicator.
- **vertical** (edge-case): A vertical flow-rail timeline.
- **sub-steps** (edge-case): subStep — finer dot markers nested under a milestone (best in vertical).
- **dots** (edge-case): variant="dot" — minimal dot indicators.
- **custom-icons** (edge-case): A per-step `icon` that persists across states.
- **outline** (edge-case): look="outline" — the Carbon language (dashed upcoming, dark-neutral complete, ! error, per-step top tails).
- **states** (edge-case): Every step state — complete · current · error · optional · disabled.
- **loading** (edge-case): `loading` — a spinner in the indicator while a step processes.
- **sizes** (edge-case): sm · md · lg.
- **clickable** (edge-case): linear={false} — click any step to jump (controlled value + onValueChange).
- **wizard** (edge-case): The full wizard — StepContent panels, StepperCompleted, Prev/Next, and an async onBeforeStepChange gate.

## Source map

Regions in `stepper.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–12 (11 lines) — React, Radix Slot, cva, icons, shared hooks
- `types` L13–67 (55 lines) — overview doc, axis aliases, geometry consts
- `utils` L68–82 (15 lines) — text-of walk for the live-region title
- `context` L83–139 (57 lines) — Stepper + Step contexts and their hooks
- `root` L140–354 (215 lines) — Stepper: state, forward-gate, context provider
- `list` L355–419 (65 lines) — StepperList: nav > ol, counts + indexes Steps
- `step` L420–699 (280 lines) — Step: dual-mode li, per-orientation layouts
- `label-group` L700–713 (14 lines) — StepLabelGroup: title/description stack
- `indicator` L714–825 (112 lines) — StepIndicator + its cva variant tables
- `separator` L826–870 (45 lines) — StepSeparator: connector with progress fill
- `labels` L871–913 (43 lines) — StepTitle + StepDescription
- `content` L914–980 (67 lines) — StepContent panels + StepperCompleted
- `triggers` L981–1047 (67 lines) — StepperPrev / NextTrigger nav buttons
- `exports` L1048–1066 (19 lines) — public compound surface

---

# Switch

> An instant on/off toggle for a single setting.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Switch } from "@garn/ui/switch"`

## Overview
Switch flips a setting that takes effect the instant it changes — notifications on/off, dark mode, an enabled feature — with no Save step. The filled track and travelled thumb make the on/off state legible at a glance. If the choice is only confirmed later on submit (a form value), use a Checkbox; if there are more than two states, use a RadioGroup or Select.

## When to use
A setting that applies immediately — no Save step (notifications on/off, dark mode).

## When not to use
A choice submitted with a form on Save (use a checkbox); mutually exclusive options (use radio-group).

## Do / Don't
- ✅ Use for instant-effect settings; reflect the new state without a confirm step.
- ✅ Pair with a label that states what the ON position means.
- ❌ Don't use a switch inside a form that the user must submit — that's checkbox territory.
- ❌ Don't pair a switch with a separate Save button for the same setting.

## Guidelines
**Use a switch only when the change is immediate.** The mental model is a physical toggle: flipping it does the thing now. If you find yourself wanting a Save button for a screen of switches, those should probably be checkboxes instead.

**Label the setting, not the state.** The Label says what the switch controls ("Email notifications") — the on/off position already communicates the state, so don't append "on/off" to the text. Reserve switches for clearly binary settings.

**Reach for `tone` only when the state carries a status.** The default `brand` fill is right for almost every toggle. Use `success`/`warning`/`danger` when the ON position itself signals something (a risky feature flag, a destructive automation) — not for decoration.

**Use `loading` for async toggles.** When flipping runs a request, set `loading` to show the in-thumb spinner and block interaction (it sets aria-busy + disabled) until the real result lands — then reflect it, reverting if it failed. Don't leave the switch looking done while the effect is still in flight.

**Pair it with a Field for anything more than a bare toggle.** A description, a card surface, or a settings row is the Field's job — drop the Switch in as the Field's control so the label, `htmlFor`, and `aria-describedby` are wired for you.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |
| `tone` | `"brand" \| "danger" \| "neutral" \| "success" \| "warning"` | `brand` | no |  |
| `checkedContent` | `React.ReactNode` | — | no | Icon or 1–2 chars shown in the track well while ON (the vacated left side). |
| `loading` | `boolean` | — | no | Shows a spinner in the thumb and blocks interaction (sets `disabled` + `aria-busy`) — for a toggle whose effect resolves asynchronously. |
| `uncheckedContent` | `React.ReactNode` | — | no | Icon or 1–2 chars shown in the track well while OFF (the vacated right side). |

_Plus 293 inherited native `<button>` attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`
- **tone** (default `brand`): `neutral`, `brand`, `success`, `warning`, `danger`

## State model
- `checked` (controlled) / `defaultChecked` (uncontrolled), `onCheckedChange` · boolean — Controlled via `checked` + `onCheckedChange`; uncontrolled via `defaultChecked`.
- Selection: single.

## Anatomy
- `switch`: The track (toggle hit target).
- `thumb`: The sliding knob; travels exactly one track-height on check.

## Accessibility
- **Role:** switch (APG: switch)
- **Space / Enter:** Toggle on / off.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- role=switch with aria-checked; data-state reflects checked / unchecked.
- `loading` sets aria-busy and disables the control while the async effect resolves.
- checkedContent / uncheckedContent are decorative (aria-hidden) — the state is conveyed by aria-checked, not the glyph.
- **Focus:** outline-hidden + 2px ring with a 2px offset.
- **Forced colors:** checked → Highlight so the on-state survives HCM.
- **Contract (warn):** Give every switch an accessible label (a <label htmlFor>, or aria-label). — _when no associated <label> or aria-label/aria-labelledby_

## Tokens
- `trackHeight` → `--garn-box-md` (identity)
- `fill` → `--garn-brand-solid` · brandable
- `fillEdge` → `--garn-brand-strong` · brandable
- `fillOff` → `--garn-muted`
- `ring` → `--garn-ring` · brandable
- **Internal (never externalize):** `--sh`

## Related
- **composes** → `utils`
- **pairsWith** → `label`
- **pairsWith** → `field` (when the setting needs a description or a card surface)
- **composes** → `spinner` (when loading — the in-thumb spinner reuses the spinner glyph)
- **alternativeTo** → `checkbox` (when the choice is submitted with a form rather than applied instantly)

## Recipes
- **labeled-switch** — A switch with an adjacent label describing the setting. _(use when exposing an instant-effect setting)_
- **switch-field** — A switch inside a Field — a settings row or option card with a label + description, wired for a11y. _(use when a toggle needs a description or a card surface)_

## Gotchas
- **The switch flips back instantly / won't move.** — Passing `checked` without `onCheckedChange` makes it controlled and frozen. → Use `defaultChecked` for uncontrolled, or pass `checked` + `onCheckedChange`.
- **No glyph shows inside the track.** — In-track content is opt-in — there is no default glyph. → Pass `checkedContent` (and/or `uncheckedContent`) with an icon or 1–2 characters.
- **A `tone` other than brand doesn't change the OFF track.** — `tone` only colours the ON (checked) track; the OFF track is a neutral surface for every tone. → That's intended — the tone reads as the on-state colour intent, not an always-on tint.

## Examples
- **basic** (canonical): Default switch.
- **labeled** (canonical): Switch with a setting label.
- **sizes** (canonical): sm · md · lg.
- **tones** (canonical): The tone axis: neutral · brand · success · warning · danger.
- **content** (canonical): In-track glyphs via checkedContent / uncheckedContent.
- **loading** (canonical): Async pending state — spinner in the thumb.
- **field** (canonical): Switch in a Field — settings row + option card.
- **disabled** (edge-case)

---

# Table

> A styled, semantic data table — primitives plus smart parts for sorting, row selection, sticky/pinned columns, column resize, empty/loading states, and pagination.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Table } from "@garn/ui/table"`

## Overview
Table presents structured records in rows and columns where alignment and scanning down a column matter — invoices, users, metrics. garn keeps the markup honest (real `<table>`/`<thead>`/`<tbody>`/`<th>`/`<td>` via `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`) and layers the data-grid behaviors on as opt-in **smart parts** rather than a monolithic component you configure with a giant prop object.

Each capability is a part you add only when you need it: a sortable header (`TableHead` with `sortDirection` + `onSort`, which wires `aria-sort` and renders a `TableSortButton`), row selection (`TableSelectionCell` + `TableSelectAllCell`, composing Checkbox), frozen columns (`pin="start|end"`), keyboard-resizable columns (`onResizeEnd` + `layout="fixed"`), a sticky header, and the `TableEmpty` / `TableSkeletonRows` / `TablePagination` state parts. For a read-only set of field→value pairs about *one* entity, that's not a table — use DataList.

## When to use
Present structured data in rows and columns where alignment and comparison matter — invoices, users, metrics — with sorting, selection, sticky/pinned columns, and pagination via the smart parts.

## When not to use
Page layout (use CSS grid/flex, never a table); a simple one-dimensional list (use a list); a few key/value pairs (use a description list).

## Do / Don't
- ✅ Name the table with a TableCaption; use TableHead for column headers.
- ✅ Right-align numeric columns and keep units consistent.
- ✅ Own the sort comparator + page slicing yourself (or via a headless table lib) — the parts are controlled and own only the aria-sort / pagination UI.
- ✅ Use `useTableSelection({ rowIds })` for select-all + indeterminate, and feed its `{ count, clear }` straight into app-shell's AppShellSelectionBar.
- ✅ For wide tables, pin the selection column `start` and the actions column `end`, and set `stickyHeader` with `containerProps={{ className: 'max-h-*' }}`.
- ✅ To resize columns, set `Table layout="fixed"` and drive widths with `useColumnResize` (spread `column(id)` onto each TableHead) so a header's width governs its column and content truncates instead of fighting the drag.
- ❌ Don't use a table for visual layout.
- ❌ Don't omit column headers — screen readers rely on them to announce cells.
- ❌ Don't reimplement the sort/filter/page engine in garn — drive it yourself or with a headless lib; the parts stay controlled.

## Guidelines
**Give the table an accessible name.** Add a `TableCaption` (it can be visually quiet) so screen-reader users know what the grid contains. When you make a header sortable, drive it through `sortDirection`/`onSort` so `aria-sort` reflects the live state — don't fake the chevron with a plain icon.

**Add smart parts only as the data demands them.** A 10-row reference table needs none of pagination, sticky headers, or resizing; reaching for them by default adds weight and interaction cost. Pin columns sparingly — freezing an identifier column helps on wide tables, but pinning several defeats the horizontal scroll it's meant to tame.

**Always render the empty and loading states.** A table that collapses to a bare header when there's no data reads as broken; drop in `TableEmpty` (optionally nesting the rich `empty` component) and `TableSkeletonRows` while fetching, and set `aria-busy` on the region. Keep numeric columns right-aligned so digits line up for comparison.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `containerProps` | `React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>` | — | no | Props for the scrolling wrapper — set `className="max-h-*"` here so a `stickyHeader` has a bounded box to stick within. |
| `density` | `"compact" \| "spacious"` | — | no | Local density override; omit to inherit the ambient `[data-density]`. |
| `layout` | `"auto" \| "fixed"` | — | no | Column-sizing model. `"fixed"` makes a `TableHead`'s `width` govern its column (content truncates instead of widening it) — the substrate column resize needs. Omit for the default content-driven `"auto"` layout. |
| `stickyFooter` | `boolean` | — | no | Stick the footer to the bottom of the scroll container on vertical scroll — for a summary / totals `TableFooter` row that stays visible over a scrolling body. Needs a height-bounded `containerProps.className` to have room to stick, same as `stickyHeader`. |
| `stickyHeader` | `boolean` | — | no | Stick the header to the top of the scroll container on vertical scroll. |

_Plus 289 inherited native `<table>` attributes._

### `TableBody` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `onReorder` | `(order: string[]) => void` | — | no | Fires on drop with the next key order. Apply it to your data. |
| `order` | `string[]` | — | no | The body row keys in visual order — the array driving your row `.map`. Required when `reorderable`. |
| `reorderable` | `boolean` | — | no | Enable drag-to-reorder for the body rows. Each reorderable {@link TableRow} needs a `value`, and a {@link TableDragHandle} in a leading cell grabs it. Powered by garn's `sortable` primitive — pointer + keyboard + screen-reader announcements come free. The order is **controlled**: pass `order` and apply the next order in `onReorder` (garn reorders the keys, never your row data). |

_Plus 280 inherited native HTML attributes._

### `TableRow` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `string` | — | no | The row's stable key when the owning {@link TableBody} is `reorderable` — the same id you keyed the `.map` and `order` array by. Wires the row into the drag engine and lets a nested {@link TableDragHandle} grab it. Ignored otherwise. |

_Plus 280 inherited native HTML attributes._

### `TableHead` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `maxWidth` | `number` | — | no |  |
| `minWidth` | `number` | — | no | Resize bounds (px). `minWidth` defaults to 80 once resizable. |
| `onResize` | `(width: number) => void` | — | no | Live width during a drag (per-pixel). Usually omitted — the DOM updates imperatively, so let `onResizeEnd` commit the final value. |
| `onResizeEnd` | `(width: number) => void` | — | no | Committed width on pointer release, each keyboard step, and double-click auto-fit. Its presence makes the header resizable (renders a {@link TableColumnResizer} grip). |
| `onSort` | `() => void` | — | no | Fired when the sort control is activated (click / Enter / Space). |
| `pin` | `"end" \| "start"` | — | no | Pin this header cell to the start/end edge on horizontal scroll. |
| `resizeLabel` | `string` | — | no | Accessible name for the resize grip when the header label isn't plain text (defaults to the string children, else "column"). |
| `sortDirection` | `TableSortDirection` | — | no | When set, the header becomes sortable: it owns `aria-sort` + `data-sort` and wraps its label in a {@link TableSortButton}. The consumer owns the comparator/data and the tri-state cycle (ascending → descending → none); the header reflects the current direction and fires `onSort`. |
| `width` | `number` | — | no | Controlled column width (px). Needs `Table layout="fixed"` to govern the column; pair with `onResizeEnd` (or the `useColumnResize` hook) to resize. |

_Plus 286 inherited native HTML attributes._

### `TableCell` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `pin` | `"end" \| "start"` | — | no | Pin this cell to the start/end edge on horizontal scroll. |

_Plus 289 inherited native HTML attributes._

### `TableSortButton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `sortDirection` | `TableSortDirection` | — | no |  |

_Plus 290 inherited native HTML attributes._

### `TableColumnResizer` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean` | — | no |  |
| `max` | `number` | — | no |  |
| `min` | `number` | — | no | Resize bounds (px). |
| `onResize` | `(width: number) => void` | — | no | Live width while dragging. Also receives a committed keyboard-step / auto-fit width **when `onResizeEnd` is not wired**, so an `onResize`-only consumer still hears those (a pointer drag already streams the final width here). Wire `onResizeEnd` for a dedicated commit callback. |
| `onResizeEnd` | `(width: number) => void` | — | no | Committed width on release, each keyboard step, and double-click auto-fit. |
| `step` | `number` | — | no | Keyboard step (px); Shift / PageUp·PageDown use a larger step. |
| `value` | `number` | — | no | Current committed width (px) — drives `aria-valuenow`; measured from the host header if omitted. |

_Plus 280 inherited native HTML attributes._

### `TableSelectionCell` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `checked` | `boolean` | — | yes |  |
| `label` | `string` | — | no | Row label for a distinct accessible name — the checkbox is named "Select {label}" (e.g. the row's primary text), so screen-reader users don't hear N identical "Select row" controls. An explicit `aria-label` still wins; omitting both keeps the generic "Select row". Mirrors {@link TableExpandToggle}. |
| `onCheckedChange` | `(checked: boolean) => void` | — | no |  |
| `onRangeChange` | `(checked: boolean) => void` | — | no | Called instead of {@link onCheckedChange} when the checkbox is activated with **Shift held** — wire it to a range selector (e.g. `useTableSelection`'s `toggleRange(id)`) for Gmail/Finder contiguous selection. Works for both Shift+click and Shift+Space (keyboard-accessible range select); the plain toggle remains the modifier-free path. |

_Plus 289 inherited native HTML attributes._

### `TableSelectAllCell` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `checked` | `"indeterminate" \| boolean` | — | yes |  |
| `onCheckedChange` | `(checked: boolean) => void` | — | no |  |

_Plus 292 inherited native HTML attributes._

### `TableEmpty` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `colSpan` | `number` | — | yes | Number of columns to span — usually your column count. |

_Plus 288 inherited native HTML attributes._

### `TableSkeletonRows` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `cellClassName` | `string` | — | no | Class applied to each cell's Skeleton bar. |
| `columns` | `number` | — | yes | How many cells per row — match your column count. |
| `rows` | `number` | — | no | How many placeholder rows to render. |

_Plus 280 inherited native HTML attributes._

### `TablePagination` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean` | — | no |  |
| `onPageChange` | `(page: number) => void` | — | yes |  |
| `onPageSizeChange` | `(pageSize: number) => void` | — | no |  |
| `page` | `number` | — | yes | Current page, 1-based. |
| `pageCount` | `number` | — | yes | Total number of pages. |
| `pageSize` | `number` | — | no | Current rows-per-page; enables the rows-per-page Select with `pageSizeOptions`. |
| `pageSizeOptions` | `number[]` | — | no |  |
| `total` | `number` | — | no | Total row count — switches the indicator to "N–M of T". |

_Plus 279 inherited native HTML attributes._

## Anatomy
- `table-container`: The scrolling wrapper around the <table>. Carries `data-density` (local override), `data-sticky-header`, and the scroll-state hooks that drive the seam shadows; set its height via `containerProps` (e.g. max-h-*) so a sticky header has a bounded box.
- `table-resize-guide`: The full-column-height resize guideline, parked in the container (a pinned header's grip can't paint past the header). A resizable header writes its column's trailing edge to `--resize-x` and reveals the line on hover / focus / drag.

**Parts**
- `Table` (`table`) · required: The <table> (wrapped in a scrolling container). Props: `density` (local override), `stickyHeader`, `layout` ("fixed" so a header's `width` governs its column — the resize substrate), `containerProps`.
- `TableHeader` (`table-header`): The <thead> column-header group.
- `TableBody` (`table-body`) · required: The <tbody> data rows.
- `TableFooter` (`table-footer`): The <tfoot> summary row (muted, medium weight).
- `TableRow` (`table-row`): A <tr>; hover highlight + data-state="selected" styling.
- `TableHead` (`table-head`): A column header cell (<th>). `sortDirection` + `onSort` make it a sortable header (auto aria-sort + a sort button); `pin="start|end"` freezes it on horizontal scroll; `width`/`minWidth`/`maxWidth` + `onResize`/`onResizeEnd` make it resizable (renders a TableColumnResizer grip — needs `Table layout="fixed"`). A header can be both sortable and resizable.
- `TableCell` (`table-cell`): A data cell (<td>). `pin="start|end"` freezes the column on horizontal scroll.
- `TableCaption` (`table-caption`): The table's accessible name/summary (<caption>).
- `TableSortButton` (`table-sort-button`): The in-cell sort control — a ghost Button with a direction-aware chevron. TableHead renders it for you from `sortDirection`; exported for bespoke headers. `aria-sort` on the <th> carries the state.
- `TableColumnResizer` (`table-column-resizer`): The column-resize grip — a focusable role="slider" on the header's trailing edge. Drag (imperative CSS-var, no per-pixel re-render), Arrow/Home/End/Shift/Page to resize via keyboard, double-click to auto-fit to content; commits via `onResizeEnd`. TableHead renders it for you from `onResizeEnd`; exported for bespoke headers.
- `TableSelectionCell` (`table-selection-cell`): A per-row checkbox cell (composes Checkbox). Controlled `checked`/`onCheckedChange`; needs an accessible `aria-label`. Pair with `data-state="selected"` on the row.
- `TableSelectAllCell` (`table-select-all`): The header select-all checkbox (a TableHead + Checkbox). Pass `checked="indeterminate"` for the some-but-not-all state (renders a dash; aria-checked="mixed").
- `TableEmpty` (`table-empty`): A full-width empty-state row (`<tr><td colSpan>`). Drop in a message, or nest the `empty` component for the rich icon/title version.
- `TableSkeletonRows` (`table-skeleton-row`): Loading placeholder rows (compose Skeleton). `rows` × `columns`; aria-hidden so screen readers skip them — set `aria-busy` on the region.
- `TablePagination` (`table-pagination`): The data-table footer — composes `pagination` (the nav landmark) + an optional rows-per-page `select` + an "N–M of T" indicator. Controlled `page`/`pageCount`/`onPageChange`.

## Accessibility
- **Role:** table
- **Enter:** Activate a sortable column header (cycle the sort direction).
- **Space:** Activate a sortable header; toggle a row checkbox or the select-all checkbox.
- **ArrowLeft / ArrowRight:** On a focused column resizer, shrink / grow the column by one step (hold Shift, or use PageUp/PageDown, for a larger step).
- **Home / End:** On a focused column resizer, jump the column to its minimum / maximum width.
- **WCAG:** 1.3.1 Info and Relationships (A); 1.4.10 Reflow (AA); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- Built on real <table>/<thead>/<th>/<tbody>/<td> — the semantics come from the elements; keep them intact (role=table, not grid).
- Name the table with a TableCaption (or aria-label/aria-labelledby).
- Use TableHead (<th>) for column headers; add `scope="row"` to a row's leading <th> when rows have headers.
- Sortable headers set `aria-sort` (ascending | descending | none) on the <th> and render a native <button>; only one column carries a non-none aria-sort — ARIA has no multi-column sort.
- Give each TableSelectionCell checkbox an accessible name (`aria-label`, e.g. "Select <row>"); the select-all goes `aria-checked="mixed"` when partially selected.
- TableSkeletonRows are aria-hidden — set `aria-busy` on the table/region while loading so the state is announced, not read as data.
- Sticky header and pinned columns are presentational; horizontal scroll (Reflow) is preserved, never trapped.
- A resizable TableHead renders a role="slider" resize grip (aria-valuemin/now/max = min/current/max width; ArrowLeft/Right resize, Home/End jump to the bounds, double-click auto-fits to content). The header pins its own accessible name so the slider's value doesn't bleed into the column-header name — pass `resizeLabel` (or `aria-label`) for a non-text header.
- **Focus:** Sortable-header buttons and selection checkboxes keep their focus-visible rings.

## Tokens
- `cellHeight` → `--garn-control-h-md` (air)
- `pinnedSurface` → `--garn-background`
- `seam` → `--garn-border`
- `seamShadowStart` → `--garn-shadow-pin-start`
- `seamShadowEnd` → `--garn-shadow-pin-end`
- `seamShadowHeader` → `--garn-shadow-pin-bottom`
- `resizeGuide` → `--garn-brand-solid`

## Related
- **composes** → `utils`
- **composes** → `button` (when TableSortButton + TablePagination prev/next)
- **composes** → `checkbox` (when TableSelectionCell / TableSelectAllCell)
- **composes** → `skeleton` (when TableSkeletonRows)
- **composes** → `pagination` (when TablePagination)
- **composes** → `select` (when TablePagination rows-per-page)
- **pairsWith** → `empty` (when nested in TableEmpty for the rich empty state)
- **pairsWith** → `badge` (when as a status cell)
- **pairsWith** → `dropdown-menu` (when for per-row actions (a kebab menu))
- **pairsWith** → `app-shell` (when feed useTableSelection into AppShellSelectionBar for bulk actions)

## Recipes
- **data-table** — A sortable, selectable, paged data table with bulk actions. _(use when showing a large, interactive dataset)_
- **sticky-pinned** — A wide + tall table with a sticky header and pinned identity/actions columns. _(use when a table is wider and taller than its viewport)_
- **column-visibility** — A dropdown-menu of checkbox items toggling which columns render — the consumer conditionally renders the matching TableHead/TableCell (garn owns no `columns` config). _(use when a wide table needs user-toggleable columns)_

## Gotchas
- **Screen readers announce cells with no column context.** — Column headers weren't marked up as TableHead (<th>). → Put column headers in a TableHeader → TableRow → TableHead, and caption the table.
- **Reaching for a table to lay out a page/cards.** — Tables are for tabular data, not layout. → Use CSS grid/flex for layout; reserve Table for rows × columns of data.
- **Sorting more than one column at once, or aria-sort on several headers.** — ARIA has no multi-column sort; only one column may carry a non-none aria-sort. → Reflect ascending/descending on the active column only; others stay sortDirection="none".
- **The sticky header doesn't stick.** — `stickyHeader` needs a bounded scroll box, and the Table owns the scroll wrapper. → Pass `containerProps={{ className: 'max-h-96' }}` (or similar) so the wrapper can scroll.
- **The bulk-action bar never appears on selection.** — Selection state wasn't lifted into the bar. → Drive selection with `useTableSelection` and render `<AppShellSelectionBar count={sel.count} onClear={sel.clear}>` when count > 0.
- **Dragging the resize grip does nothing, or the column snaps back.** — A header's width only governs its column under fixed table-layout, and the width must be controlled. → Set `Table layout="fixed"` and commit width via `onResizeEnd` (or `useColumnResize`); auto layout lets cell content fight the drag.
- **A resizable column header is announced with a trailing number (e.g. "Name 200").** — The resize grip is a role="slider" child, so its value leaks into the header's name-from-content. → A resizable TableHead auto-pins its aria-label to a string label; for a non-text header, pass `resizeLabel` (or `aria-label`).

## Examples
- **basic** (canonical): An invoices table with a caption, header, and right-aligned amounts.
- **sortable** (playground): Tri-state sortable headers (aria-sort); the consumer owns the comparator + cycle.
- **selection** (playground): Row selection (select-all / indeterminate) feeding AppShellSelectionBar.
- **empty** (edge-case): A full-width empty state nesting the Empty component.
- **loading** (edge-case): Skeleton-row loading state (aria-busy).
- **pagination** (playground): TablePagination with rows-per-page + an N–M of T indicator.
- **data-table** (canonical): The full composition: sortable headers + row selection (→ selection bar) + pagination.
- **sticky-pinned** (playground): Sticky header + pinned select/Name/actions columns with scroll-aware seam shadows.
- **density** (playground): A local compact-density override.
- **resizable** (playground): Drag / keyboard column resize (TableColumnResizer + useColumnResize) under layout="fixed", with double-click auto-fit; a header that's both sortable and resizable.
- **visibility** (playground): The column-visibility recipe — a dropdown-menu of checkbox items toggling which JSX columns render (keeps ≥1 column on).

## Source map

Regions in `table.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–35 (34 lines) — React, icons, shared hooks, sibling components
- `utils` L36–97 (62 lines) — pin classes, resize constants, width clamp
- `reorder-context` L98–116 (19 lines) — drag-reorder contexts (the drag handle lives in the reorder region)
- `root` L117–249 (133 lines) — Table scroll container + sticky/pin engine
- `parts` L250–561 (312 lines) — header/body/footer/row/head/cell/caption structural subcomponents
- `sort` L562–607 (46 lines) — in-cell sort button
- `resize` L608–914 (307 lines) — column-resize grip (slider)
- `state-hooks` L915–948 (34 lines) — batched-update helper for the liftable state hooks
- `use-column-resize` L949–1018 (70 lines) — liftable column-width state hook
- `use-table-selection` L1019–1142 (124 lines) — liftable selection state hook
- `selection-cells` L1143–1234 (92 lines) — per-row + select-all checkbox cells
- `use-table-expansion` L1235–1335 (101 lines) — liftable expandable-row state hook
- `expansion-parts` L1336–1540 (205 lines) — expand toggle, expand-all header cell, detail row
- `reorder` L1541–1601 (61 lines) — the row drag handle (contexts live in the reorder-context region)
- `empty` L1602–1626 (25 lines) — full-width empty-state row
- `skeleton` L1627–1669 (43 lines) — loading placeholder rows
- `pagination` L1670–1780 (111 lines) — data-table footer (paging + rows-per-page)
- `exports` L1781–1806 (26 lines) — public surface

---

# Tabs

> Switch between a few peer views in place, showing one panel at a time.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** navigation
- **Import:** `import { Tabs } from "@garn/ui/tabs"`

## Overview
Tabs switch between a few peer views in the same context, one panel at a time — settings sections, overview/detail, related lists. `Tabs` owns the active `value` and `orientation`, `TabsList` holds the `TabsTrigger`s (roving focus), and each `TabsContent` panel shows when its value is active. Use tabs when the views are siblings the user toggles between; for sequential, gated steps use a Stepper, and for primary site navigation use NavigationMenu.

## When to use
Switch between a few peer views in the same context, one panel at a time — settings sections, overview/detail, related lists.

## When not to use
Sequential steps that must be done in order (use a stepper); navigating to separate routes/pages (use links / a nav menu); content that should all be visible at once; many (~7+) sections or long content (use a side nav or accordion).

## Do / Don't
- ✅ Give each TabsTrigger a `value` and a matching TabsContent.
- ✅ Keep labels short so the tablist fits on one line.
- ✅ Set `defaultValue` (uncontrolled) or `value` + `onValueChange` (controlled).
- ❌ Don't use tabs for a linear, ordered flow.
- ❌ Don't bury content the user always needs behind a non-default tab.
- ❌ Don't overload the tablist — switch to a nav menu or accordion when there are many sections.

## Guidelines
**Tabs are for peer views, not steps or pages.** They imply equal, independent sections in one place — don't use them for an ordered flow (that's a Stepper) or to navigate to separate URLs (that's navigation). Keep the set small enough to see at once; many tabs that wrap or scroll signal the content wants a different structure.

**Use short, parallel labels and a sensible default.** One or two words each, in the same grammatical form, with the most important panel active first. Don't bury a required action inside a non-default tab where users may never look.

**Respect the keyboard model.** Arrow keys move between triggers and the active panel is wired via `aria-controls`; don't put the only path to critical content behind a tab a keyboard user might skip. Avoid tabs within tabs.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `mount` | `TabsMountMode` | — | no | Panel mounting. `active` (default) mounts a panel's children on first activation; `eager` renders every panel up front (today's behavior — SEO / measure-on-mount). Per-panel `keepMounted` persists an activated panel. |
| `size` | `TabsSize` | — | no |  |
| `variant` | `TabsVariant` | — | no | Visual language: `underline` (default), `pill` (segmented), `enclosed` (card). |

_Plus 285 inherited native HTML attributes._

### `TabsList` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `indicator` | `boolean` | — | no | Render an animated active indicator (default true). Set false to opt out. |
| `scrollButtons` | `boolean` | — | no | Show prev/next scroll buttons flanking the list when it overflows (the pointer affordance — keyboard + trackpad scroll already work). The buttons sit *outside* the tablist so the ARIA structure stays clean; they fade out at the reached end. Compose `TabsScrollButton` by hand for bespoke layouts. |

_Plus 282 inherited native HTML attributes._

### `TabsTrigger` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `badge` | `React.ReactNode` | — | no | Trailing badge. A number renders a garn `Counter` matched to the tab's size (e.g. an unread count); a node renders verbatim. |
| `icon` | `React.ReactNode` | — | no | Leading icon (terse path). Compose children for full control. |

_Plus 291 inherited native HTML attributes._

### `TabsContent` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `keepMounted` | `boolean` | — | no | Keep this panel mounted (hidden) once it has been activated, so its form / scroll state survives a tab switch. Overrides the root's `mount="active"` lazy unmount for this panel only. |

_Plus 283 inherited native HTML attributes._

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string — The active tab's value. Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`.
- Selection: single.

## Anatomy

**Parts**
- `Tabs` (`tabs`) · required: State container (Radix Root) — owns the active `value` and `orientation`. No visual box of its own.
- `TabsList` (`tabs-list`) · required: The tablist: a muted pill that holds the triggers (roving focus).
- `TabsTrigger` (`tabs-trigger`) · required: A tab button; its `value` selects the matching content. Active tab gets a raised background.
- `TabsContent` (`tabs-content`) · required: A panel; its `value` matches a trigger. Only the active panel is shown.

## Accessibility
- **Role:** tablist (APG: tabs)
- **ArrowLeft / ArrowRight:** Move between tabs (horizontal orientation).
- **ArrowUp / ArrowDown:** Move between tabs (vertical orientation).
- **Home / End:** Jump to the first / last tab.
- **Tab:** Move focus from the tablist into the active panel.
- **Enter / Space:** Activate the focused tab (manual activation mode).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The list is role=tablist with roving tabindex; each trigger is role=tab with aria-selected.
- Each trigger aria-controls its panel; each panel is role=tabpanel, aria-labelledby its trigger.
- Default activation is automatic (focus selects). Use `activationMode="manual"` to require Enter/Space.
- **Focus:** Triggers and the active panel show a 2px ring; focus moves list → panel on Tab.

## Tokens
- `listHeight` → `--garn-control-h-md` (air)
- `ring` → `--garn-ring` · brandable

## Related
- **composes** → `utils`
- **alternativeTo** → `accordion` (when there are many sections, or stacking reads better on small screens)
- **alternativeTo** → `navigation-menu` (when the destinations are separate routes/pages, not in-place panels)

## Recipes
- **section-tabs** — A few peer sections switched in place. _(use when switching between a few peer views in the same context)_

## Gotchas
- **A tab shows nothing (or the wrong panel) when clicked.** — A TabsTrigger `value` doesn't match any TabsContent `value`. → Pair every trigger with a content panel sharing the same `value`.
- **Tabs switch on arrow-key focus before the user commits.** — Default activation is automatic. → Pass `activationMode="manual"` to require Enter/Space to activate.

## Examples
- **basic** (canonical): Two-tab Account / Password switcher.

---

# Tag

> Removable and selectable chips — dismissable filter tokens and pick-to-toggle option chips, with TagGroup coordinating roving-keyboard selection and removal across a set.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Tag } from "@garn/ui/tag"`
- **Polymorphism:** `asChild` (default element `<span>`)

## Overview
Tag is the interactive chip — a keyword, label, or filter the user can remove or select, often in a `TagGroup`. It shares the chip family's `tone` × `appearance` × `size` vocabulary with Badge, but where Badge is a read-only marker, Tag carries affordances: a remove control, selected state, focus. Use it for editable label sets and filter chips; for a status you only display, use Badge, and for a single value the user picks from a menu, use BadgeSelect.

## When to use
Removable + selectable chips: dismissable filter tokens (applied filters, recipients, keywords) and pick-to-toggle option chips. Use a standalone <Tag onRemove> for a lone token, or a <TagGroup> to coordinate selection (selectionMode) and removal with roving-keyboard a11y across a set.

## When not to use
A static, non-interactive label or status (use Badge); a numeric count (use Counter); a single pick-to-change value (use BadgeSelect); a few mutually-exclusive choices in a form (use RadioGroup); a long single-select list (use Select).

## Do / Don't
- ✅ Give every TagGroup an accessible name (label / aria-label).
- ✅ Set a stable `value` on each Tag in a selectable or removable group — selection and removal key off it.
- ✅ Let onRemove be the source of the remove affordance (don't hand-place a remove button); pass onRemove on the group for per-chip removal, or on a standalone Tag.
- ✅ Use tone for intent and share it across the badge family (Badge / Counter / Tag) so a status reads the same everywhere.
- ✅ Use asChild to make a chip a link (a tag that filters/navigates).
- ❌ Don't use a Tag for a static label that can't be removed or selected — that's Badge.
- ❌ Don't nest your own interactive element inside a clickable standalone Tag (use a TagGroup, whose role=row hosts the remove button safely).
- ❌ Don't strip the focus ring or override the roving tabindex — they are the keyboard contract.
- ❌ Don't reach for raw colors; tone resolves through the --garn-badge-* tokens (edit dark mode in the token layer).

## Guidelines
**Use Tag when the chip is actionable.** If users add, remove, or toggle it, it's a Tag — not a Badge. Make the remove control a real, labelled button ("Remove <name>") so it's reachable by keyboard and announced.

**Group related tags and keep labels tight.** A `TagGroup` communicates that the chips belong to one set (the filters on a list, the labels on an item); keep each label to a word or two so a row of them stays scannable.

**Keep tone meaningful and removal forgiving.** Reuse the chip tones consistently, and don't lean on color alone. When removing a tag has consequences, make it easy to undo rather than gating each removal behind a confirm.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"framed" \| "outline" \| "soft" \| "solid"` | `soft` | no |  |
| `shape` | `"pill" \| "rounded" \| "sharp"` | `rounded` | no |  |
| `size` | `"md" \| "sm"` | `md` | no |  |
| `tone` | `"brand" \| "danger" \| "discovery" \| "info" \| "neutral" \| "success" \| "warning"` | `neutral` | no |  |
| `asChild` | `boolean` | — | no | Render as the child element (a link/button chip), merging props. |
| `count` | `number` | — | no | A trailing count, rendered as a Counter matched to the chip's tone/size (its appearance inverts for contrast). |
| `disabled` | `boolean` | — | no |  |
| `leading` | `React.ReactNode` | — | no | Leading content — icon, avatar, or dot. |
| `maxWidth` | `number \| string` | — | no |  |
| `onRemove` | `(value?: string) => void` | — | no | Standalone removal handler (in a group, the group's `onRemove` is used). |
| `removeLabel` | `string` | — | no | Accessible label for the remove button. Default: `Remove {label}`. |
| `trailing` | `React.ReactNode` | — | no | Trailing content — rendered after the label, before any remove button. |
| `truncate` | `boolean` | — | no | Truncate a long label with an ellipsis + native tooltip. |
| `value` | `string` | — | no | Stable key for selection/removal. Required inside a selectable/removable group. |

_Plus 278 inherited native `<span>` attributes._

### `TagGroup` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `TagAppearance` | — | no |  |
| `defaultSelectedKeys` | `string[]` | — | no | Uncontrolled initial selection. |
| `disabledKeys` | `string[]` | — | no | Disable these chips by `value` (in addition to a chip's own `disabled`). |
| `disallowEmptySelection` | `boolean` | — | no | Keep at least one chip selected (single mode can't toggle the last off). |
| `empty` | `React.ReactNode` | — | no | Rendered when the group has no chips (e.g. all removed). |
| `label` | `React.ReactNode` | — | no | Convenience group label (auto-wired as the group's accessible name). |
| `onRemove` | `(value: string) => void` | — | no | Enable removal: called with the removed chip's `value`. |
| `onSelectionChange` | `(keys: string[]) => void` | — | no |  |
| `selectedKeys` | `string[]` | — | no | Controlled selection (chip `value`s). |
| `selectionMode` | `TagSelectionMode` | — | no | "none" (default), "single", or "multiple". |
| `shape` | `TagShape` | — | no |  |
| `size` | `TagSize` | — | no |  |
| `tone` | `TagTone` | — | no | Ambient defaults inherited by child Tags (each Tag may override). |

_Plus 279 inherited native HTML attributes._

## Variants
- **tone** (default `neutral`): `neutral`, `brand`, `info`, `success`, `warning`, `danger`, `discovery`
- **appearance** (default `soft`): `solid`, `soft`, `outline`, `framed`
- **size** (default `md`): `sm`, `md`
- **shape** (default `rounded`): `sharp`, `rounded`, `pill`

## Anatomy
- `tag`: The chip. Standalone it is a <span> (or a <button> when clickable, or the asChild element); inside a TagGroup it is a role=row grid cell host.
- `tag-leading`: Fixed-width leading slot — an icon, avatar, or dot. Replaced by a check when the chip is selected.
- `tag-label`: The chip text — the only part that truncates.
- `tag-trailing`: Trailing content before the remove button — a `count` Counter (tone/size matched to the chip, contrast-inverted appearance) and/or a custom `trailing` node.
- `tag-remove`: The remove affordance — a real focusable <button> (aria-label 'Remove {label}'). Auto-rendered when removal is available.

**Parts**
- `TagGroup` (`tag-group`): The labelled, roving-tabindex grid that coordinates a set of Tags. Props: selectionMode ('none' | 'single' | 'multiple'), selectedKeys / defaultSelectedKeys / onSelectionChange, disabledKeys, disallowEmptySelection, onRemove (enables removal), label (auto-wired accessible name), empty (empty-state slot), and ambient tone/appearance/shape/size defaults each Tag may override. Selection and removal key off each Tag's `value`.

## Accessibility
- **Role:** grid
- **WCAG:** 1.4.1 Use of Color (A); 1.4.3 Contrast (Minimum) (AA); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- A standalone Tag has no implicit role (a <span>), becomes a <button> when clickable, or the asChild element (e.g. an <a>); keep a readable text label and don't encode meaning by color alone.
- A TagGroup is a role=grid with one roving tab stop; each Tag is a role=row (aria-selected in single/multiple mode) wrapping role=gridcell content and a gridcell remove button — the grid pattern is what lets a chip carry a focusable remove button without a nested-interactive violation.
- Keyboard: arrows + Home/End rove between chips (logical, so they mirror under RTL); Enter/Space toggle selection; Backspace/Delete remove the focused chip and move focus to its neighbour (or the previous chip if it was last, or the group if none remain).
- Every remove button is named from its chip ('Remove {label}', overridable via removeLabel). The group is multiselectable only in 'multiple' mode (aria-multiselectable).
- Give the TagGroup an accessible name via `label` (auto-wired as aria-labelledby), `aria-label`, or `aria-labelledby` — a group of chips without a name is anonymous to assistive tech.
- **Focus:** 2px ring in --garn-ring on the chip (the roving row) and the remove button; roving tabindex keeps a TagGroup a single tab stop.
- **Contract (warn):** Give the TagGroup an accessible name (a `label`, or aria-label / aria-labelledby). — _when a TagGroup has no `label`, `aria-label`, or `aria-labelledby`_

## Tokens
- `fill` → `--garn-badge-brand-bg` · brandable
- **Internal (never externalize):** `--t-soft-bg`

## Related
- **composes** → `utils`
- **slotAccepts** → `avatar` (when a Tag.Leading can be an avatar (a person / recipient chip))
- **pairsWith** → `popover` (when removable filter tokens sit beside a Popover+Command faceted filter picker)
- **pairsWith** → `input` (when Tags render the chips inside a token / pills text input)
- **pairsWith** → `empty` (when the TagGroup `empty` slot shows an Empty when all chips are removed)
- **alternativeTo** → `badge` (when the chip is a static, non-interactive label (not removable or selectable))
- **alternativeTo** → `counter` (when the value is a numeric count, not a label)
- **alternativeTo** → `toggle-group` (when the options are a fixed segmented control rather than a dynamic, removable set)

## Gotchas
- **Selecting or removing a chip in a TagGroup does nothing.** — The Tag has no `value` — selection and removal key off it. → Give each Tag a stable `value`; selectedKeys / onSelectionChange / onRemove / disabledKeys all reference it.
- **No remove button appears on the chips.** — Removal is gated by an onRemove handler, not a boolean. → Pass onRemove on the TagGroup (per-chip removal) or on a standalone Tag; the remove button is then auto-rendered.
- **A clickable standalone Tag with its own remove button triggers a nested-interactive a11y error.** — A standalone clickable chip is a <button>; a second button inside it nests interactives. → Use a TagGroup — its chips are role=row (non-interactive), which can host a focusable remove button safely.
- **A dev console warns that the TagGroup has no accessible name.** — The group has no `label`, `aria-label`, or `aria-labelledby`. → Pass `label` (auto-wired as the group's name) or an aria-label.
- **Editing dark-mode chip colors in the component has no effect.** — Tones resolve through the --garn-badge-* component tokens; dark values live in the token layer. → Adjust dark mode in the garn theme CSS (.dark block) — never with raw ramps in tag.tsx.

## Examples
- **basic** (canonical): Plain chips — neutral, brand, and a leading-icon chip.
- **removable** (edge-case): Standalone dismissable filter tokens (onRemove).
- **tones** (edge-case): The full palette — neutral · brand · info · success · warning · danger · discovery.
- **appearances** (edge-case): solid · soft · outline · framed.
- **count** (edge-case): A trailing count (a composed Counter) and a custom trailing slot.
- **shapes** (edge-case): sharp · rounded · pill.
- **sizes** (edge-case): sm · md.
- **single-select** (edge-case): A single-select TagGroup (disallowEmptySelection) — selected reads as a check + fill.
- **multi-select** (edge-case): A multi-select TagGroup — toggle several chips.
- **removable-group** (edge-case): Applied-filters: a TagGroup with onRemove and an empty state.
- **selectable-removable** (edge-case): Selectable AND removable chips in one group — both affordances on one TagGroup.
- **disabled** (edge-case): disabledKeys — a chip that can't be selected and is skipped by roving.
- **truncate** (edge-case): A long label truncated with maxWidth + a native tooltip.
- **link** (edge-case): asChild — a chip that is a link (a tag that navigates).

---

# Textarea

> A multi-line text field for longer freeform input.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Textarea } from "@garn/ui/textarea"`

## Overview
Textarea collects multi-line freeform text — a comment, a description, a message. It renders the same field surface as Input (`appearance` × `size`), so it sits on the shared grid and reddens on `aria-invalid` like every other control; its minimum height is derived as two control rows so it reads as multi-line at rest. For a single line, use Input; for a fixed-length code, InputOTP; for a choice, Select.

## When to use
Collect multi-line freeform text — comments, descriptions, messages, notes.

## When not to use
A single line (use input); choosing among fixed options (use select or radio-group).

## Do / Don't
- ✅ Pair with a label; allow vertical resize unless the layout requires a fixed height.
- ✅ Set a sensible number of rows / min-height for the expected content.
- ❌ Don't use a textarea for one-line values.
- ❌ Don't disable resizing without a layout reason.

## Guidelines
**Always pair a Textarea with a Label, and size it to the expected input.** Start tall enough to signal that a few sentences are welcome; a single-row box invites single-word answers. Use the placeholder for an example, never as the field's name.

**Show limits before they're hit, not after.** When there's a max length, surface a live character count and warn as it approaches the cap — don't silently truncate on submit. Wire validation through `aria-invalid` + a described error message so the state is announced.

**Let users grow the field.** Allow vertical resize (or auto-grow) for longer entries rather than trapping a long message in a small scroll box. Don't disable the browser's resize handle without giving an equivalent way to see more.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `autoResize` | `boolean` | — | no | Grow to fit content instead of scrolling — re-measured on input and on width changes (wrapping shifts height). The `size` min-height stays the floor; set a `max-height` class to cap it (it starts scrolling past the cap). |

_Plus 294 inherited native `<textarea>` attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onChange` · string — Controlled via `value` + `onChange`; uncontrolled via `defaultValue`.
- Selection: single.

## Anatomy
- `textarea`: The native <textarea> element.

## Accessibility
- **Role:** textbox
- **WCAG:** 1.3.1 Info and Relationships (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- Associate a visible <label> (htmlFor) or provide aria-label / aria-labelledby.
- **Focus:** Border darkens (foreground/40) on any focus; keyboard focus adds a 2px neutral ring (foreground/15).
- **Contract (warn):** Give every textarea an accessible label (a <label htmlFor>, or aria-label/aria-labelledby). — _when no associated <label htmlFor>, aria-label, or aria-labelledby_

## Tokens
- `minHeight` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)
- `borderColor` → `--garn-foreground`

## Related
- **composes** → `utils`
- **composes** → `field-variants`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `input` (when the value is a single line)

## Recipes
- **labeled-textarea** — A labeled multi-line field. _(use when collecting multi-line text in a form)_

## Gotchas
- **Typing does nothing / React warns about a controlled component.** — Passing `value` without `onChange`. → Use `defaultValue` for uncontrolled, or pass both `value` and `onChange`.

## Examples
- **basic** (canonical): Default textarea.
- **labeled** (canonical): Textarea with a label.
- **appearances** (playground): outline · soft · ghost (shared field surface).
- **sizes** (playground): xs · sm · md · lg · xl.
- **disabled** (edge-case)

---

# TimeField

> A typed time input — format-driven, with Arrow-key stepping and a native Date value.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { TimeField } from "@garn/ui/time-field"`

## Overview
TimeField is the typed time control — the time-side twin of DatePicker's field. It reuses **Input** wholesale (the clock leading glyph, clear button, `appearance` × `size`, the wrapped focus surface, and the invalid treatment), adding only the time logic: a `format` prop (date-fns tokens like `HH:mm` or `h:mm a`) that drives display, parse, and the placeholder, and **Arrow-key stepping** (↑/↓ by `step` minutes, PageUp/Down by the hour). The committed value is a native `Date` — the time portion is what matters, the date portion is preserved — so a TimeField drops straight into DateTimePicker.

Reach for **TimePicker** instead when users should pick from a list of slots (booking), and **DateTimePicker** when a date and time are entered together.

## When to use
Enter a time of day by typing, with Arrow-key nudging — in a form where a slot list would be overkill.

## When not to use
Picking from fixed slots (use TimePicker); a date + time together (use DateTimePicker); a duration (use a number field with a unit).

## Do / Don't
- ✅ Pair with a label and choose a 24h/12h `format`.
- ✅ Hold the value in state (or use `defaultValue`); read it as a `Date`.
- ✅ Set `step` to the granularity you want Arrow keys to nudge.
- ❌ Don't rely on the placeholder as the label.
- ❌ Don't hand-set height/padding — the size variant owns the grid.

## Guidelines
**Pair with a Label and pick a `format` that matches expectations** (24-hour `HH:mm` vs 12-hour `h:mm a`); it drives typing and display together. **Let the field surface own sizing** — choose a `size` rung rather than hand-padding. **Reflect validity with aria-invalid** + a described message. Arrow keys step the value, so keyboard users never need the mouse.

**Wire format: `HH:mm:ss`.** With `name`, a hidden input posts the canonical time of day (the `<input type="time" step="1">` wire format) — never the formatted display text (`"9:30 AM"`) and never a UTC-shifted instant. The visible field carries no `name`, so nothing double-submits.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `defaultValue` | `Date` | — | no |  |
| `format` | `string` | — | no | date-fns token string driving display, parse, and the placeholder. |
| `hourStep` | `number` | — | no | Minutes added/removed per PageUp/PageDown. Default 60. |
| `leading` | `React.ReactNode` | — | no | Override the default leading clock glyph. |
| `onValueChange` | `(value: Date \| undefined) => void` | — | no |  |
| `step` | `number` | — | no | Minutes added/removed per ArrowUp/ArrowDown. Default 1. |
| `value` | `Date` | — | no | Selected time as a `Date` (time portion meaningful; date portion preserved). |

_Plus 316 inherited native `<input>` attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · Date — The time as a native `Date` (time portion meaningful; date preserved). Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`.
- Selection: single.

## Anatomy
- `input-root`: Reuses Input's wrapped field surface (border, focus-within ring, invalid/disabled). Styled by `className`.
- `input`: The <input> — the type target; ref + typed value land here.
- `input-leading`: The leading clock glyph (override via `leading`).
- `input-clear`: Input's clear button (clearable) — clears the value.

## Accessibility
- **Role:** textbox
- **ArrowUp / ArrowDown:** Step the time by `step` minutes (default 1).
- **PageUp / PageDown:** Step the time by `hourStep` minutes (default 60).
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- Give the field an accessible label — <label htmlFor>, aria-label, or aria-labelledby; the format-pattern placeholder is not a label.
- The expected format is announced via a visually-hidden aria-describedby hint.
- Reflect validation with aria-invalid + a described error message.
- **Focus:** Inherits Input's focus surface (border darkens on focus; keyboard focus adds a neutral ring).
- **Contract (warn):** Give every time field an accessible label. — _when no associated <label htmlFor>, aria-label, or aria-labelledby_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)

## Related
- **composes** → `utils`
- **composes** → `input`
- **composes** → `use-controllable-state`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **pairsWith** → `date-picker` (when a date and time are collected side by side)
- **alternativeTo** → `time-picker` (when users should pick from a list of time slots)

## Gotchas
- **The value is a Date with today's date, not just a time.** — TimeField stores a native `Date`; when empty it steps/parses onto today. → Read only the time from the value, or pass a `value` whose date you control.
- **Typed time snaps back.** — The text didn't match `format`, so it reverted on blur. → Type in the exact `format` (shown as the placeholder).

## Examples
- **basic** (canonical): A default 24-hour time field.
- **twelve-hour** (canonical): A 12-hour format (h:mm a).
- **step** (edge-case): Arrow keys step by 15 minutes.
- **states** (edge-case): Disabled and invalid.
- **sizes** (playground): xs · sm · md · lg · xl.

---

# TimePicker

> A time field with a scrollable list of selectable time slots — the booking-UI pattern.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** form-control
- **Import:** `import { TimePicker } from "@garn/ui/time-picker"`

## Overview
TimePicker is TimeField's pick-from-a-list sibling — the booking-UI pattern. It's the same typeable field, plus a Popover holding a scrollable **listbox of time slots** at your chosen `interval` (default 30 min). It reuses the date family's field + popover shell (with a clock trigger), so it lines up with DatePicker and the rest of the form surface. The value is a native `Date`; picking a slot preserves the value's date, and typing stays available alongside the list.

Use **TimeField** when a bare typed time is enough (no slots), and **DateTimePicker** for a date and time together.

## When to use
Pick a time from fixed slots (appointment, reservation) while still allowing free typing.

## When not to use
A bare typed time (use TimeField); a date + time (use DateTimePicker); an arbitrary-precision duration.

## Do / Don't
- ✅ Set `interval` to the slot granularity; pair with a label.
- ✅ Hold the value in state; read it as a `Date`.
- ✅ Reflect validation with aria-invalid + a described message.
- ❌ Don't rely on the placeholder as the label.
- ❌ Don't use huge slot lists at 1-minute intervals — prefer TimeField for fine typing.

## Guidelines
**Choose an `interval` that matches the booking granularity** (15/30 min). **Pair with a Label** and pick a 24h/12h `format`. The typed field is fully keyboard-operable (ArrowDown opens, Enter commits, Escape closes); the slot list is keyboard-operable too (arrows/Home/End/Page roving focus, Enter/Space commits), with the current time marked and scrolled into view on open. **Reflect validity** with aria-invalid.

**Wire format: `HH:mm:ss`.** With `name`, the hidden form input posts the canonical time of day (the `<input type="time" step="1">` wire format) — a time-only field never posts an invented-date UTC instant.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | `outline` | no |  |
| `size` | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | `md` | no |  |
| `"aria-invalid"` | `"false" \| "true" \| boolean` | — | no |  |
| `"aria-label"` | `string` | — | no |  |
| `"aria-labelledby"` | `string` | — | no |  |
| `className` | `string` | — | no |  |
| `clearable` | `boolean` | — | no |  |
| `clearLabel` | `string` | — | no |  |
| `contentClassName` | `string` | — | no |  |
| `defaultOpen` | `boolean` | — | no |  |
| `defaultValue` | `Date` | — | no |  |
| `disabled` | `boolean` | — | no |  |
| `format` | `string` | — | no | date-fns token string driving display, parse, and the placeholder. |
| `id` | `string` | — | no |  |
| `interval` | `number` | — | no | Minutes between slots in the list. Default 30. |
| `name` | `string` | — | no | Name for a hidden input mirroring the value on form submit as a plain `HH:mm:ss` time of day (the `<input type="time" step="1">` wire format — never an invented-date UTC instant). |
| `onOpenChange` | `(open: boolean) => void` | — | no |  |
| `onValueChange` | `(value: Date \| undefined) => void` | — | no |  |
| `open` | `boolean` | — | no |  |
| `placeholder` | `string` | — | no |  |
| `readOnly` | `boolean` | — | no |  |
| `ref` | `React.Ref<HTMLInputElement>` | — | no |  |
| `required` | `boolean` | — | no |  |
| `triggerLabel` | `string` | — | no |  |
| `value` | `Date` | — | no |  |

_Plus 3 inherited native `<input>` attributes._

## Variants
- **appearance** (default `outline`): `outline`, `soft`, `ghost`
- **size** (default `md`): `xs`, `sm`, `md`, `lg`, `xl`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · Date — The time as a native `Date`. Controlled via `value` + `onValueChange`; uncontrolled via `defaultValue`.
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — The slot-list popover's open state. Controlled via `open` + `onOpenChange`; uncontrolled via `defaultOpen`.
- Selection: single.

## Anatomy
- `time-picker`: The field shell (shared with the date pickers) — the visible control surface. Styled by `className`.
- `time-picker-input`: The borderless <input> — the type target.
- `time-picker-trigger`: The clock toggle (Popover trigger).
- `time-picker-clear`: The clear button — shown when a time is set.
- `list`: The slot listbox (role=listbox); each slot is a role=option.
- `time-picker-option`: One time slot; the current time carries aria-selected.

## Accessibility
- **Role:** textbox (APG: combobox)
- **ArrowDown:** From the field: open the slot list. In the list: move the roving focus to the next slot (clamped at the end, no wrap).
- **ArrowUp:** In the list: move the roving focus to the previous slot (clamped at the start, no wrap).
- **Home:** In the list: jump the roving focus to the first slot.
- **End:** In the list: jump the roving focus to the last slot.
- **PageDown:** In the list: jump the roving focus forward ~one hour of slots.
- **PageUp:** In the list: jump the roving focus back ~one hour of slots.
- **Enter:** From the field: commit the typed time. In the list: commit the focused slot (select + close + return focus to the field).
- **Space:** In the list: commit the focused slot (select + close + return focus to the field).
- **Escape:** Close the slot list.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- Give the field an accessible label; the format-pattern placeholder is not a label.
- The slot list is a role=listbox of role=option slots; the current time carries aria-selected and scrolls into view on open.
- The slot list is fully keyboard-operable: a roving tabindex keeps exactly one option tabbable at a time; arrows/Home/End/PageUp/PageDown move the roving focus, and Enter/Space commits the focused slot. The list is opened from the field and returns focus there on commit.
- Type-ahead (printable-character jump within the list) is intentionally omitted — the typed field is the primary character-entry path; a deliberate deviation from the APG Listbox pattern.
- Reflect validation with aria-invalid + a described message.
- **Focus:** Field focus surface as the date pickers; the list is opened from the field and dismissed on Escape/outside.
- **Contract (warn):** Give every time picker an accessible label. — _when no associated <label htmlFor>, aria-label, or aria-labelledby_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `paddingInline` → `--garn-control-px-md` (air)

## Related
- **composes** → `utils`
- **composes** → `date-picker`
- **composes** → `use-controllable-state`
- **pairsWith** → `label`
- **pairsWith** → `form`
- **alternativeTo** → `time-field` (when a bare typed time (no slot list) is enough)

## Gotchas
- **The slot list is enormous.** — A small `interval` over 24 hours yields many options (e.g. 96 at 15 min). → Use a coarser `interval`, or switch to TimeField for free typing.
- **Two slots show the same label (e.g. 01:00 appears twice).** — A 12-hour `format` without a meridiem token (e.g. `hh:mm`) renders the AM and PM slots identically. → Include a meridiem token in `format` (e.g. `h:mm a`) so the 12-hour slots read unambiguously.

## Examples
- **basic** (canonical): A time field with a 30-minute slot list.
- **interval** (edge-case): A 15-minute slot interval.
- **twelve-hour** (canonical): A 12-hour format (h:mm a).
- **states** (edge-case): Disabled and invalid.

---

# Timeline

> A read-only chronology — activity feed, audit log, order/shipment history, changelog, or status thread. A toned-marker rail of ordered events with terse or fully-composed items, grouped day headers, a live pending tail, alternating layout, and a collapsible body.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** data-display
- **Import:** `import { Timeline } from "@garn/ui/timeline"`

## Overview
Timeline shows a sequence of events along a single axis — an activity feed, an order's status history, an audit trail, a changelog. `Timeline.Item` is one event (terse props or composed children, reflecting loading / current / complete), `Timeline.Group` is a dated/section run, and the `Separator` / `Marker` / `Connector` keep every marker aligned on one line. Use it for chronological events; for ordered *steps the user completes* use a Stepper, and for plain term→value facts use DataList.

## When to use
A read-only chronology of events that already happened — an activity feed, audit log, order/shipment history, changelog, or status thread. Reach for the terse <Timeline.Item> per event; compose the slots for rich entries.

## When not to use
An interactive, gated, forward-moving process where the user navigates steps (use Stepper); a flat list of non-temporal items (use a plain list); a single 'field: value' detail block (use DataList); progress toward one goal (use Progress).

## Do / Don't
- ✅ Give the list an accessible name (label / aria-label).
- ✅ Pass `dateTime` (ISO) on each item so the <time> carries a machine value beside the human text.
- ✅ Use `tone` for event status — it announces an sr-only word AND colours the marker from the shared badge vocabulary.
- ✅ Use Timeline.Group for day/section runs (optionally `sticky`); use `loading` for the live pending tail.
- ✅ Order items the way they should read (the component preserves the consumer's array order — no auto-sort).
- ❌ Don't use Timeline for a process the user steps through — that's Stepper (it has aria-current, focusable triggers, and gated movement).
- ❌ Don't rely on marker colour alone for meaning — keep the tone (it carries the sr-only status word).
- ❌ Don't strip the focus ring on item actions or the collapsible-body toggle.
- ❌ Don't hardcode marker colours — tones resolve through the --garn-badge-* tokens (edit dark mode in the token layer).

## Guidelines
**Use it for events in time, not for steps to take.** A timeline records what happened (or is happening); a Stepper drives a process forward. Order consistently — usually newest-first for feeds, oldest-first for histories — and stick to it.

**Give each event a clear marker and timestamp.** Use the marker `variant`/`tone` to convey state (done, current, error) and show a human-readable, locale-aware time; the `current`/`loading` states highlight what's live. Group long runs by date with `Timeline.Group`.

**Keep it scannable and accessible.** Lead each item with what changed, keep detail terse, and let the marker column stay decorative (aria-hidden) while the text carries the meaning to assistive tech. Don't overload one axis with unrelated streams.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `side` | `"alternating" \| "end" \| "start"` | `start` | no | Marker/content placement: left rail (default), right rail, or zig-zag. |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no | Marker geometry ladder (identity — does not shrink with density). |
| `tone` | `"brand" \| "danger" \| "info" \| "muted" \| "neutral" \| "success" \| "warning"` | `neutral` | no | Default marker tone inherited by every item (each item may override). |
| `variant` | `"dot" \| "icon" \| "outline"` | `dot` | no |  |
| `dense` | `boolean` | — | no | Tighten type + line-height for log-style feeds (spacing already follows density). |
| `label` | `React.ReactNode` | — | no | Convenience accessible name for the list (the `<ol>`). |

_Plus 283 inherited native `<ol>` attributes._

### `Timeline.Item` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `current` | `boolean` | — | no | Emphasise this entry as the live/active one (a tonal halo, like Stepper's current step). |
| `dateTime` | `string` | — | no | Machine-readable ISO timestamp for the `<time datetime>` attribute. |
| `loading` | `boolean` | — | no | This entry is in progress — the marker shows a spinner, the connector fades out. |
| `marker` | `React.ReactNode` | — | no | Custom marker content (icon / avatar / glyph). Overrides the default dot. |
| `side` | `TimelineResolvedSide` | — | no | Per-item side override (ignored unless the layout is alternating). |
| `time` | `React.ReactNode` | — | no | Terse mode: the timestamp (rendered in a `<time>`). |
| `title` | `React.ReactNode` | — | no | Terse mode: the event title. |
| `tone` | `"brand" \| "danger" \| "info" \| "muted" \| "neutral" \| "success" \| "warning"` | — | no | Marker/text tone. Overrides the Timeline default. |
| `value` | `string` | — | no | Stable key (reserved for future selection/anchoring). |
| `variant` | `"dot" \| "icon" \| "outline"` | — | no | Marker geometry: a plain dot (default), a tonal icon ring, or an outline ring. |

_Plus 278 inherited native HTML attributes._

### `Timeline.Group` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `React.ReactNode` | — | no | Section header text (e.g. "Today", "Yesterday", a date). |
| `sticky` | `boolean` | — | no | Stick the header to the top of the scroll container while its run is visible. |

_Plus 281 inherited native HTML attributes._

### `Timeline.Title` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no | Render as the child element (e.g. a heading or a link), merging props. |

_Plus 280 inherited native HTML attributes._

### `Timeline.Time` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `dateTime` | `string` | — | no | Machine-readable ISO value for the `datetime` attribute. |

_Plus 279 inherited native HTML attributes._

### `Timeline.Body` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `collapsible` | `boolean` | — | no | Clamp to N lines with a "Show more" disclosure (uncontrolled). |
| `lines` | `number` | — | no | Number of lines to show when collapsed (default 2). |
| `showLessLabel` | `string` | — | no | Label for the collapse control (default "Show less"). |
| `showMoreLabel` | `string` | — | no | Label for the expand control (default "Show more"). |

_Plus 280 inherited native HTML attributes._

### `Timeline.Skeleton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `dense` | `boolean` | — | no |  |
| `rows` | `number` | — | no | How many placeholder rows to render (default 3). |
| `size` | `TimelineSize` | — | no |  |

_Plus 283 inherited native HTML attributes._

## Variants
- **side** (default `start`): `start`, `end`, `alternating`
- **size** (default `md`): `sm`, `md`, `lg`
- **tone** (default `neutral`): `neutral`, `brand`, `info`, `success`, `warning`, `danger`, `muted`
- **variant** (default `dot`): `dot`, `icon`, `outline`

## Anatomy
- `timeline`: The list — a real <ol> carrying side/size/dense data-attrs. Named via label / aria-label / aria-labelledby.
- `timeline-label`: Optional convenience heading rendered above the list (when `label` is set).

**Parts**
- `Timeline.Item` (`timeline-item`) · required: One event — a <li>. Dual-mode: terse (title / time / tone / marker / variant / loading / current / side) or composed children. Reflects data-state (loading | current | complete).
- `Timeline.Group` (`timeline-group`): A dated/section run — an <li> header (optionally `sticky`) over a nested <ol> of its items; valid HTML that AT announces as a sub-list.
- `Timeline.Separator` (`timeline-separator`): The fixed-width marker + connector column (decorative, aria-hidden) that keeps every marker on one axis.
- `Timeline.Marker` (`timeline-marker`): The dot / icon / outline ring at the head of an item (carries the `variant` axis). Decorative; a loading item shows a Spinner.
- `Timeline.Connector` (`timeline-connector`): The vertical line tying an item to the next; hidden on the last item; fades after a pending item.
- `Timeline.Content` (`timeline-content`): The text column (title · time · body · actions).
- `Timeline.Title` (`timeline-title`): The event title (asChild to render a heading or link).
- `Timeline.Time` (`timeline-time`): The timestamp — a real <time datetime> carrying the machine ISO value beside the human text.
- `Timeline.Body` (`timeline-body`): The event body; when `collapsible`, clamps to `lines` with a real <button aria-expanded> disclosure.
- `Timeline.Actions` (`timeline-actions`): A trailing row of normal focusable controls (the <li> itself isn't interactive).
- `Timeline.Opposite` (`timeline-opposite`): The meta rail on the far side of the marker (typically the timestamp in an alternating layout).
- `Timeline.Skeleton` (`timeline-skeleton`): A loading preset — marker + connector + 2-line placeholders in the rail's exact geometry.

## Accessibility
- **Role:** list
- **WCAG:** 1.3.1 Info and Relationships (A); 1.4.1 Use of Color (A); 1.4.3 Contrast (Minimum) (AA); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- A real <ol> of <li> events — an ordered list of facts, NOT a navigation. There is deliberately no aria-current, no roving focus, and no panels (the Stepper distinction).
- Each timestamp is a <time datetime> carrying a machine ISO value beside the human text (pass `dateTime`; otherwise the visible text is used as a best-effort value).
- The marker is decorative (aria-hidden); its status reaches AT via an sr-only tone word ('Error: …', 'Success: …') so colour is never the sole signal (WCAG 1.4.1). neutral/brand/muted carry no status word.
- A Timeline.Group renders an <li> heading over a nested <ol>, so AT announces a sub-list under the section header without faking flat numbering.
- Give the list an accessible name via `label`, `aria-label`, or `aria-labelledby` (dev-warns if missing). Items' actions and the collapsible-body toggle are normal focusable controls.
- **Focus:** The list and items aren't focusable; only their actions and the collapsible-body toggle are, each with a 2px --garn-ring focus ring.
- **Contract (warn):** Give the Timeline an accessible name via `label`, `aria-label`, or `aria-labelledby`. — _when a Timeline has no `label`, `aria-label`, or `aria-labelledby`_

## Tokens
- `gap` → `--garn-gap-stack` (air)
- `markerFill` → `--garn-badge-neutral-bold` · brandable
- **Internal (never externalize):** `--m-bg`

## Related
- **composes** → `utils`
- **composes** → `spinner` (when a loading (pending) item shows a Spinner in its marker)
- **slotAccepts** → `avatar` (when a Timeline.Marker (variant=icon) hosts an avatar for an actor's event)
- **slotAccepts** → `button` (when a Timeline.Actions row hosts buttons / links)
- **slotAccepts** → `empty` (when an empty feed renders an Empty inside the Timeline)
- **alternativeTo** → `stepper` (when the sequence is an interactive, gated process rather than a past-facing record)

## Recipes
- **activity-feed** — A toned activity feed / audit log with timestamps. _(use when showing a chronology of events that already happened)_

## Gotchas
- **Reaching for Timeline to build a multi-step wizard / checkout flow.** — Timeline is a past-facing record; a forward, gated process is Stepper. → Use Stepper for interactive processes (it has aria-current, focusable triggers, gated movement); Timeline for history.
- **Screen readers don't announce an event's status.** — The marker is decorative — status rides in the tone's sr-only word, and neutral/brand/muted carry none. → Set a status tone (info/success/warning/danger) so the sr-only word is announced; don't rely on colour.
- **The <time> has no machine-readable value.** — Only visible text was passed; the ISO value comes from `dateTime`. → Pass `dateTime` (e.g. "2026-06-28T14:20") on each item alongside the human `time`.
- **A dev console warns the Timeline has no accessible name.** — No `label`, `aria-label`, or `aria-labelledby`. → Pass `label` (rendered + wired) or an aria-label / aria-labelledby.

## Examples
- **basic** (canonical): Terse items — title + time + tone, the order-activity feed.
- **tones** (edge-case): The full palette — neutral · brand · info · success · warning · danger · muted.
- **markers** (edge-case): Marker geometry — dot · outline · icon.
- **sizes** (edge-case): sm · md · lg marker ladders.
- **current** (edge-case): A `current` item with a tonal halo — a live shipment tracker.
- **pending** (edge-case): A loading tail — spinner marker + a fading connector.
- **rich** (edge-case): Composed items — avatar markers, a collapsible body, and an actions row.
- **grouped** (edge-case): Timeline.Group day headers (Today / Yesterday) over nested lists.
- **alternating** (edge-case): side="alternating" — a zig-zag roadmap.
- **end-side** (edge-case): side="end" — the rail on the trailing edge.
- **dense** (edge-case): dense + sm — a tight system-event log.
- **skeleton** (edge-case): Timeline.Skeleton — the loading preset in the rail's geometry.
- **empty** (edge-case): An Empty state inside a Timeline with no events.

## Source map

Regions in `timeline.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L2–10 (9 lines) — React, Radix Slot, cva, shared utils
- `types` L11–64 (54 lines) — overview doc, axis aliases, tone-word map
- `utils` L65–79 (15 lines) — text-extraction helper
- `context` L80–121 (42 lines) — timeline + item contexts and hooks
- `root` L122–212 (91 lines) — Timeline (the <ol>, ambient defaults, index mapping)
- `group` L213–275 (63 lines) — TimelineGroup (dated section run)
- `item` L276–386 (111 lines) — TimelineItem (dual-mode row, side resolution)
- `separator` L387–415 (29 lines) — TimelineSeparator (marker + connector rail)
- `marker` L416–518 (103 lines) — timelineMarkerVariants + TimelineMarker
- `connector` L519–550 (32 lines) — TimelineConnector (the vertical line)
- `content` L551–717 (167 lines) — Content, Title, Time, Body, Actions
- `opposite` L718–744 (27 lines) — TimelineOpposite (far-side meta rail)
- `skeleton` L745–805 (61 lines) — TimelineSkeleton (loading preset)
- `exports` L806–855 (50 lines) — compound assembly + named re-exports

---

# Toggle Group

> A group of toggle buttons acting as one single- or multi-select control.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { ToggleGroup } from "@garn/ui/toggle-group"`

## Overview
ToggleGroup binds related toggles into one control — a segmented single-choice selector or a multi-select toolbar (text alignment, formatting marks). `ToggleGroup` sets `type` (`single` for a segmented pick-one, `multiple` for independent toggles), owns the `value`, and shares appearance/size to each `ToggleGroupItem`. Use it for a compact set of visual, button-style options; for a labelled form choice use RadioGroup (one) or Checkboxes (several), and for a single toggle use Toggle.

## When to use
Group related toggles into one control — a segmented single-choice selector or a multi-select toolbar (alignment, formatting marks).

## When not to use
One independent on/off (use toggle); a single instant setting (use switch); a long list (use select); a few exclusive choices in a form (use radio-group); switching between views (use tabs).

## Do / Don't
- ✅ Set `type="single"` for one-of-N, `type="multiple"` for many-of-N.
- ✅ Set appearance/size on the group — items inherit them via context.
- ✅ Label the group, and give each item (often icon-only) an aria-label and a unique `value`.
- ❌ Don't mix unrelated actions into one group.
- ❌ Don't leave the group or its icon-only items unlabeled.
- ❌ Don't use it to navigate between pages (use tabs/links).

## Guidelines
**Pick `single` vs `multiple` to match the choice.** `single` is a segmented control (exactly one active — alignment); `multiple` is independent toggles (bold + italic together). Choosing the wrong type confuses what selection means.

**Keep it small, labelled, and even.** It works for a handful of peer options shown at once; a long list belongs in a Select. Give each item an accessible name (icon-only items especially) and a consistent size/appearance across the group.

**Use it for visual options, not form fields.** When the choice is a labelled field in a form, RadioGroup/Checkbox communicate intent better. Preserve the roving-focus keyboard model and make the active state clear beyond color alone.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline"` | `ghost` | no |  |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |

_Plus 288 inherited native HTML attributes._

## Variants
- **appearance** (default `ghost`): `ghost`, `outline`
- **size** (default `md`): `sm`, `md`, `lg`

## State model
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string | string[] — The pressed item value(s). `type="single"` ⇒ string; `type="multiple"` ⇒ string[].

## Anatomy

**Parts**
- `ToggleGroup` (`toggle-group`) · required: Root — sets `type` (single | multiple), owns `value`, and shares appearance/size to items via context.
- `ToggleGroupItem` (`toggle-group-item`) · required: One toggle in the group; needs a unique `value`. Inherits appearance/size from the group.

## Accessibility
- **Role:** group
- **Tab:** Move focus into the group (roving tabindex).
- **ArrowLeft / ArrowRight / ArrowUp / ArrowDown:** Move between items in the group.
- **Enter / Space:** Toggle the focused item.
- **WCAG:** 1.3.1 Info and Relationships (A); 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A)
- The group is a single tab stop with roving focus across items.
- Label the group (aria-label / aria-labelledby) and give each icon-only item its own aria-label.
- `type="single"` behaves like a radio set; `type="multiple"` like a set of independent toggles.
- **Contract (warn):** Label the group and each icon-only item (aria-label on the group and on each item). — _when the group has no accessible name (aria-label / aria-labelledby) and its items are icon-only_

## Tokens
- `itemHeight` → `--garn-control-h-md` (air)
- `ring` → `--garn-ring` · brandable

## Related
- **composes** → `utils`
- **composes** → `toggle`
- **alternativeTo** → `radio-group` (when the exclusive options belong in a form and should all read as labeled choices)
- **alternativeTo** → `tabs` (when the choices switch between views rather than set a value)

## Recipes
- **formatting-toolbar** — A multi-select toolbar of formatting marks (bold / italic / underline). _(use when toggling several independent options on a selection)_

## Gotchas
- **TypeScript error or nothing selects.** — `type` is required on the group, and each ToggleGroupItem needs a unique `value`. → Set `type="single"` or `type="multiple"`, and give every item a unique value.
- **An item's appearance/size doesn't match the group.** — appearance/size are set on the group and shared via context; per-item values are overridden by the group's. → Set appearance/size on the ToggleGroup, not on individual items.

## Examples
- **basic** (canonical): Multi-select formatting toolbar.
- **single** (playground): Single-select alignment (outline).

---

# Toggle

> A two-state on/off button for a formatting mark, view option, or setting.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** form-control
- **Import:** `import { Toggle } from "@garn/ui/toggle"`

## Overview
Toggle is a single two-state (on/off) button — a pressed/unpressed control for a formatting mark (bold), a view option, or a toolbar setting. It looks like a button but holds state via `aria-pressed`, with `appearance` (ghost / outline) and `size`. Use it for a binary control inside a toolbar; for a labelled settings switch use Switch, for a checkbox-style boolean in a form use Checkbox, and for a set of related toggles use ToggleGroup.

## When to use
A single two-state (on/off) button — toggling a formatting mark, a view option, or a toolbar setting.

## When not to use
A setting that reads as on/off text (use switch); a one-shot action (use button); choosing among options (use toggle-group or radio-group).

## Do / Don't
- ✅ Use `pressed`/`onPressedChange` (controlled) or `defaultPressed` (uncontrolled).
- ✅ Give icon-only toggles an aria-label.
- ✅ Reserve it for state you can toggle, not a fire-once action.
- ❌ Don't use a Toggle for a non-stateful action — that's a Button.
- ❌ Don't ship an icon-only Toggle with no accessible name.
- ❌ Don't use a lone Toggle where a labeled Switch communicates the setting better.

## Guidelines
**Use Toggle for a button that stays pressed.** It's the right control for toolbar-style on/off (bold, mute) where the affordance is a button, not a form field; a standalone setting reads better as a Switch. Make the pressed state visually distinct from hover.

**Label icon-only toggles and convey state beyond color.** An icon toggle needs an `aria-label`, and the on/off difference must be visible without relying on color alone (fill, outline, the icon itself). The `aria-pressed` state is what AT announces — keep it accurate.

**Reach for ToggleGroup when toggles relate.** Several alignment or formatting toggles belong in a ToggleGroup so single-choice/multi-select semantics and shared appearance/size are modeled — don't hand-assemble loose toggles for that.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline"` | `ghost` | no |  |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |

_Plus 294 inherited native `<button>` attributes._

## Variants
- **appearance** (default `ghost`): `ghost`, `outline`
- **size** (default `md`): `sm`, `md`, `lg`

## State model
- `pressed` (controlled) / `defaultPressed` (uncontrolled), `onPressedChange` · boolean — Whether the toggle is on. Controlled via `pressed` + `onPressedChange`; uncontrolled via `defaultPressed`.

## Anatomy
- `toggle` — accepts icon | text | icon + text: The pressable button; data-state=on|off.

## Accessibility
- **Role:** button (APG: button)
- **Enter / Space:** Toggle the pressed state.
- **WCAG:** 2.1.1 Keyboard (A); 4.1.2 Name, Role, Value (A); 2.4.7 Focus Visible (AA)
- Radix sets aria-pressed to reflect the on/off state.
- An icon-only toggle has no text — give it an aria-label.
- Forced colors: the on state maps to Highlight / HighlightText.
- **Focus:** 1px ring in --garn-ring on :focus-visible.
- **Contract (warn):** Give an icon-only toggle an accessible name (aria-label). — _when the toggle is icon-only (no text child) and has no aria-label / aria-labelledby / title_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `ring` → `--garn-ring` · brandable

## Related
- **composes** → `utils`
- **pairsWith** → `toggle-group`
- **alternativeTo** → `switch` (when the setting reads better as a labeled on/off)
- **alternativeTo** → `button` (when the action doesn't hold state)

## Gotchas
- **An icon-only toggle is announced with no name.** — Toggle has no text to derive an accessible name from. → Pass aria-label to the Toggle.

## Examples
- **basic** (canonical): An icon + text toggle.
- **variants** (playground): ghost / outline / sizes, icon-only.

---

# Toolbar

> A semantic, roving-focus strip of related controls — one tab stop, arrow-key navigation, and measured overflow that collapses out-of-space actions into a menu.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** layout
- **Import:** `import { Toolbar } from "@garn/ui/toolbar"`

## Overview
Toolbar is the accessible container garn was missing: a single, named region (role=toolbar) that puts a whole strip of related controls on ONE tab stop and navigates between them with the arrow keys — buttons, toggles, toggle-groups, links, a search field, and split buttons, mixed into one coherent bar. It is deliberately thin: a roving-focus + overflow shell that composes garn's Button, Toggle-group, Separator, Dropdown-menu, and Tooltip rather than re-skinning them.

That is the gap ButtonGroup doesn't fill. ButtonGroup visually joins a cluster (role=group, no keyboard model); Toolbar adds the semantic role, the single tab stop with continuous arrow navigation across nested groups, and — its marquee feature — responsive overflow: when the bar runs out of space it measures itself and collapses the out-of-space actions into a '…' more-menu, so an action is never lost and the bar keeps a stable single-row height. The role and roving only switch on at 3+ controls (the APG threshold); a 1–2 control cluster stays a plain group.

Two structural variants share the anatomy. The default `docked` bar is the flat app / editor / data-table strip. `floating` (via ToolbarFloating) is the selection bubble — a variant=floating bar anchored to a text selection with Popover, keeping focus on the caret. Density is a token concern (`size` → gap / padding / radius, control heights from --garn-control-h-*), never per-instance padding.

## When to use
A strip of 3+ related controls (buttons, toggles, links, a search field) that should behave as ONE tab stop with arrow-key navigation — editor formatting bars, app / data-table action bars, vertical tool rails, and selection bubbles — especially when they must stay reachable as the container narrows.

## When not to use
For 1–2 unrelated actions, use plain Buttons spaced with a gap. To only visually join a small related cluster without a keyboard model, use ButtonGroup. To choose one value (or several) from a set, use ToggleGroup directly. For a bar of dropdown menus (File / Edit / View), use Menubar; for a global command surface, use Command.

## Do / Don't
- ✅ Give the toolbar an aria-label (or aria-labelledby).
- ✅ Use the toolbar's own parts (ToolbarButton / ToolbarToggleGroup / ToolbarSplitButton), not standalone Button / SplitButton.
- ✅ Give every icon-only control an aria-label, and a tooltip for the visible name.
- ✅ Leave overflow on `collapse` and let the bar fold overflowing actions into the more-menu.
- ✅ Place a ToolbarInput last, and give it an aria-label.
- ✅ Name a split button's menu half for what it opens (“More save options”), distinct from the primary.
- ❌ Don't drop a standalone SplitButton into a toolbar — it isn't a roving item; use ToolbarSplitButton.
- ❌ Don't hand-pad controls with px-* / [Npx]; density comes from `size`.
- ❌ Don't hardcode role=toolbar on a 1–2 control cluster — that's a plain group, and this component switches roving on only at 3+.
- ❌ Don't hide overflowing actions yourself — let `collapse` keep them reachable in the menu.
- ❌ Don't put an editable control anywhere but last, or the arrow keys will fight the caret.

## Guidelines
**Always name the bar.** A toolbar is one thing in the page tab order, so it needs an accessible name — pass `aria-label` or `aria-labelledby`. Icon-only controls each need their own `aria-label`; pair with `tooltip` for the visible name.

**Let overflow do the work; don't hand-hide.** Keep every action in the markup and let `overflow=collapse` (the default) decide what folds into the more-menu at the current width. Reserve `scroll` / `wrap` for bars that must show everything, and `visible` when you position the bar yourself.

**Reach for the toolbar's own parts.** Use ToolbarButton / ToolbarToggleGroup / ToolbarSplitButton / ToolbarInput — not the standalone Button / SplitButton — so each control roves correctly and knows how to re-render itself as a menu row when it overflows. A standalone SplitButton in a toolbar breaks the single-tab-stop model; ToolbarSplitButton is the fix.

**Place a search field last.** A ToolbarInput is pinned (it never collapses) and takes over the arrow keys for the caret while focused, so put it at the end per APG — actions collapse in front of it.

**Prefer a soft or padded surface when controls have selection or focus rings.** A flush `ghost` bar gives a focus ring no room; a `soft` bar also lifts selected toggles to an elevated thumb that reads on the tint.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft" \| "solid"` | `outline` | no |  |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | no |  |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no |  |
| `variant` | `"docked" \| "floating"` | `docked` | no |  |
| `dir` | `"ltr" \| "rtl"` | — | no |  |
| `loop` | `boolean` | — | no | Wrap first↔last on arrow keys (roving). Default `true`. |
| `overflow` | `"collapse" \| "scroll" \| "visible" \| "wrap"` | — | no | Wrap-first, scroll, keep-visible, or (default) measure & collapse to a menu. |
| `overflowIcon` | `React.ReactNode` | — | no | Glyph for the collapsed overflow trigger (default: a horizontal ellipsis). |
| `overflowLabel` | `string` | — | no | Accessible name for the "…" overflow trigger. |

_Plus 279 inherited native `<div>` attributes._

### `ToolbarButton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `shortcut` | `React.ReactNode` | — | no | Keyboard shortcut for this action — one descriptor rendered in three places: a `<kbd>` in the tooltip, a shortcut hint in the overflow menu, and (when a string) `aria-keyshortcuts` on the control. |
| `tooltip` | `React.ReactNode` | — | no | Visible name hint for an icon-only button; follows orientation / RTL. |

_Plus 303 inherited native HTML attributes._

### `ToolbarSplitButton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `"aria-label"` | `string` | — | no | Accessible name of the PRIMARY half. Required when `label` carries no text (an icon-only primary) — it names the button itself, not this wrapper. |
| `align` | `"center" \| "end" \| "start"` | — | no | Menu alignment against the chevron half. Defaults to `end` — the menu is launched from the trailing half, so it hangs back under the split button rather than spilling past it. |
| `children` | `React.ReactNode` | — | yes | The menu half's contents: `DropdownMenuItem`s and friends. |
| `disabled` | `boolean` | — | no |  |
| `label` | `React.ReactNode` | — | yes | Visible label of the primary half. |
| `leading` | `React.ReactNode` | — | no | Icon placed before the primary label. |
| `menuLabel` | `string` | — | yes | Accessible name of the MENU half. Required, and it must be contextual ("More save options") rather than a repeat of the primary's name — voice control has no other way to tell the two halves apart. |
| `onSelect` | `() => void` | — | no | The primary action — the whole point of the left half. |
| `shortcut` | `React.ReactNode` | — | no | Keyboard shortcut for the PRIMARY action (tooltip `<kbd>` + aria-keyshortcuts). |
| `size` | `ToolbarSize` | — | no | Density rung for the pair. Deliberately the toolbar's own scale rather than Button's: both halves derive from one rung (the menu half taking the square one), so they cannot drift in height. |
| `tone` | `"brand" \| "danger" \| "neutral" \| "success" \| "warning"` | — | no |  |
| `tooltip` | `React.ReactNode` | — | no | Visible name hint for the primary half; follows orientation / RTL. |
| `variant` | `"default" \| "ghost" \| "link" \| "outline" \| "soft"` | — | no | Fill of both halves. Defaults to `ghost`, matching `ToolbarButton`. |

_Plus 278 inherited native HTML attributes._

### `ToolbarToggleItem` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tooltip` | `React.ReactNode` | — | no | Visible name hint for an icon-only toggle; follows orientation / RTL. |

_Plus 291 inherited native HTML attributes._

### `ToolbarInput` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"ghost" \| "outline" \| "soft"` | — | no | Field fill; defaults to `soft` to sit quietly inside the bar. |
| `leading` | `React.ReactNode` | — | no | In-field leading glyph (e.g. a search icon). |

_Plus 310 inherited native HTML attributes._

### `ToolbarFloating` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `align` | `"center" \| "end" \| "start"` | — | no |  |
| `anchor` | `React.RefObject<ToolbarAnchor \| null>` | — | no | Element or virtual anchor to float against — a `ref` to anything exposing `getBoundingClientRect` (a DOM node, or a virtual object tracking a text selection). There is no built-in trigger element; omit it only when placing the bubble yourself, since without an anchor it has no positioning reference. |
| `autoFocus` | `boolean` | — | no | Move focus into the bar on open. Default `false` — keep the caret/selection. |
| `defaultOpen` | `boolean` | — | no |  |
| `onOpenChange` | `(open: boolean) => void` | — | no |  |
| `open` | `boolean` | — | no | Controlled open state of the bubble. |
| `overflow` | `"collapse" \| "scroll" \| "visible" \| "wrap"` | — | no | Overflow of the inner bar. Default `visible` — a bubble sizes to its content. |
| `side` | `"bottom" \| "left" \| "right" \| "top"` | — | no |  |
| `sideOffset` | `number` | — | no |  |

_Plus 285 inherited native HTML attributes._

## Variants
- **variant** (default `docked`): `docked`, `floating`
- **appearance** (default `outline`): `solid`, `soft`, `outline`, `ghost`
- **size** (default `md`): `sm`, `md`, `lg`
- **orientation** (default `horizontal`): `horizontal`, `vertical`

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Open state of a ToolbarFloating bubble. Uncontrolled by default; pass `open` + `onOpenChange` to drive it from a text selection.
- `value` (controlled) / `defaultValue` (uncontrolled), `onValueChange` · string | string[] — Selection of a ToolbarToggleGroup (string for `type=single`, string[] for `type=multiple`). Uncontrolled selection is preserved across an overflow relocation via the root store.

## Anatomy
- `toolbar`: The bar container. Renders role=toolbar with a single roving tab stop at 3+ controls (APG threshold); a plain role=group at 1–2; nothing at 0. Reflects every enum axis as data-variant / data-appearance / data-size / data-orientation / data-overflow, plus data-elevated on a soft bar.
- `toolbar-overflow-trigger` — accepts the overflowIcon glyph (default: a horizontal ellipsis): The '…' more-button the measured collapse renders when actions don't fit. It carries the overflowLabel accessible name and opens a dropdown-menu holding the overflowed controls as menu rows.
- `measureMirror`: An off-screen (visibility:hidden, inert, aria-hidden) clone of every child used only to measure widths for the collapse fit — never focusable, never in the a11y tree.

**Parts**
- `ToolbarGroup` (`toolbar-group`): A focus-transparent role=group cluster of related controls. It adds no tab stop of its own — its children are roving items of the outer toolbar — and collapses as a unit into the overflow menu (its aria-label becomes a menu label).
- `ToolbarSeparator` (`toolbar-separator`): A decorative divider between control clusters, rotated with orientation. Suppressed automatically when a collapse leaves it leading or trailing, and de-duplicated inside the overflow menu (where it renders as a DropdownMenuSeparator).
- `ToolbarButton` (`toolbar-button`): An action button (composes Button, default variant ghost). Takes `tooltip` (visible name for an icon-only button) and `shortcut` (one descriptor rendered as a <kbd> in the tooltip, a shortcut hint in the overflow menu, and aria-keyshortcuts when a string). Focusable-when-disabled: a disabled button stays arrow-reachable via aria-disabled, inert to activation.
- `ToolbarSplitButton` (`toolbar-split-button`): A primary action attached to a menu of related ones, as ONE roving stop — the toolbar-native split button (the standalone SplitButton cannot be a toolbar item). Prop-driven: `label` / `onSelect` / `menuLabel`, with the menu contents as children. The menu half is tabIndex=-1 and reachable on the perpendicular arrow axis; the pair counts once toward the APG threshold and collapses to a primary row + a named submenu.
- `ToolbarToggleGroup` (`toolbar-toggle-group`): A single- or multiple-selection toggle set that delegates roving to the toolbar (Radix ToggleGroup with rovingFocus off), so it introduces no second tab stop. Uncontrolled selection parks on a root-lifted store keyed per group, so it survives being relocated between the bar and the overflow menu.
- `ToolbarToggleItem` (`toolbar-toggle-item`): One toggle within a ToolbarToggleGroup (styled by toggleVariants). Takes `tooltip` for an icon-only visible name. In the overflow menu it renders as a DropdownMenuCheckboxItem (multiple) or DropdownMenuRadioItem (single). Focusable-when-disabled.
- `ToolbarLink` (`toolbar-link`): A navigation link styled as a ghost button and roving as a toolbar item (composes Radix Toolbar.Link → <a>). Uses aria-disabled (a link takes no native disabled) to stay arrow-reachable while inert.
- `ToolbarInput` (`toolbar-input`): A first-class roving text/search member (styled by fieldVariants, optional leading glyph). Arrow/Home/End move the caret rather than roving focus (the editable escape hatch); it is pinned in the bar (never collapses to the menu) while actions overflow. Place it LAST per APG.
- `ToolbarFloating` (`toolbar-floating`): The floating (selection / bubble) toolbar — the text-selection bubble pattern. Composes Popover to anchor a variant=floating Toolbar against an element or virtual `anchor` (a ref exposing getBoundingClientRect). Anchor-only: there is NO built-in trigger element. Focus stays on the selection by default (autoFocus off); the popover surface is stripped to a bare positioner so the inner floating bar owns the elevated look.

## Accessibility
- **Role:** toolbar (APG: toolbar)
- **Tab / Shift+Tab:** Enter or leave the toolbar as a whole — one tab stop at 3+ controls. Focus lands on the last-focused (or first) control; a second Tab exits the bar entirely.
- **ArrowRight / ArrowLeft / ArrowDown / ArrowUp:** Rove to the next / previous control along the orientation axis (→/← horizontal, ↓/↑ vertical). Wraps first↔last when `loop` (default true). Direction follows `dir` — under RTL, ArrowLeft moves to the next (visually-left) control.
- **Home / End:** Focus the first / last control.
- **Enter / Space:** Activate the focused control; on a ToolbarSplitButton's menu half, open its menu.
- **Escape:** Close an open overflow or split-button menu and return focus to its trigger.
- **ArrowDown / ArrowUp:** On a ToolbarSplitButton, move between the primary and menu halves — on the axis perpendicular to the bar's roving (RTL-mirrored on a vertical rail), so no roving key is stolen.
- **WCAG:** 2.1.1 Keyboard (A); 2.5.3 Label in Name (A); 4.1.2 Name, Role, Value (A); 1.4.11 Non-text Contrast (AA); 2.5.8 Target Size (Minimum) (AA)
- role=toolbar is applied only at 3+ controls (APG threshold). 1–2 controls render a plain role=group with independent tab stops; 0 controls render neither.
- Requires an accessible name — pass aria-label or aria-labelledby (dev-warned when missing on a roving toolbar).
- Single tab stop via roving tabindex (the focused control is tabindex=0, the rest -1), using real DOM focus, not aria-activedescendant.
- aria-orientation=vertical is emitted only on a vertical rail.
- Disabled controls stay in the roving sequence as aria-disabled (focusable-when-disabled) rather than being removed from the tab order.
- Icon-only controls take their accessible name from aria-label; pair with Tooltip for the visible name (the tooltip side follows orientation / RTL).
- Overflowed controls stay reachable inside the '…' dropdown menu; the trigger carries the overflowLabel accessible name.
- In a ToolbarSplitButton the menu ARIA (aria-haspopup / aria-expanded) lives ONLY on the menu half, supplied by the dropdown-menu primitive; both halves are separate native buttons.
- **Focus:** Roving tabindex (Radix RovingFocusGroup) — one tab stop, real DOM focus moved by the arrow keys. Focus returns to the overflow / split-button trigger when its menu closes.
- **Forced colors:** Each control's focus ring is drawn by its own Button / Toggle and survives when backgrounds are dropped; the collapse container's clip-margin keeps the ring visible.; The floating bubble keeps a real border (composes Popover), and separators keep a real rule.
- **Contract (error):** Tab moves focus onto the toolbar exactly once; a second Tab leaves it. Controls are reached by the arrow keys via roving tabindex, never by Tab. — _when role=toolbar (3+ controls)_
- **Contract (error):** ArrowRight focuses the next control and ArrowLeft the previous; with `loop` (default), ArrowRight past the last wraps to the first. — _when a horizontal toolbar_
- **Contract (error):** The root exposes aria-orientation=vertical; ArrowDown / ArrowUp move between controls and ArrowLeft / ArrowRight do not rove. — _when orientation=vertical_
- **Contract (error):** Home focuses the first control; End focuses the last. — _when role=toolbar_
- **Contract (error):** ArrowLeft moves to the next (visually-left) control — arrow direction follows the locale, not the physical key. — _when a horizontal toolbar under dir=rtl_
- **Contract (error):** A nested group adds no second tab stop; its items are traversed inline within the single toolbar arrow sequence (Shift+Tab is not trapped). — _when a ToolbarToggleGroup or ToolbarGroup inside the bar_
- **Contract (error):** A disabled control still receives focus via the arrows (aria-disabled) but does not activate on Enter / Space / click. — _when a disabled ToolbarButton / ToolbarToggleItem / ToolbarLink / ToolbarSplitButton_
- **Contract (error):** Exposes a non-empty accessible name via aria-label (the icon alone is not a name). — _when an icon-only ToolbarButton / ToolbarToggleItem / ToolbarLink_
- **Contract (error):** Every enum axis reflects to its data-* attribute: data-variant, data-appearance, data-size, data-orientation, data-overflow (and data-elevated on a soft bar). — _when always_
- **Contract (error):** Overflowing controls render inside the '…' dropdown menu and every action stays keyboard-reachable — none are dropped. — _when overflow=collapse and the bar is narrower than its controls_
- **Contract (warn):** The overflow menu entrance animates opacity only — no scale transform. — _when prefers-reduced-motion: reduce_
- **Contract (error):** The input is an arrow-reachable roving member whose Arrow / Home / End move the caret (not focus); it is pinned in the bar while actions collapse and never renders as a menu row. — _when a ToolbarInput in a collapsing bar_
- **Contract (warn):** A toolbar needs an accessible name — pass aria-label or aria-labelledby. — _when a roving toolbar with no aria-label / aria-labelledby_
- **Contract (warn):** A search / text field needs an accessible name — pass aria-label or aria-labelledby (a placeholder is not a reliable name). — _when a ToolbarInput with no aria-label / aria-labelledby_
- **Contract (error):** Adds exactly ONE tab stop: the menu half is tabIndex=-1; the two halves are one roving item reached by the perpendicular arrow axis, and roving-axis keys / Home / End pressed on the menu half are handed back to the bar. — _when a ToolbarSplitButton in a roving toolbar_
- **Contract (error):** aria-haspopup / aria-expanded appear on the menu half only — never on the primary half or the wrapper — and the menu opens from the keyboard. — _when a ToolbarSplitButton with a menu half_
- **Contract (error):** A ToolbarSplitButton counts once toward the roving threshold: two controls plus one stays a plain group; three turns roving on. — _when the APG 3-control threshold_
- **Contract (error):** Both halves stay arrow-reachable and announced aria-disabled; neither activates, and the menu half is not a live trigger at all. — _when a disabled ToolbarSplitButton_
- **Contract (error):** On collapse it becomes a primary menu row plus a submenu named by menuLabel; neither action is lost. — _when a ToolbarSplitButton in an overflowing bar_
- **Contract (warn):** Name the menu half for what it opens (e.g. “More save options”), not a copy of the primary — voice control has no other way to tell the halves apart. — _when a ToolbarSplitButton whose menu half name equals the primary half's_
- **Contract (warn):** An icon-only primary half needs an accessible name — pass aria-label (it names the button, not the wrapper). — _when a ToolbarSplitButton with an icon-only primary half and no aria-label_
- **Contract (error):** It renders a variant=floating toolbar inside a role=dialog popover surface (sharing the bar's accessible name) and does not steal focus from the selection by default (autoFocus off). — _when a ToolbarFloating bubble opens_

## Tokens
- `height` → `--garn-control-h-md` (air)
- `clipMargin` → `--garn-space-6` (air)

## Related
- **composes** → `utils`
- **composes** → `button`
- **composes** → `button-group` (when hosts the split button seam)
- **composes** → `toggle`
- **composes** → `toggle-group`
- **composes** → `separator`
- **composes** → `dropdown-menu` (when the overflow more-menu)
- **composes** → `tooltip` (when icon-only visible names + shortcuts)
- **composes** → `popover` (when anchors the floating bubble)
- **composes** → `kbd` (when renders shortcut hints)
- **slotAccepts** → `button` (when as ToolbarButton)
- **slotAccepts** → `toggle-group` (when as ToolbarToggleGroup)
- **pairsWith** → `command` (when the bar and a ⌘K palette share one action set)
- **pairsWith** → `tooltip`
- **alternativeTo** → `button-group` (when you only need a visually-joined cluster, without a roving keyboard model)
- **alternativeTo** → `menubar` (when the bar is a menu bar of dropdown menus rather than a control strip)

## Recipes
- **editor-formatting-bar** — A dense formatting bar that stays one row at any width: toggle-groups for text style, action buttons, and measured overflow into a more-menu. _(use when a prioritised action set must stay a single row at any width)_
- **toolbar-split-button** — A primary toolbar action attached to a menu of related ones, as one roving stop. Use ToolbarSplitButton — the standalone SplitButton is not a roving item. _(use when a primary toolbar action has a small set of related variants)_
- **selection-bubble** — A floating formatting bar that tracks a text selection — anchor ToolbarFloating to a ref exposing getBoundingClientRect (a DOM node or a virtual selection rect). _(use when a formatting bar should appear over and follow a text selection)_

## Gotchas
- **No arrow-key navigation and no role=toolbar in the a11y tree — the bar behaves like a plain group.** — Fewer than 3 controls. Toolbar applies role=toolbar + roving only at the APG 3+ threshold; 1–2 controls stay role=group with independent tab stops. → This is intended. Add a third control for a real toolbar, or accept the plain group for a 1–2 control cluster.
- **Arrow keys skip a split button, or it adds extra Tab stops mid-bar.** — A standalone SplitButton was placed in the toolbar — its halves keep tabIndex 0 and it counts for nothing toward the roving threshold, silently downgrading the bar. → Use ToolbarSplitButton instead: it is one roving stop (menu half tabIndex=-1, reachable by the perpendicular arrow) and counts once toward the 3-control gate.
- **A search / text field disappears into the overflow menu when the bar narrows, or the arrow keys move focus off it instead of the caret.** — The editable wasn't a ToolbarInput, or wasn't placed last. → Use ToolbarInput and place it LAST. It is pinned (never collapses) and its Arrow/Home/End move the caret via the root's editable escape hatch.
- **On a soft bar, a selected toggle is hard to see — its fill is the same shade as the bar.** — A tinted (soft) bar collides with the absolute-neutral selected fill. → Nothing to do — a soft bar sets data-elevated, so selected toggles lift to a card 'thumb' that reads on the tint (WCAG 1.4.11). Don't hand-tint the controls.
- **A control's focus ring is clipped along the bar's edge, worst on a flush ghost bar.** — The collapse container clips transient item-spill; a ring drawn just outside the box gets caught at the edge. → The clip-margin (--garn-space-6) already shows a ≤3px ring; give a taller control (a ToolbarInput) room with a padded surface (soft) rather than the flush ghost.
- **A leading or trailing separator shows after the bar collapses, or two separators sit adjacent in the menu.** — Expecting to hand-manage dividers across the overflow boundary. → Don't — Toolbar trims a separator that becomes an edge after the cut and de-dupes adjacent ones in the menu automatically. Author separators for the full-width layout.
- **The toolbar (or an icon-only control, or a split button's menu half) is flagged as having no accessible name in dev.** — A roving toolbar with no aria-label, an icon-only button/input with no aria-label, or a split button whose two halves share one name. → Name the bar (aria-label / aria-labelledby); give each icon-only control an aria-label; name a split button's menu half for what it opens, distinct from the primary.

## Examples
- **basic** (canonical): A text-formatting bar: history buttons, a multi-select style group, and a single-select alignment group on one tab stop.
- **appearances** (playground): solid / soft / outline / ghost surfaces of the same bar.
- **sizes** (playground): The sm / md / lg density rungs.
- **vertical** (edge-case): A vertical tool rail — ↑/↓ navigation and aria-orientation=vertical.
- **overflow** (canonical): Measured collapse: a width-constrained bar folds out-of-space actions into a '…' menu, none dropped.
- **actions** (canonical): An app action bar mixing a group, text buttons with shortcuts, a disabled button, and a link.
- **split-button** (canonical): A ToolbarSplitButton: primary Save plus a menu of related options, as one roving stop.
- **vertical-overflow** (edge-case): A height-bounded vertical rail collapsing into a side-anchored more-menu with a custom overflowIcon.
- **search** (edge-case): A ToolbarInput pinned at the end: the search field stays put while the actions before it collapse.
- **floating** (canonical): ToolbarFloating anchored to a text selection, keeping focus on the caret.

## Source map

Regions in `toolbar.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `types` L42–106 (65 lines) — public surface + shared context
- `variants` L108–176 (69 lines) — the bar surface (semantic tokens only)
- `helpers` L178–386 (209 lines) — child classification + accessible-name probe
- `overflow` L388–603 (216 lines) — measured collapse into a "more" menu
- `root` L605–886 (282 lines) — Toolbar
- `parts` L888–1811 (924 lines) — Group / Separator / Button / ToggleGroup / ToggleItem / Link
- `floating` L1813–1891 (79 lines) — the selection / bubble toolbar (variant=floating, anchored)
- `exports` L1893–1907 (15 lines)

---

# Tooltip

> A small text hint shown on hover or focus to clarify a control.

- **Status:** stable
- **Version:** `0.3.0` (since `0.1.0`)
- **Pattern:** overlay
- **Import:** `import { Tooltip } from "@garn/ui/tooltip"`
- **Polymorphism:** `asChild`

## Overview
Tooltip adds a brief, supplementary text hint to a control — naming an icon button, spelling out an abbreviation, surfacing a shortcut. Wrap the app (or a subtree) once in a `TooltipProvider` to share delay/skip timing, then each `Tooltip` pairs a `TooltipTrigger` with a non-interactive `TooltipContent`. It's a passive label, not a surface you can click into — for interactive content use Popover, for a profile/link preview use HoverCard.

## When to use
Add a brief, supplementary text hint to a control — clarify an icon button, abbreviate a label, surface a shortcut.

## When not to use
Essential information the user must read (put it inline); interactive content like links/buttons (use a popover); a control's primary label (use a real label / aria-label).

## Do / Don't
- ✅ Keep it to a few words; mount one TooltipProvider near the app root.
- ✅ Still give icon-only triggers an aria-label — the tooltip is extra, not the name.
- ❌ Don't put interactive elements in a tooltip — it can't be focused/clicked reliably.
- ❌ Don't hide critical information behind hover only.

## Guidelines
**Never put essential or interactive content in a tooltip.** It's keyboard- and touch-hostile by nature — no clicks, no links, and it can be missed entirely. Anything required to complete the task belongs in the visible UI; the tooltip only *supplements*.

**A tooltip supplements a name, it doesn't replace one.** An icon-only button still needs its own `aria-label` — the tooltip is a hover convenience, not the accessible name. Keep the text to a few words, no rich formatting.

**Use one Provider and lean on its timing.** A single `TooltipProvider` keeps delays consistent and the skip-delay snappy when moving between controls. Don't trigger tooltips on disabled elements that can't receive focus — wrap an enabled element instead.

## State model
- `open` (controlled) / `defaultOpen` (uncontrolled), `onOpenChange` · boolean — Usually left uncontrolled (hover/focus drives it); controllable via `open` + `onOpenChange`.
- Selection: single.

## Anatomy

**Parts**
- `TooltipProvider` · required: Wraps the app (or a subtree) once; shares delay/skip config across tooltips.
- `Tooltip` · required: Root — owns the open state for one tooltip.
- `TooltipTrigger` (`tooltip-trigger`) · required: The element the hint describes (asChild to wrap your control).
- `TooltipContent` (`tooltip-content`) · required: The hint bubble (portaled, non-interactive).

## Accessibility
- **Role:** tooltip (APG: tooltip)
- **Tab:** Focusing the trigger shows the tooltip.
- **Escape:** Dismiss the tooltip while the trigger stays focused.
- **WCAG:** 1.4.13 Content on Hover or Focus (AA); 4.1.2 Name, Role, Value (A)
- Trigger is described by the tooltip (aria-describedby); shows on hover AND keyboard focus.
- Content is non-interactive — never put links/buttons inside a tooltip (use a popover).
- **Focus:** Appears on trigger focus, not just hover; dismissible with Escape.
- **Contract (warn):** Give the trigger its own accessible name (aria-label); the tooltip is supplementary, not a label. — _when the trigger is an icon-only control that relies on the tooltip for its only accessible name_
- **Contract (warn):** Wrap the app (or subtree) in a single TooltipProvider. — _when a Tooltip is rendered without a TooltipProvider ancestor_

## Tokens
- `fill` → `--garn-brand-solid` · brandable
- `motion` → `--garn-motion-fast`

## Related
- **composes** → `utils`
- **pairsWith** → `button` (when to clarify an icon-only button)
- **pairsWith** → `kbd` (when to show the shortcut for the action)
- **alternativeTo** → `popover` (when the content needs to be interactive)

## Recipes
- **icon-button-tooltip** — A tooltip clarifying an icon-only button (which still carries its own aria-label). _(use when an icon-only control needs a visible hint)_

## Gotchas
- **The tooltip never appears, or only on the first one.** — No TooltipProvider ancestor wrapping the Tooltip(s). → Mount a single <TooltipProvider> near the app root (or wrap the subtree).

## Examples
- **basic** (canonical): Provider → tooltip on a button.

---

# Tracker

> A strip of tone-coloured blocks showing a status history — uptime, SLA, or health over time.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Tracker } from "@garn/ui/tracker"`

## Overview
Tracker is the status-page strip: a dense row of small blocks, each coloured by a status tone, that reads as an at-a-glance history — 90 days of uptime, a run of health checks, an SLA window. It's the ops counterpart to a sparkline: shape over time, but categorical (good/degraded/down) rather than numeric.

## When to use
Show a categorical status history over time — uptime, incidents, SLA windows, run health.

## When not to use
A numeric trend (use Sparkline); a single current status (use Badge); a proportion (use Progress/CategoryBar).

## Do / Don't
- ✅ Give the strip an `aria-label` summary and each block a `title`.
- ✅ Use the semantic tones so status meaning is consistent with the rest of the system.
- ❌ Don't rely on colour alone — keep the per-block `title` and the summary label.
- ❌ Don't encode magnitude in block size — Tracker is categorical.

## Guidelines
**Summarise in the label.** The strip is one `role=img`; give it an `aria-label` that states the takeaway ("99.2% uptime over 90 days") — a screen-reader user shouldn't have to infer it from colours.

**Lean on tone, not colour alone.** Blocks use the semantic tones (success/warning/danger/neutral), and each carries a hover `title` with the date + status so the detail is reachable without relying on hue.

**Keep blocks uniform.** Equal-width blocks with a tiny gap read as a timeline; don't vary size to encode a second dimension — that's a different chart.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `TrackerItem[]` | — | yes |  |

_Plus 279 inherited native `<div>` attributes._

## Anatomy
- `tracker`: The strip (role=img); a flex row of blocks.
- `tracker-block`: One status block; `data-tone` + a hover `title`.

## Accessibility
- **Role:** img
- **WCAG:** 1.1.1 Non-text Content (A)
- role=img with an `aria-label` summary (e.g. "99.2% uptime, 90 days") — pass one; the blocks alone don't convey the summary.
- Each block carries a hover `title` (date + status) and reflects `data-tone`.
- Tone maps to the semantic success/warning/danger/info/neutral tokens.

## Related
- **composes** → `utils`
- **pairsWith** → `badge` (when labelling the current/overall status beside the strip)
- **alternativeTo** → `sparkline` (when the history is numeric rather than categorical)

## Gotchas
- **Screen readers get nothing useful.** — role=img with no `aria-label`. → Pass an `aria-label` that summarises the strip.

## Examples
- **basic** (canonical): 60-day uptime — mostly healthy with an outage + degraded days.
- **statuses** (edge-case): A short run mixing all tones incl. a neutral no-data block.

---

# Tree

> An arbitrary-depth hierarchical tree — recursive expand/collapse nodes with roving-tabindex keyboard navigation (WAI-ARIA Tree View), for file explorers, folder/nav sidebars, and threaded or org structures. Terse or composed items, selection (single / multiple with range + ⌘A), tri-state checkbox cascade, filter-to-reveal with highlighting, scroll-to-node, async lazy children, and inline rename.

- **Status:** stable
- **Version:** `0.3.0` (since `0.2.0`)
- **Pattern:** data-display
- **Import:** `import { Tree } from "@garn/ui/tree"`
- **Polymorphism:** `asChild` (default element `<ul>`)

## Overview
Tree is the hierarchical collection — recursive, same-shape nodes that expand and collapse to arbitrary depth, navigated with a full WAI-ARIA Tree View keyboard model. Reach for it for file/folder explorers, nested navigation sidebars, and threaded or org/category structures. `Tree.Item` is one node (terse `label`/`icon`/`trailing`/`actions`, or composed slots); nested items become its children. It scales from a read-only outline to selection (single active node, or multi-select with range + ⌘A), to a checkbox tree with tri-state cascade — plus filter-to-reveal, scroll-to-node, async lazy loading, and inline rename. For single-level expandable rows in a grid use Table; for peer rows with no hierarchy use List; for a few stacked open/close sections use Accordion.

## When to use
A hierarchy the user expands and collapses to arbitrary depth — a file/folder explorer, a nested navigation sidebar, a category/org structure, threaded comments. Use terse <Tree.Item> for the common node and compose the slots for rich rows; set `selectionMode` for active-node selection, `checkable` for a checkbox tree, and `Tree.Search` / `filterValue` to find nodes in a deep tree.

## When not to use
Single-level expandable detail rows inside a data grid (use Table's expandable rows); a flat collection of peer rows with no hierarchy (use List); a handful of stacked open/close content sections (use Accordion or Collapsible); a single entity's field:value facts (use DataList); picking from a popover (use Select / Combobox).

## Do / Don't
- ✅ Give the tree an accessible name (label / aria-label) and every node a stable `value`.
- ✅ Drive expansion/selection/checks with the controlled or default key sets and their on…Change callbacks.
- ✅ Use `selectionMode` for the active-node model and the orthogonal `checkable` for a containment checkbox tree (they can coexist).
- ✅ Add `Tree.Search` (or `filterValue`) for find-in-tree, and `loadable`/`loading` to lazy-load a subtree on first expand.
- ✅ Enable `reorderable` + `onMove` with a `Tree.DragHandle` in each row to let users drag nodes to a new parent/position (apply the move to your data in `onMove`).
- ✅ Show `Tree.Skeleton` while the tree loads and an <Empty> (via Tree.Empty) when it's cleared.
- ❌ Don't wrap a whole <Tree.Item> in another component (e.g. a ContextMenu trigger) — it hides the node from the tree model; compose inside the item instead.
- ❌ Don't put `asChild` directly on Tree.Label under a Radix trigger — it clobbers the label's data-slot (breaking type-ahead/highlight); wrap a plain element within the label.
- ❌ Don't reach for Tree for a flat list, a data grid, or a couple of collapsible sections — use List / Table / Accordion.
- ❌ Don't rely on colour alone for checkbox state — the tri-state Checkbox carries aria-checked (incl. mixed).

## Guidelines
**Give every node a stable `value`** — it keys expansion, selection, and checks. Drive state with the controlled/uncontrolled pairs (`expandedKeys`/`defaultExpandedKeys`, `selectedKeys`, `checkedKeys`) and their `on…Change` callbacks.

**Choose the interaction model deliberately.** `selectionMode` is the active-node model (single = one highlighted node, multiple = range/⌘A); `checkable` is the orthogonal checkbox model (containment cascade by default, `cascade={false}` for independent flags). They can coexist as two independent state sets.

**Lean on the built-in depth.** `Tree.Search` (or `filterValue`) filters and auto-reveals; `revealKey` scrolls a deep node into view; `loadable`/`loading` load a subtree on first expand; `editable`/`onRename` rename in place; `reorderable` + `onMove` + a `Tree.DragHandle` in each row add drag-reparent (pointer + keyboard, 3-way drop zones, cycle-safe). Virtualization and a data-driven `items` API stay recipes with a windowing library, never built-in props.

**Keep it accessible.** Name the tree; don't strip the roving model or the focus ring; convey state with the checkbox/aria, not colour alone.

## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `checkedStrategy` | `"all" \| "leaves" \| "parents"` | `all` | no | What `onCheckedChange` emits: everything checked, only topmost parents, or only leaves. Internal state is always leaves; this shapes the callback. |
| `selectionMode` | `"multiple" \| "none" \| "single"` | `none` | no | Selection model — sets `aria-selected` on the active node(s). |
| `size` | `"lg" \| "md" \| "sm"` | `md` | no | Row height / type ladder. |
| `cascade` | `boolean` | — | no | Parent↔child check conduction. `false` = independent checks (checkStrictly). |
| `checkable` | `boolean` | — | no | Render a checkbox per node (independent of `selectionMode`). |
| `checkedKeys` | `string[]` | — | no | Controlled checked keys (parents included when fully checked). |
| `defaultCheckedKeys` | `string[]` | — | no | Uncontrolled initial checks. |
| `defaultExpandedKeys` | `string[]` | — | no | Uncontrolled initial expansion. |
| `defaultFilterValue` | `string` | — | no | Uncontrolled initial filter query (drive it with `<Tree.Search>`). |
| `defaultSelectedKeys` | `string[]` | — | no | Uncontrolled initial selection. |
| `density` | `Density` | — | no | Local density override; omit to inherit the ambient `[data-density]`. |
| `disabledKeys` | `string[]` | — | no | Keys that cannot be selected/checked/focused. |
| `expandedKeys` | `string[]` | — | no | Controlled expanded keys. |
| `filterValue` | `string` | — | no | Controlled filter query — hides non-matches, auto-reveals matching branches. |
| `guides` | `boolean` | — | no | Draw vertical indent guide lines down each level. |
| `label` | `React.ReactNode` | — | no | Convenience accessible name for the tree. |
| `onCheckedChange` | `(keys: string[]) => void` | — | no | Called with the next checked set (leaves + fully-checked parents). |
| `onExpandedChange` | `(keys: string[]) => void` | — | no | Called with the next expanded set whenever it changes. |
| `onFilterChange` | `(query: string) => void` | — | no | Called with the next filter query whenever it changes. |
| `onMove` | `(value: string, target: { parent: string \| null; index: number; }) => void` | — | no | Fires when a node is dropped onto a new parent/position. You move your data: remove `value` from its old spot and insert it into `parent`'s children at `index` (a null `parent` means the tree root). Cycles are pre-filtered out. |
| `onSelectionChange` | `(keys: string[]) => void` | — | no | Called with the next selection whenever it changes. |
| `reorderable` | `boolean` | — | no | Enable drag-reparent (needs a `<Tree.DragHandle>` in each node's row). |
| `revealKey` | `string` | — | no | Reveal a node: expand its ancestors, then focus + scroll it into view. |
| `selectedKeys` | `string[]` | — | no | Controlled selected keys (each `Tree.Item` needs a `value`). |
| `selectionFollowsFocus` | `boolean` | — | no | In `single` mode, move selection as focus moves (default false). |

_Plus 279 inherited native `<ul>` attributes._

### `Tree.DragHandle` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | — | no | Accessible name for the icon-only handle. |

_Plus 290 inherited native HTML attributes._

### `Tree.Item` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `actions` | `React.ReactNode` | — | no | Terse mode: trailing focusable controls (kept above the row). |
| `disabled` | `boolean` | — | no | Inert, non-selectable, non-checkable, skipped by nav + cascade. |
| `editable` | `boolean` | — | no | Allow inline rename (F2 / double-click the label). Requires a string `label`. |
| `icon` | `React.ReactNode` | — | no | Terse mode: the leading icon (open/closed-aware via context). |
| `label` | `React.ReactNode` | — | no | Terse mode: the node label (also the primary click / activation target). |
| `loadable` | `boolean` | — | no | Marks a parent whose children load on demand — shows a chevron with no items yet. |
| `loading` | `boolean` | — | no | Children are loading — swaps the chevron for a spinner. |
| `onActivate` | `(event: React.SyntheticEvent) => void` | — | no | Fired when the row is activated (Enter / click). |
| `onRename` | `(nextLabel: string) => void` | — | no | Called with the committed label when an inline rename is confirmed. |
| `trailing` | `React.ReactNode` | — | no | Terse mode: inert trailing metadata (count / badge). |
| `value` | `string` | — | yes | Stable key — required to participate in expansion / selection / checks. |

_Plus 277 inherited native HTML attributes._

### `Tree.Label` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | no | Render as the child element (e.g. a link or heading), merging props. |

_Plus 280 inherited native HTML attributes._

### `Tree.Skeleton` props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `icon` | `boolean` | — | no | Show a leading icon placeholder. |
| `rows` | `number` | — | no | How many placeholder rows to render (default 5). |
| `size` | `TreeSize` | — | no |  |

_Plus 280 inherited native HTML attributes._

## Variants
- **size** (default `md`): `sm`, `md`, `lg`
- **selectionMode** (default `none`): `none`, `single`, `multiple`
- **checkedStrategy** (default `all`): `all`, `parents`, `leaves`

## Anatomy
- `tree`: The tree — a <ul role=tree> carrying size/density/selection-mode data-attrs and the single keyboard handler (roving tabindex + APG model). Named via label / aria-label / aria-labelledby.
- `tree-label-heading`: Optional convenience heading rendered above the tree (when `label` is set).
- `tree-row`: The horizontal content cell inside each node (toggle · check · icon · label · trailing · actions). Hosts padding, min-height, the hover/selected fill, and the row-wide focus ring driven by the treeitem.
- `tree-toggle`: The expand/collapse chevron on a parent node — a decorative <button tabindex=-1> (aria-hidden; expansion is announced via the treeitem's aria-expanded and driven by the keyboard). A fixed spacer (tree-toggle-spacer) aligns leaves; a Spinner (tree-toggle-spinner) replaces it while a `loading` node fetches.
- `tree-check`: The auto-rendered per-node Checkbox gutter (in `checkable` mode) — tabindex=-1, tri-state (aria-checked mixed) under cascade.
- `tree-match`: The highlighted <mark> wrapping the matched substring of a string label while a filter query is active.
- `tree-rename`: The in-place rename <input> shown while an `editable` node is being renamed — its data-slot keeps the tree keyboard hands-off.
- `tree-drop-indicator`: The insertion line drawn at a node's before/after drop edge during a `reorderable` drag (an `inside` drop highlights the row + ring instead). Reflected via the row's data-drop-zone.

**Parts**
- `Tree.DragHandle` (`tree-drag-handle`): The grip that reparents a node when the Tree is `reorderable` — a real <button> with an accessible name. Only the handle starts a drag, so the node keeps its role=treeitem semantics (dragging the whole row would break the tree a11y model). Renders nothing when the tree isn't reorderable. Pointer drag comes from the sortable engine; the keyboard model (pick up · arrows move · right nests · left outdents · Enter drops · Escape cancels) is the tree's own.
- `Tree.Item` (`tree-item`) · required: One node — a <li role=treeitem> carrying aria-level/setsize/posinset, aria-expanded (parents), aria-selected (selection modes), and the roving tabindex. Dual-mode: terse (label/icon/trailing/actions) or composed children. Nested <Tree.Item>s become its role=group. Props: `value` (key), `disabled`, `loadable`/`loading` (async), `editable`/`onRename` (rename), `onActivate`. Reflects data-level/expanded/selected/checked/disabled/editable/state.
- `Tree.Group` (`tree-group`): The <ul role=group> wrapping a node's child items — auto-rendered by Tree.Item when it has nested items (also exported for explicit composition). Carries the per-level indent and, with `guides`, the vertical guide line.
- `Tree.Icon` (`tree-icon`): The leading icon; reflects the node's open state via data-expanded (open/closed-aware folder icons).
- `Tree.Label` (`tree-label`): The node's primary text. `asChild` swaps in an <a>/<button> for a navigational tree; truncates; hosts the match highlight.
- `Tree.Trailing` (`tree-trailing`): Inert trailing metadata (a count / badge) — pushed to the row's end, not a tab stop.
- `Tree.Actions` (`tree-actions`): Trailing focusable controls (buttons / overflow menu) with their own tab stops; revealed on row hover/focus.
- `Tree.Search` (`tree-search`): A search <input> that drives the tree's filter-to-reveal. Placed above the tree content (hoisted out of the <ul>); matches auto-expand their ancestors and highlight in place.
- `Tree.Empty` (`tree-empty`): An empty-state slot — drop a garn <Empty> inside; a full-width tree row.
- `Tree.Skeleton` (`tree-skeleton`): A loading preset — indented rows of chevron + icon + label placeholders in the node's geometry, hidden from AT.

## Accessibility
- **Role:** tree
- **Space / Enter:** On a Tree.DragHandle: pick the node up (reorderable), then drop it at the chosen position.
- **ArrowUp / ArrowDown:** While dragging a node: move the drop target to the previous / next visible node.
- **ArrowRight:** While dragging: nest the node inside the current target.
- **ArrowLeft:** While dragging: outdent — move the target up to the parent level.
- **Escape:** Cancel an in-progress node drag and restore.
- **WCAG:** 1.3.1 Info and Relationships (A); 1.4.1 Use of Color (A); 2.1.1 Keyboard (A); 2.4.7 Focus Visible (AA); 4.1.2 Name, Role, Value (A)
- The tree is a <ul role=tree> of <li role=treeitem>; a node's children are wrapped in a <ul role=group>. Each treeitem carries aria-level, aria-setsize, and aria-posinset computed from its position; parents carry aria-expanded (leaves do not).
- Roving tabindex — exactly ONE node is tabbable (tabindex=0) at a time (the last-focused node, else the first enabled visible node); all others are -1. Tab enters/leaves the whole tree as a single stop.
- Keyboard (APG Tree View): Up/Down move through visible nodes; Right expands a collapsed parent then descends; Left collapses an open parent then ascends to the parent; Home/End jump to the first/last visible node; type-ahead focuses the next node whose label matches; `*` expands every sibling parent at the current level.
- Selection: `selectionMode="single"` sets aria-selected on one node (optionally following focus); `selectionMode="multiple"` sets aria-multiselectable on the tree and aria-selected per node, with Space/click toggle, Shift+Arrow / Shift+Click range extension, and ⌘/Ctrl+A select-all-visible.
- `checkable` renders a real Checkbox per node (tabindex=-1, operated by Space or pointer). Under `cascade` (default), checking a parent conducts to all enabled descendants and a parent shows aria-checked=mixed when only some descendants are checked; conduction stops at disabled nodes. `cascade={false}` (checkStrictly) makes checks independent.
- The chevron toggle is decorative (aria-hidden, tabindex=-1) — expansion is announced via the treeitem's aria-expanded and driven by the keyboard, so the toggle never becomes a second tab stop. `Tree.Actions` keep their own tab stops within the active node.
- Filter-to-reveal hides non-matching nodes, force-expands the ancestors of matches, and highlights the matched substring; roving/keyboard operate over the filtered-visible set. Inline rename swaps the label for an input whose data-slot keeps the tree keyboard hands-off (Enter/blur commit, Escape cancels). Give the tree an accessible name via `label`, `aria-label`, or `aria-labelledby` (dev-warns if missing).
- Drag-reparent (`reorderable`) drags via a real <button> `Tree.DragHandle` (accessible name required), so the node keeps its role=treeitem — a role=button on the row would break the tree model. Fully keyboard-operable: Space/Enter on the handle picks the node up; arrows move the drop target through the visible nodes; Right nests it inside the target, Left outdents it; Space/Enter drops and Escape cancels. Each pick-up/move/drop is announced to a polite live region; a node can never be dropped into its own subtree (cycle-safe).
- **Focus:** A single roving tabindex on the treeitems (active node = 0, others = -1); Arrow keys move focus and the focus ring is drawn on the row from the focused <li>. The chevron and per-node checkbox are tabindex=-1 (operated by keyboard-at-the-treeitem or pointer) so the tree stays one tab stop; Tree.Actions rove with the active node.
- **Contract (warn):** Give the Tree an accessible name via `label`, `aria-label`, or `aria-labelledby`. — _when a Tree has no `label`, `aria-label`, or `aria-labelledby`_

## Tokens
- `rowGap` → `--garn-gap-inline` (air)
- `rowHeight` → `--garn-control-h-md` (identity)
- `rowRadius` → `--garn-radius`
- `motion` → `--garn-motion-fast` (air)
- **Internal (never externalize):** `--tree-indent`

## Related
- **composes** → `utils`
- **composes** → `checkbox` (when an auto-rendered per-node Checkbox drives `checkable` selection with tri-state cascade)
- **composes** → `input` (when Tree.Search renders a search input, and an inline rename swaps the label for an input)
- **composes** → `spinner` (when a `loading` node shows a Spinner in place of its chevron while children load)
- **composes** → `sortable` (when `reorderable` drives drag-reparent through the sortable primitive (pointer activation + auto-scroll) plus the tree's own 3-way projection and indent/outdent keyboard)
- **slotAccepts** → `badge` (when a Tree.Trailing shows a count / status badge)
- **slotAccepts** → `button` (when a Tree.Actions node hosts buttons / an overflow menu)
- **slotAccepts** → `empty` (when an empty tree renders an Empty inside Tree.Empty)
- **pairsWith** → `context-menu` (when a node is given right-click actions — compose the ContextMenu inside the item (never wrap the item))
- **pairsWith** → `inline-edit` (when a richer rename experience than the built-in editable field is needed)
- **pairsWith** → `scroll-area` (when a height-constrained tree gets its own styled scrollbar)
- **alternativeTo** → `table` (when the hierarchy is single-level expandable rows inside a grid of columns)
- **alternativeTo** → `list` (when the collection is flat (peer rows with no parent/child nesting))
- **alternativeTo** → `accordion` (when there are a few stacked open/close content sections, not an arbitrary-depth hierarchy)

## Recipes
- **file-tree** — A file/folder explorer — expand/collapse nodes with open-aware icons. _(use when showing an arbitrary-depth hierarchy the user expands and collapses)_
- **checkbox-tree** — A tree of checkboxes with tri-state parent↔child cascade (a permission / selection tree). _(use when selecting nodes with containment semantics (checking a folder checks its files))_
- **searchable-tree** — A tree with find-in-tree — a query hides non-matches, reveals ancestors, and highlights. _(use when locating a node in a large/deep tree)_
- **reorderable-tree** — A tree where nodes can be dragged to a new parent/position — a grip handle per row, 3-way before/after/inside drop zones, cycle-safe. _(use when letting users restructure a hierarchy by dragging nodes between parents)_

## Gotchas
- **Nodes don't expand/select, or aria-level is missing on some nodes.** — Nested items were wrapped in another component (e.g. a ContextMenu trigger), hiding them from the child-walked tree model. → Keep nested <Tree.Item>s as direct children (Fragments/Tree.Group are fine). To add a per-node context menu, compose the ContextMenu INSIDE the item (trigger on an element within Tree.Label), never around the item.
- **Filter highlight / type-ahead stops working for a node after adding a context menu or link.** — `asChild` was put directly on Tree.Label under a Radix trigger, which clobbers the label's data-slot (spread order). → Keep the real Tree.Label slot and wrap a plain element (e.g. a <span>) inside it as the trigger / link target.
- **Expecting `checkedKeys` and `selectedKeys` to be the same thing.** — `checkable` (checkbox containment) and `selectionMode` (active node) are two independent state models with separate key sets. → Drive them separately — checkedKeys/onCheckedChange for the checkbox tree, selectedKeys/onSelectionChange for the active node; they can be on at once.
- **onCheckedChange returns parent keys you didn't expect (or omits them).** — The default `checkedStrategy="all"` emits leaves + fully-checked parents. → Set `checkedStrategy` to `"leaves"` (only leaves) or `"parents"` (only topmost fully-checked) to shape the payload; internal state stays leaves so it round-trips.
- **Async subtree never loads, or a folder has no chevron until data arrives.** — Tree doesn't fetch — a node with no children and no `loadable` renders as a leaf. → Mark the node `loadable` (shows a chevron), set `loading` while fetching (shows a Spinner), and load its children in `onExpandedChange`; render them when they arrive.
- **Using Tree for single-level expandable rows in a table, or for a flat list.** — Tree is an arbitrary-depth role=tree, not a grid or a flat collection. → Use Table's expandable rows for one level of detail in a grid, and List for a flat collection of peer rows.
- **`reorderable` is on but nodes won't drag (or the label/icon disappears when adding a Tree.DragHandle).** — The drag lives on Tree.DragHandle (not the row), and adding any composed child switches Tree.Item into composed mode — so the terse `label`/`icon` props are ignored. → Put a <Tree.DragHandle> in the node's row, and in that composed node render the content as slots (<Tree.Icon>/<Tree.Label>) rather than the terse `label`/`icon` props. Apply the reparent to your data in `onMove(value, { parent, index })`.

## Examples
- **basic** (canonical): A file tree — terse nodes with folder/file icons, a disabled node, default-expanded branches.
- **selection** (edge-case): Single-select navigation — one active node (aria-selected), selection following focus.
- **checkable** (edge-case): A checkbox tree — tri-state parent↔child cascade with indeterminate parents.
- **sizes** (edge-case): The size ladder — sm · md · lg row geometry.
- **guides-actions** (edge-case): Indent guide lines, trailing badges, and per-node hover actions.
- **filter** (edge-case): Filter-to-reveal — Tree.Search hides non-matches, auto-expands ancestors, highlights.
- **async** (edge-case): Async lazy children — a loadable node shows a spinner then loads its subtree on expand.
- **multi-select** (edge-case): Multi-select — ⌘/Ctrl+A, Shift+Arrow range, PageUp/Down.
- **rename** (edge-case): Inline rename — F2 / double-click swaps the label for an editable field.
- **context-menu** (edge-case): Per-node right-click actions — a ContextMenu composed inside the item.
- **skeleton** (edge-case): A loading preset — indented chevron/icon/label placeholders.
- **empty** (edge-case): An empty state via Tree.Empty composing <Empty>.
- **reorderable** (edge-case): Drag-reparent — a grip handle per node; drag to move nodes between parents (3-way drop zones, cycle-safe), with onMove reshaping nested data.

## Source map

Regions in `tree.tsx` — read a targeted slice, not the whole file. Line ranges are exact as of the last `info:build`.

- `imports` L3–42 (40 lines) — module imports and component overview doc
- `utils` L43–97 (55 lines) — shared aliases and text/highlight/itemsOf helpers
- `model` L98–156 (59 lines) — TreeNode shape and buildModel from JSX
- `reparent-model` L157–216 (60 lines) — drop zones, move resolution, cycle guards
- `context` L217–291 (75 lines) — Tree and TreeItem contexts and hooks
- `selection-cascade` L292–334 (43 lines) — tri-state parent-child check cascade math
- `root-props` L335–395 (61 lines) — TreeProps public API surface
- `reparent` L396–652 (257 lines) — useTreeReparent pointer and keyboard drag engine
- `root` L653–1233 (581 lines) — Tree root: state, filter reveal, keyboard, render
- `item` L1234–1485 (252 lines) — row sizing constants, TreeItemProps, TreeItem component
- `parts` L1486–1595 (110 lines) — Toggle chevron, Check checkbox, Group wrapper
- `rename` L1596–1646 (51 lines) — inline rename input field
- `slots` L1647–1777 (131 lines) — Icon, Label, Trailing, Actions, DragHandle slots
- `presets` L1778–1865 (88 lines) — Search filter input, Empty state, Skeleton
- `exports` L1866–1907 (42 lines) — compound Tree namespace and exports