@misoto22/design 0.3.1 → 0.6.0

package/dist/agent/Command.md

@@ -0,0 +1,93 @@
+# Command
+
+A filterable list of actions — the ⌘K surface.
+
+- Group: Overlays
+- Import: `import { Command } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/command/
+- Related: combobox, dialog
+
+## Accessibility
+
+- The list filters as you type, the highlight moves with the arrow keys, and focus stays in the input. That last part is the ARIA combobox pattern and the part a home-made palette gets wrong.
+
+## Keyboard
+
+- ↑ / ↓ — Moves the highlight. Focus stays in the input, so what you typed stays editable.
+- Enter — Runs the highlighted item.
+- Escape — Closes the palette.
+
+## Command
+
+A filterable list of actions — the ⌘K surface. Built on cmdk rather than on a `Select` or a menu, because the interaction is neither: the list is filtered as you type, the highlighted row moves with the arrow keys while focus STAYS in the input, and Enter runs the highlighted row. That is the ARIA combobox pattern, and it is the part nobody should hand-roll — `aria-activedescendant` moving without focus moving is precisely where a home-made palette stops working with a screen reader.
+
+## CommandInput
+
+The filter field. Carries the search icon and the combobox semantics.
+
+## CommandList
+
+## CommandEmpty
+
+Shown when the filter matches nothing. Say what would match, not "no results".
+
+## CommandFooter
+
+The key-hint strip along the bottom. A palette is a keyboard surface whose keys are invisible: nothing on screen says the arrows move the row or that Enter runs it, and a reader who reaches for the mouse has been failed by the design rather than by themselves.
+
+## CommandHint
+
+One key-and-verb pair inside a `CommandFooter`.
+
+### Props
+
+- `keys` (required) — `string[]`. The keys this hint describes, printed as `Kbd` chips.
+- `children` (required) — `ReactNode`. What they do — a verb, lowercase, no sentence.
+
+Also accepts: `Omit<ComponentProps<'span'>, 'children'>`.
+
+## CommandGroup
+
+## CommandSeparator
+
+A divider between groups. Marked presentational, because ARIA permits a `listbox` to contain only `option` and `group` — and the library renders this as `role="separator"`, which puts a critical `aria-required-children` violation inside every palette that uses one. The grouping is already announced by the groups themselves, so removing the divider from the accessibility tree loses nothing.
+
+## CommandItem
+
+### Props
+
+- `shortcut` — `string`. A shortcut printed at the end of the row.
+- `icon` — `ReactNode`. A leading glyph. Pass the icon element, sized 16. It is what makes a long list scannable — the eye sorts by shape before it reads, and forty identical rows of text defeat that.
+- `meta` — `ReactNode`. A quiet note at the end of the row — what kind of thing this is, or its current state. Not a description: a palette that prints a sentence per row stops being scannable at about six of them.
+
+Also accepts: `ComponentProps<typeof CommandPrimitive.Item>`.
+
+## CommandDialog
+
+The palette in a modal, which is how it is nearly always used. The dialog's own padding is removed: a palette is edge-to-edge, and its input is the first thing focus lands on.
+
+### Props
+
+- `open` (required) — `boolean`.
+- `onOpenChange` (required) — `(open: boolean) => void`.
+- `label` (required) — `string`. Names the palette for assistive tech.
+- `children` (required) — `ReactNode`.
+
+## Examples
+
+```tsx
+<Command label="Command palette">
+  <CommandInput placeholder="Type a command…" />
+  <CommandList>
+    <CommandEmpty>Nothing matches.</CommandEmpty>
+    <CommandGroup heading="Navigate">
+      <CommandItem onSelect={go}>Components</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+<CommandFooter>
+  <CommandHint keys={['↑', '↓']}>navigate</CommandHint>
+  <CommandHint keys={['↵']}>open</CommandHint>
+</CommandFooter>
+```

package/dist/agent/ComposedChart.md

@@ -0,0 +1,57 @@
+# ComposedChart
+
+Bars and lines over one axis — the volume, and the rate it moved at.
+
+- Group: Charts
+- Import: `import { ComposedChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/composed-chart/
+- Related: bar-chart, line-chart
+
+## When to reach for it
+
+Two measures that share a scale. Two that do NOT share one belong in two charts or indexed to a common base: there is no second y-axis here, on purpose.
+
+## Accessibility
+
+- title is required; the rows are also rendered as a visually hidden table.
+- One value axis only. A dual-axis chart lets its author choose where the lines cross, which is the single most misleading thing a chart can do.
+- enableHoverHighlight dims every bar outside the hovered column, driven by the chart’s own tooltip index.
+
+## ComposedChart
+
+Bars and lines over one axis — the shape for "the volume, and the rate it moved at". One axis, always. Two measures at different scales belong in two charts or indexed to a common base; a second y-scale lets the author choose where the lines cross, which is the single most misleading thing a chart can do.
+
+### Props
+
+- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`.
+- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
+- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `chartProps` — `ComponentProps<typeof RechartsComposedChart>`. Escape hatch onto the raw Recharts chart element.
+- `curveType` — `ChartCurveType` default `'linear'`. How the line between two points is interpolated. Every mark inherits it unless it says otherwise.
+- `animationType` — `ChartRevealType` default `'forward'`.
+- `barGap` — `number`.
+- `barCategoryGap` — `number`.
+- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render. Selection dims every other series.
+- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
+- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
+- `loadingBars` — `number`. How many bars the skeleton draws.
+- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.
+
+## Examples
+
+```tsx
+<ComposedChart title="Revenue and profit" config={config} data={data}>
+  <ComposedChart.Grid />
+  <ComposedChart.XAxis dataKey="month" />
+  <ComposedChart.Tooltip />
+  <ComposedChart.Bar dataKey="revenue" variant="duotone" />
+  <ComposedChart.Line dataKey="profit" />
+</ComposedChart>
+```

package/dist/agent/ContextMenu.md

@@ -0,0 +1,59 @@
+# ContextMenu
+
+The menu a right-click opens.
+
+- Group: Overlays
+- Import: `import { ContextMenu } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/context-menu/
+- Related: dropdown-menu
+
+## When to reach for it
+
+Never as the only way to reach an action. Touch users, trackpad users and keyboard users may have no way to open it.
+
+## Keyboard
+
+- Shift / F10 — Opens the menu from the keyboard, where the platform supports it.
+- ↑ / ↓ — Moves between items.
+- Escape — Closes it.
+
+## ContextMenu
+
+Radix ContextMenu root and trigger, as typed passthroughs.
+
+## ContextMenuTrigger
+
+## ContextMenuContent
+
+The menu a right-click opens. Never the only way to reach an action. A context menu is opened by a secondary pointer button or a keyboard's own menu key, and a meaningful share of readers have neither — a touch user, someone on a trackpad they have not configured, anyone driving the page by keyboard alone. Whatever is in here belongs somewhere reachable too: a row's overflow button, a toolbar.
+
+## ContextMenuItem
+
+A row. Highlight follows `data-highlighted`, which covers hover and keyboard.
+
+### Props
+
+- `icon` — `LucideIcon`.
+- `destructive` — `boolean` default `false`.
+
+Also accepts: `ComponentProps<typeof ContextMenuPrimitive.Item>`.
+
+## ContextMenuSeparator
+
+Hairline divider between groups.
+
+## ContextMenuLabel
+
+Mono eyebrow heading for a group.
+
+## Examples
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger asChild><Card>Right-click me</Card></ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem icon={Copy}>Copy</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```

package/dist/agent/DatePicker.md

@@ -0,0 +1,75 @@
+# DatePicker
+
+A date — or a span of them — chosen from a calendar.
+
+- Group: Forms
+- Import: `import { DatePicker } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/date-picker/
+- Related: calendar, field
+
+## When to reach for it
+
+Deliberately not a text input with a calendar attached: parsing a typed date needs a format, and 03/04 is March the fourth in one country and the third of April in the next. When the date is a long way back, the calendar’s month and year are dropdowns.
+
+## Accessibility
+
+- The trigger prints the date in the visitor’s own locale, not a fixed dd/mm/yyyy.
+- DateRangePicker keeps the panel open until both ends are chosen — a range is not a value until it has a second date.
+- The shortcut rail is plain buttons, not a menu: they set the same value the grid beside them sets, so they belong to one control and Tab in the same pass.
+- Presets are computed on click, so “today” means today even on a tab left open overnight.
+
+## Keyboard
+
+- Enter / Space — Opens the calendar.
+- Escape — Closes it without choosing.
+
+## RANGE_PRESETS
+
+The shortcuts a range picker is asked for on nearly every screen it appears on, so they ship rather than being rebuilt per dashboard. Computed on click: a preset list built at render time freezes "today" at whenever the page loaded, which is wrong for anything left open overnight.
+
+## DATE_PRESETS
+
+The single-date equivalent.
+
+## DatePicker
+
+A date, chosen from a calendar. A trigger and a `Calendar` in a `Popover` — not a new component so much as the composition people otherwise assemble slightly differently on every screen. It is deliberately NOT a text input with a calendar attached. A typed date needs parsing, and parsing needs a format, and a format is a locale argument nobody wins. When typing genuinely matters — a birth date, a long way back — the calendar's month and year are dropdowns, which is the same journey without the ambiguity.
+
+### Props
+
+- `value` — `Date`.
+- `defaultValue` — `Date`.
+- `onValueChange` — `(value: Date | undefined) => void`.
+- `label` (required) — `string`. Names the control. Required — the trigger's text is a value, not a label.
+- `placeholder` — `string` default `'Pick a date'`.
+- `disabled` — `boolean` default `false`.
+- `disabledDates` — `ComponentProps<typeof Calendar>['disabled']`. Days the reader may not choose. Passed straight to the calendar.
+- `format` — `(date: Date) => string` default `formatDate`. How the chosen date is printed on the trigger.
+- `presets` — `boolean | DatePreset<Date>[]`. Shortcuts shown beside the grid. Pass `true` for the built-in set, an array for your own, or leave it off for none.
+- `className` — `string`.
+
+## DateRangePicker
+
+A span of dates — a stay, a reporting period, a filter. Two months side by side, because a range that crosses a month boundary is the common case, and paging back and forth to see both ends is what makes a range picker tiring. They stack under `sm`, where two would not fit — the calendar's own `months` class already carries that, so there is nothing to override. The panel stays open until both ends are chosen: a range is not a value until it has a second date, and closing on the first one would mean re-opening to finish.
+
+### Props
+
+- `value` — `DateRange`.
+- `defaultValue` — `DateRange`.
+- `onValueChange` — `(value: DateRange | undefined) => void`.
+- `label` (required) — `string`.
+- `placeholder` — `string` default `'Pick a range'`.
+- `disabled` — `boolean` default `false`.
+- `disabledDates` — `ComponentProps<typeof Calendar>['disabled']`.
+- `months` — `number` default `2`. How many months are shown side by side. Falls back to one under `sm`.
+- `format` — `(date: Date) => string` default `formatDate`.
+- `presets` — `boolean | DatePreset<DateRange>[]` default `true`. Shortcuts shown beside the grid — Last 30 days and its neighbours. `true` for the built-in set, an array for your own. On by default here and off on the single picker, because "last 30 days" is most of what a range picker is ever asked for, while a single date is usually a specific one.
+- `className` — `string`.
+
+## Examples
+
+```tsx
+<Field label="Publish on"><DatePicker label="Publish on" /></Field>
+<DateRangePicker label="Reporting period" />
+```

package/dist/agent/Diagram.md

@@ -0,0 +1,46 @@
+# Diagram
+
+A flow or architecture figure, drawn out of the system’s own parts.
+
+- Group: Display
+- Import: `import { Diagram } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/diagram/
+- Related: card, figure-band
+
+## When to reach for it
+
+A picture of structure, in a page rather than in a terminal. Nesting is containment and an edge is a step between siblings — a diagram that needs arbitrary wiring wants a drawing, not this.
+
+## Accessibility
+
+- A <figure> with role="group", named by its caption, so the whole picture is one thing a reader can skip.
+- Arrows are aria-hidden: assistive tech reads the nodes in document order and has no use for a glyph pointing at the next one.
+- Server-rendered markup, not a canvas — every label is real text a screen reader and a search engine can read.
+
+## Diagram
+
+A flow or architecture diagram, drawn out of the system's own parts. The alternative it replaces is a fenced block of box-drawing characters — `┌──────┬──────┐` — which is a picture rendered in a font chosen for code. It inherits the code block's frame and scrollbar, so a diagram reads as terminal output; it cannot wrap, so on a phone it either overflows or is scaled to nothing; the box edges are text, so a screen reader reads the rules out loud; and none of it responds to the theme. The other alternative is a diagramming library, which is several hundred kilobytes of layout engine, renders after hydration, and draws in its own palette. This is neither: hairline frames on the radius scale, mono labels, the muted step for anything supporting — so a diagram belongs to the page it sits on. It server-renders, because it is markup. NESTING IS CONTAINMENT, which is what most architecture diagrams actually describe: this is inside that, and these two sit beside each other. Edges are for the sequence between siblings, not for arbitrary wiring — a diagram that needs arbitrary wiring is a diagram that wants a drawing, and this will not pretend otherwise. It takes a spec rather than markup, so a fenced ```diagram block in an article and a hand-written figure on a page are one renderer and one look — and a wrong diagram is corrected by editing data.
+
+### Props
+
+- `spec` (required) — `DiagramSpec`.
+- `className` — `string`.
+
+## Examples
+
+```tsx
+<Diagram
+  spec={{
+    caption: 'One request, end to end.',
+    edges: [{ from: 'edge', to: 'app', label: 'HTTPS' }],
+    nodes: [
+      { id: 'edge', label: 'Edge', note: 'CDN' },
+      { id: 'app', label: 'Application', accent: true, children: [
+        { label: 'Router' },
+        { label: 'Handlers' },
+      ] },
+    ],
+  }}
+/>
+```

package/dist/agent/Dialog.md

@@ -0,0 +1,52 @@
+# Dialog
+
+A modal surface: portal, scrim, centred panel.
+
+- Group: Overlays
+- Import: `import { Dialog } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/dialog/
+- Related: dropdown-menu, tooltip
+
+## Accessibility
+
+- Radix owns the focus trap, Escape, the scroll lock and aria-modal.
+- A dialog without a visible heading still renders a hidden title, rather than shipping an unnamed modal.
+
+## Keyboard
+
+- Escape — Closes it, and focus returns to the trigger it came from.
+- Tab — Cycles inside the dialog; focus cannot leave while it is open.
+
+## Dialog
+
+Radix Dialog root + trigger + close, re-exported as typed passthroughs.
+
+## DialogTrigger
+
+## DialogClose
+
+## DialogContent
+
+A modal surface: portal → scrim → centred panel. Radix owns the focus trap, the escape key, the scroll lock and the `aria-modal` wiring — all of which a hand-rolled dialog gets subtly wrong, usually by leaving focus behind in the page underneath. Radix requires a `Dialog.Title` whether or not one is shown, so a dialog without a visible heading still renders a hidden one rather than logging a warning and shipping an unnamed modal.
+
+### Props
+
+- `title` — `ReactNode`. Heading text. When omitted, a visually-hidden title is rendered for a11y.
+- `description` — `ReactNode`. Sub-heading under the title.
+- `className` — `string`.
+- `showClose` — `boolean` default `true`. Show the top-right close control (default true).
+- `hideTitle` — `boolean` default `false`. Keeps the title for assistive tech and hides it visually. For a surface whose purpose is obvious to anyone who can see it — a command palette, a media lightbox — where a printed heading would be furniture. The title itself is never optional: Radix requires one, and a modal with no accessible name drops a screen reader into an unnamed region.
+
+Also accepts: `Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title' | 'className'>`.
+
+## Examples
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild><Button>Delete</Button></DialogTrigger>
+  <DialogContent title="Delete file" description="This cannot be undone.">
+    <DialogClose asChild><Button variant="secondary">Cancel</Button></DialogClose>
+  </DialogContent>
+</Dialog>
+```

package/dist/agent/DropdownMenu.md

@@ -0,0 +1,70 @@
+# DropdownMenu
+
+A menu of actions.
+
+- Group: Overlays
+- Import: `import { DropdownMenu } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/dropdown-menu/
+- Related: dialog, select
+
+## When to reach for it
+
+Actions. Items that navigate belong in a nav; items that set a value are a Select or a RadioGroup.
+
+## Accessibility
+
+- Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.
+- Highlight is driven by data-highlighted, which covers hover AND keyboard focus — styling :hover alone leaves the keyboard user unable to see where they are.
+
+## Keyboard
+
+- Enter / Space / ↓ — Opens the menu and lands on the first item.
+- ↑ / ↓ — Moves between items.
+- a–z — Jumps to the next item starting with that letter.
+- Escape — Closes the menu and returns focus to the trigger.
+
+## DropdownMenu
+
+Radix DropdownMenu root + trigger, re-exported as typed passthroughs.
+
+## DropdownMenuTrigger
+
+## DropdownMenuContent
+
+A menu surface. A menu is a list of ACTIONS. If the items navigate somewhere, they belong in a nav; if they set a value, that is a `Select` or a `RadioGroup` — Radix has menu variants for both, and a plain item pretending to be a choice loses the checked state a screen reader needs.
+
+Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Content>`.
+
+## DropdownMenuItem
+
+A menu row. Highlight is driven by Radix's `data-highlighted`, which covers both pointer hover and keyboard focus — styling `:hover` alone leaves the keyboard user unable to see where they are.
+
+### Props
+
+- `icon` — `LucideIcon`. Optional leading icon, rendered before the label.
+- `destructive` — `boolean` default `false`. Paints the row as destructive. Use for delete, revoke, disconnect.
+
+Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Item>`.
+
+## DropdownMenuSeparator
+
+Hairline divider between menu groups.
+
+## DropdownMenuLabel
+
+Mono eyebrow heading for a group of items.
+
+## Examples
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild><Button variant="secondary">Menu</Button></DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuLabel>Account</DropdownMenuLabel>
+    <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem icon={LogOut}>Sign out</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```

package/dist/agent/EmptyState.md

@@ -0,0 +1,37 @@
+# EmptyState
+
+A collection with nothing in it — yet.
+
+- Group: Feedback
+- Import: `import { EmptyState } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/empty-state/
+- Related: error-state, skeleton
+
+## When to reach for it
+
+Nothing went wrong. The copy says what to do, not what failed.
+
+## EmptyState
+
+A collection with nothing in it — yet. Distinct from `ErrorState`: nothing went wrong here, so the copy says what to do rather than what failed. The two are different components because the shared temptation — one component with a `variant` — produces error pages that read like empty folders.
+
+### Props
+
+- `icon` — `LucideIcon`. Optional lucide icon, shown muted inside a quiet circle.
+- `title` (required) — `ReactNode`.
+- `description` — `ReactNode`.
+- `action` — `ReactNode`. The one thing to do next. An empty state without an action is a dead end.
+
+Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.
+
+## Examples
+
+```tsx
+<EmptyState
+  icon={Inbox}
+  title="No projects yet"
+  description="Create your first project to get started."
+  action={<Button>New project</Button>}
+/>
+```

package/dist/agent/ErrorState.md

@@ -0,0 +1,41 @@
+# ErrorState
+
+A page that could not be shown.
+
+- Group: Feedback
+- Import: `import { ErrorState } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/error-state/
+- Related: empty-state, alert
+
+## Accessibility
+
+- The big status code is aria-hidden; the heading immediately after says the same thing in words.
+
+## ERROR_ACTION_CLASS
+
+The recovery affordance's look, exported so every error page offers the same one rather than each inventing a link style.
+
+## ErrorState
+
+A page that could not be shown. The code is set at the top of the type ladder and marked `aria-hidden` — read aloud, "404" before the sentence explaining it is noise, and the heading immediately after says the same thing in words.
+
+### Props
+
+- `code` (required) — `ReactNode`. The status, set large — "404", "500". Decorative; the heading carries the meaning.
+- `heading` (required) — `ReactNode`.
+- `message` (required) — `ReactNode`.
+- `action` (required) — `ReactNode`. The way back. Render it with .
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+<ErrorState
+  code="404"
+  heading="Page not found"
+  message="The page you're looking for has moved, or never existed."
+  action={<a href="/" className={ERROR_ACTION_CLASS}>Back home</a>}
+/>
+```

package/dist/agent/Facet.md

@@ -0,0 +1,82 @@
+# Facet
+
+The same chart once per group, on one shared scale.
+
+- Group: Charts
+- Import: `import { Facet } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/facet/
+- Related: line-chart, sparkline
+
+## When to reach for it
+
+Eight series overplot into a hairball in one frame. Two or three series that genuinely need comparing point-for-point still belong in one chart.
+
+## Accessibility
+
+- The shared domain is the default and the whole point: on independent scales a group peaking at 40 and one peaking at 4,000 draw the same shape, and the comparison the reader came for is not merely lost but inverted.
+- Every panel is a figure with its own accessible name, so a screen reader walks eight named charts rather than one unnamed grid.
+- Panels beyond max fold into a stated overflow rather than being dropped, and the count is printed — a grid silently missing four groups is not something a reader can detect.
+- Panel order is a choice the call site makes explicitly through sort, because reading order is what a reader takes as ranking.
+
+## Facet
+
+The same chart repeated once per group, on one shared scale — small multiples. The answer to the question a multi-series chart stops being able to answer at around five series: eight lines in one plot is a hairball, and the reader spends their attention untangling strands instead of reading them. Splitting the same lines across eight small plots costs the direct overlay comparison and buys back every individual shape, which is almost always the better trade — this is Tufte's small multiple, and Observable Plot and Vega-Lite both treat it as a first-class operation for the same reason. Reach for a multi-series `<LineChart>` or `<AreaChart>` instead when the series really do have to be read AGAINST each other — crossovers, gaps, shares of one total — and when there are few enough of them to tell apart. Reach for this when each group has its own shape worth seeing, when the groups are many, or when the reader's question is "which of these is different". What it gets right that a hand-rolled `data.map()` does not: the panels share one domain by default. On independent scales every panel fills its own plot, so a group peaking at 40 and a group peaking at 4,000 come out the same shape — the comparison is not merely lost, it is inverted, and nothing on screen says so. `panel.domain` is that shared scale; the render function has to pass it to the panel's value axis. It also caps the grid, folds or counts the tail, and prints one legend and one axis label instead of twelve.
+
+### Props
+
+- `title` (required) — `string`. What the whole grid shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the grid instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `data` (required) — `TRow[]`. Every row, across every group. The split happens here, not at the call site.
+- `by` (required) — `keyof TRow & string`. The row field the data is split on. One panel per distinct value.
+- `value` (required) — `(keyof TRow & string) | (keyof TRow & string)[]`. The row field, or fields, holding the numbers. This is what the shared domain is measured over and what a statistical sort reads, so it has to name every series a panel draws — a panel that plots a field this does not mention can still overflow its own axis.
+- `xDataKey` — `keyof TRow & string`. The shared category field — the x axis every panel has in common. Feeds the hidden table view, and is what lets `overflow="fold"` add the tail up at each category instead of concatenating it.
+- `scales` — `FacetScales` default `'shared'`. Whether every panel is drawn against one domain or against its own. `"shared"` — the default, and the entire reason this component exists. On independent scales every panel fills its own plot, so a group peaking at 40 and a group peaking at 4,000 come out the same shape, and the comparison the reader opened the grid to make is not merely hard but actively wrong. The shared domain is computed across all the panels that survive the cap and handed to each one as `panel.domain`; a panel that does not pass it to its value axis has opted back into the broken version. `"independent"` is the escape hatch for the case where the panels are not comparable — different units, different orders of magnitude that carry no relation — and where each panel's own shape is the only reading. It is never the safe answer, which is why it is not the default.
+- `domain` — `[number, number]`. Pins the domain outright, ignoring the data and `scales` alike.
+- `includeZero` — `boolean` default `true`. Pulls the shared domain out to include zero. On by default, and the same default Recharts applies on its own: bars and areas read against a truncated baseline overstate every difference in the grid, and a grid exists to be compared. Turn it off when the values live far from zero and the differences between them ARE the reading — temperatures, latencies, ratings out of five.
+- `nice` — `boolean` default `true`. Rounds the domain out so the panels' ticks land on numbers a reader recognises. Off, a shared domain of `[0, 314]` gives ticks at 78.5.
+- `sort` — `FacetSort<TRow>` default `'max'`. The panel order. Defaults to the largest peak first, because that is what makes a grid readable: eye order becomes rank order, and "which of these is the problem" is answered by position before a single axis is read. `"name"` for a grid a reader will look things up in, an explicit array of names for an order the data does not carry — stages, weekdays, severities — and a comparator over `{ name, rows, stats }` for anything else.
+- `order` — `'asc' | 'desc'`. The sort direction. Omit and it follows the sort: A→Z for a name or an explicit list, biggest first for a statistic.
+- `limit` — `number | false` default `12`. How many panels are drawn before the rest are dealt with. Twelve by default rather than unlimited, because the failure this prevents is silent: a `by` field with forty values renders forty plots, each one roughly a postage stamp, and nothing on the page says the grid stopped being readable. `false` lifts the cap when the call site has genuinely decided to draw them all.
+- `overflow` — `FacetOverflow` default `'note'`. What happens to the groups past the cap. `"note"` — the default — draws the top N and prints a line under the grid saying how many are missing. `"fold"` adds one more panel holding the tail summed at each category, the same bargain `BarList`'s "Other" row makes: the total stays true, and one panel absorbs the long tail. Either way a capped grid says so; nothing is dropped in silence.
+- `otherLabel` — `string` default `'Other'`. What the folded panel is called.
+- `overflowNote` — `(info: FacetOverflowInfo) => ReactNode` default `defaultOverflowNote`. Writes the line under a capped grid. The default sentence is English; this is where a translated call site replaces it.
+- `columns` — `'auto' | number` default `'auto'`. How many columns the grid holds at its widest. `"auto"` — the default — fits as many panels as `minPanelWidth` allows and reflows on its own, which is the behaviour a card, a sidebar and a full-width page all need from the same call site. A number caps the count without pinning it: the grid still drops to fewer columns when the container is narrow, rather than shrinking twelve plots to nothing.
+- `minPanelWidth` — `number` default `MIN_PANEL_PX`. How narrow a panel may get before the grid drops a column, in pixels.
+- `legend` — `ReactNode`. One key for the whole grid, printed above it. A legend inside every panel is the same three swatches repeated twelve times, which is ink spent restating what the reader learned from the first panel. Put `<LineChart.Legend>` in one panel and this is unnecessary; put it here and take it out of the panels.
+- `yLabel` — `ReactNode`. The value axis's name, printed once above the grid instead of per panel.
+- `xLabel` — `ReactNode`. The category axis's name, printed once under the grid.
+- `showPanelNames` — `boolean` default `true`. Prints each panel's group name above its plot. On by default. Turning it off only hides the name — it stays in the accessibility tree, because a grid whose panels a screen reader cannot tell apart is a grid with one figure and twelve anonymous plots in it.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view of every row. Worth setting when the panels' own charts already ship theirs — each chart in the package renders its rows as a table too, so a twelve-panel grid can otherwise put thirteen tables in the accessibility tree.
+- `empty` — `ChartEmptyProps`. What the grid shows when the data yields no groups at all. No `false` escape hatch, unlike a single chart's: an empty pair of axes is at least a chart, but an empty grid is nothing — there is no reading for the absence to be.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `children` (required) — `(panel: FacetPanel<TRow>) => ReactNode`. One panel, called once per group. Hand `panel.domain` to the panel chart's value axis. That single line is what the component is for; without it the panels are on independent scales and the grid is decorative.
+
+## Examples
+
+```tsx
+<Facet title="Visitors by channel" data={rows} by="channel" value="visitors" xDataKey="month">
+  {(panel) => (
+    <LineChart title={`${panel.name} visitors`} config={config} data={panel.rows}>
+      <LineChart.XAxis dataKey="month" />
+      <LineChart.YAxis domain={panel.domain} />
+      <LineChart.Line dataKey="visitors" />
+    </LineChart>
+  )}
+</Facet>
+// Biggest first, six panels, the rest summed into one — and the grid says so.
+<Facet
+  title="Requests by endpoint"
+  data={rows}
+  by="endpoint"
+  value="requests"
+  xDataKey="hour"
+  sort="sum"
+  limit={6}
+  overflow="fold"
+  columns={3}
+>
+  {(panel) => <MiniBars rows={panel.rows} domain={panel.domain} />}
+</Facet>
+```