@misoto22/design 0.3.1 → 0.6.0

package/dist/agent/Popover.md

@@ -0,0 +1,57 @@
+# Popover
+
+A panel anchored to a control, holding content you can interact with.
+
+- Group: Overlays
+- Import: `import { Popover } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/popover/
+- Related: tooltip, dropdown-menu
+
+## When to reach for it
+
+Anything with a link, a field or a button in it. A tooltip describes and cannot be entered — put a control inside one and it becomes unreachable.
+
+## 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.
+- label is required: a popover is a dialog, and an unnamed one announces nothing.
+- Its contents Tab like the rest of the page, unlike a menu’s arrow-key list.
+
+## Keyboard
+
+- Enter / Space — Opens it.
+- Tab — Moves through its contents like the rest of the page.
+- Escape — Closes it and returns focus to the trigger.
+
+## Popover
+
+Radix Popover root, trigger, anchor and close, as typed passthroughs.
+
+## PopoverTrigger
+
+## PopoverAnchor
+
+## PopoverClose
+
+## PopoverContent
+
+A panel anchored to a control, holding content the reader can interact with. The line against `Tooltip` is not visual, it is behavioural: a tooltip describes and cannot be entered; a popover holds things you tab to. Anything with a link, a field or a button in it is a popover, and putting that inside a tooltip makes it unreachable — the tooltip closes as soon as focus tries to move into it. Against `DropdownMenu`: a menu is a list of actions with menu semantics and arrow-key navigation. A popover is free-form, and its contents Tab like the rest of the page.
+
+### Props
+
+- `label` (required) — `string`. Names the panel for assistive tech. Required — a popover is a dialog.
+- `showClose` — `boolean` default `false`. Show the top-end close control.
+
+Also accepts: `ComponentProps<typeof PopoverPrimitive.Content>`.
+
+## Examples
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild><Button variant="secondary">Filters</Button></PopoverTrigger>
+  <PopoverContent label="Filters">
+    <Field label="Status"><Select>…</Select></Field>
+  </PopoverContent>
+</Popover>
+```

package/dist/agent/Progress.md

@@ -0,0 +1,33 @@
+# Progress
+
+A bar that fills, or sweeps when the end is unknown.
+
+- Group: Feedback
+- Import: `import { Progress } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/progress/
+- Related: spinner
+
+## Accessibility
+
+- Omitting value drops aria-valuenow, so a screen reader hears “indeterminate” rather than a number that is a guess.
+- label is required — a bare bar announces nothing.
+
+## Progress
+
+A bar that fills, or sweeps when the end is unknown. Flat: a track in `--stone`, a fill in `--ink`. The White Reset has no gradient and no glow, so the only thing carrying the reading is the boundary between the two.
+
+### Props
+
+- `value` — `number | null` default `null`. 0–100. Omit (or pass `null`) when the duration is genuinely unknown — the bar then sweeps instead of filling, and Radix drops `aria-valuenow` so a screen reader is told "indeterminate" rather than a number that is a guess.
+- `label` (required) — `string`. Names what is progressing. Required: a bare bar announces nothing.
+- `showValue` — `boolean` default `false`. Prints the percentage above the bar. Only meaningful when `value` is set.
+
+Also accepts: `Omit<ComponentProps<typeof ProgressPrimitive.Root>, 'value'>`.
+
+## Examples
+
+```tsx
+<Progress value={62} label="Uploading photos" showValue />
+<Progress label="Indexing" />
+```

package/dist/agent/RadarChart.md

@@ -0,0 +1,54 @@
+# RadarChart
+
+A profile across several named dimensions.
+
+- Group: Charts
+- Import: `import { RadarChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/radar-chart/
+- Related: line-chart, pie-chart
+
+## When to reach for it
+
+Recognising a silhouette. The area a radar encloses depends on the order its spokes happen to be in, so it is the wrong chart for comparing magnitudes.
+
+## Accessibility
+
+- title is required; the rows are also rendered as a visually hidden table.
+- Two or three series at most: filled polygons overlap, and judging areas through two layers of translucency is what a radar is worst at. Past that, variant="lines".
+
+## RadarChart
+
+A profile across several named dimensions — the shape for "what is this thing strong and weak at". It reads a SHAPE, not a set of values: the area a radar encloses depends on the order the spokes happen to be in, so it is the wrong chart for comparing magnitudes and the right one for recognising a silhouette. Two or three series at most.
+
+### 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 RechartsRadarChart>`. Escape hatch onto the raw Recharts chart element.
+- `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.
+- `loadingPoints` — `number`. How many points the skeleton draws.
+- `angleDataKey` — `keyof TData & string`. The row field naming each spoke. Used by the table view.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+
+## Types
+
+- `RadarVariant` = `'filled' | 'lines'`
+
+## Examples
+
+```tsx
+<RadarChart title="Team skills" config={config} data={data} angleDataKey="skill">
+  <RadarChart.PolarGrid />
+  <RadarChart.PolarAngleAxis dataKey="skill" />
+  <RadarChart.Tooltip />
+  <RadarChart.Radar dataKey="current" />
+</RadarChart>
+```

package/dist/agent/RadialChart.md

@@ -0,0 +1,57 @@
+# RadialChart
+
+Values on an arc — a gauge, or a few totals against one scale.
+
+- Group: Charts
+- Import: `import { RadialChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/radial-chart/
+- Related: pie-chart, bar-chart
+
+## When to reach for it
+
+A single value against a fixed total. Past about four bars a BarChart is the honest choice, because a radial bar’s radius is not its value.
+
+## Accessibility
+
+- title is required; pass valueKey and the rows are also rendered as a visually hidden table.
+- Set max or the scale comes from the data and the largest bar always fills the arc — which makes 62% and 98% look identical.
+- showTrack draws the unfilled remainder, which is what makes a gauge readable at all.
+
+## RadialChart
+
+Values on an arc — a gauge, or a small set of totals against one scale. The caveat worth knowing before reaching for it: a radial bar's LENGTH is its value, but its RADIUS is not, so an inner bar and an outer bar of the same value are drawn different lengths. That makes it a poor comparison and a good single-value gauge; past about four bars, a `<BarChart>` is the honest choice.
+
+### Props
+
+- `config` (required) — `ChartConfig`. Bar names → their label and paint. Keys must match the `nameKey` values.
+- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
+- `nameKey` (required) — `keyof TData & string`. The row field naming each bar.
+- `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 RechartsRadialBarChart>`. Escape hatch onto the raw Recharts chart element.
+- `variant` — `RadialVariant` default `'full'`. The arc shape — a full ring, or the half circle a gauge wants.
+- `max` — `number`. What a full sweep is worth. Without it the scale comes from the data, so the largest bar always fills the arc — which is right for a comparison and wrong for a gauge. Set it (typically 100) whenever a single value has to read against a fixed total, or "62%" and "98%" will look identical.
+- `innerRadius` — `number | string` default `'30%'`. Where the arc starts, from the centre.
+- `outerRadius` — `number | string` default `'100%'`. Where the arc ends.
+- `defaultSelectedBar` — `string | null` default `null`. The bar lit on first render.
+- `onSelectionChange` — `(selection: { name: string; value: number } | 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.
+- `valueKey` — `keyof TData & string`. The row field holding each bar's number. Used by the table view.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+
+## Types
+
+- `RadialVariant` = `'full' | 'semi'`
+
+## Examples
+
+```tsx
+<RadialChart title="Storage used" config={config} data={data} nameKey="tier" max={100}>
+  <RadialChart.RadialBar dataKey="used" />
+  <RadialChart.Tooltip />
+</RadialChart>
+```

package/dist/agent/RadioGroup.md

@@ -0,0 +1,44 @@
+# RadioGroup
+
+A set of mutually exclusive choices.
+
+- Group: Forms
+- Import: `import { RadioGroup } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/radio-group/
+- Related: checkbox, select
+
+## Accessibility
+
+- One tab stop for the whole group; the arrow keys move between options, per the ARIA radiogroup pattern.
+- The label is inside the <label>, so the whole row is the click target.
+
+## Keyboard
+
+- Tab — Moves into the group, and out of it — the whole group is one stop.
+- ↑ / ↓ / ← / → — Moves between options AND selects as it goes.
+
+## RadioGroup
+
+A set of mutually exclusive choices. Radix owns the roving tabindex, so the whole group is ONE tab stop and the arrow keys move between options — which is what the ARIA radiogroup pattern requires and what a stack of hand-rolled `<input type="radio">` wrappers usually gets wrong.
+
+Also accepts: `ComponentProps<typeof RadioGroupPrimitive.Root>`.
+
+## RadioGroupItem
+
+One option, and its label, as a single click target. The `<label>` wraps both, so the whole row is clickable — a bare 18px circle is below every pointer-target guideline and is miserable on a phone. It is also what gives the control its accessible name: remove the wrapper and the radio has no name at all. Selection follows focus, which is the half of the pattern that makes a radiogroup usable from the keyboard: moving to an option chooses it, so nobody has to press an extra key to commit. That is implemented here rather than inherited, because the upstream primitive gates it on a flag cleared by `keyup` and loses the race against its own focus move — see ARROW_GRACE_MS. Re-selecting an already-selected option is a no-op, so this stays correct even where the upstream path does fire.
+
+### Props
+
+- `children` (required) — `ReactNode`. The visible label. Rendered inside the `<label>` that wraps the control.
+
+Also accepts: `Omit<ComponentProps<typeof RadioGroupPrimitive.Item>, 'children'>`.
+
+## Examples
+
+```tsx
+<RadioGroup defaultValue="light" aria-label="Theme">
+  <RadioGroupItem value="light">Light</RadioGroupItem>
+  <RadioGroupItem value="dark">Dark</RadioGroupItem>
+</RadioGroup>
+```

package/dist/agent/SankeyChart.md

@@ -0,0 +1,61 @@
+# SankeyChart
+
+Where a quantity goes as it moves through stages.
+
+- Group: Charts
+- Import: `import { SankeyChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/sankey-chart/
+- Related: bar-chart
+
+## When to reach for it
+
+A funnel, a budget, an energy or traffic breakdown. The only chart here whose data is a graph rather than a table.
+
+## Accessibility
+
+- title is required. The hidden table lists the FLOWS rather than the nodes — a table of node totals would lose every “from → to” the diagram exists to show.
+- Four link variants: gradient reads as flow, source and target attribute a band to one end, solid gives up colour and lets the nodes carry identity.
+
+## SankeyChart
+
+Where a quantity goes as it moves through stages — the shape for a funnel, a budget, an energy or traffic breakdown. The only chart here whose data is a GRAPH rather than a table, so it takes `{ nodes, links }` instead of rows, and the table view lists the flows rather than the nodes.
+
+### Props
+
+- `data` (required) — `SankeyData`. The nodes and the links between them, in Recharts' own shape.
+- `config` (required) — `ChartConfig`. Node names → their label and paint.
+- `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.
+- `sankeyProps` — `Omit<SankeyProps, 'data'>`. Escape hatch onto the raw Recharts Sankey element.
+- `nodeWidth` — `number` default `10`. How wide each node rectangle is, in pixels.
+- `nodePadding` — `number` default `10`. Vertical gap between nodes in the same column, in pixels.
+- `linkCurvature` — `number` default `0.5`. 0 draws straight links, 1 the fullest curve.
+- `iterations` — `number` default `32`. Layout passes. More is tidier and slower.
+- `sort` — `boolean` default `true`. Lets the layout reorder nodes for the fewest crossings.
+- `align` — `'left' | 'justify'` default `'justify'`. How nodes are placed along the flow axis.
+- `verticalAlign` — `'justify' | 'top'` default `'justify'`. How nodes are distributed within a column.
+- `defaultSelectedNode` — `string | null` default `null`. The node lit on first render. Selecting one dims every flow it does not touch.
+- `onSelectionChange` — `(selection: { name: string; value: number } | 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.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+
+## Types
+
+- `SankeyLinkVariant` = `'gradient' | 'solid' | 'source' | 'target'`
+- `SankeyLabelPosition` = `'inside' | 'outside'`
+
+## Examples
+
+```tsx
+<SankeyChart title="Traffic by source and outcome" config={config} data={data}>
+  <SankeyChart.Node radius={2}>
+    <SankeyChart.NodeLabel position="outside" showValues />
+  </SankeyChart.Node>
+  <SankeyChart.Link variant="gradient" />
+  <SankeyChart.Tooltip />
+</SankeyChart>
+```

package/dist/agent/ScatterChart.md

@@ -0,0 +1,54 @@
+# ScatterChart
+
+Two measures against each other, one mark per observation.
+
+- Group: Charts
+- Import: `import { ScatterChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/scatter-chart/
+- Related: line-chart, heatmap
+
+## When to reach for it
+
+Correlation, clustering, outliers — the questions that do not survive being bucketed into a bar. The only chart here whose x axis is a number rather than a category.
+
+## Accessibility
+
+- title is required. The table view is declared rather than inferred: scatter data lives on each series, so there is no single set of rows to read off the root.
+- Shape does the work hue does elsewhere. Two overlapping clouds separate far better by circle-versus-cross than by two steps of grey — and shape survives overprinting, which a lightness step does not.
+- A solid mark carries a surface-coloured ring, so two observations that land on top of each other stay countable.
+- ZAxis maps its measure to a mark’s AREA, not its radius: doubling a radius quadruples the ink, which is the most common way a bubble chart lies.
+
+## ScatterChart
+
+Two measures against each other, one mark per observation — the shape for "is there a relationship here". The only chart in the set whose x axis is a NUMBER rather than a category, which is the whole point: a scatter answers correlation, clustering and outliers, and none of those questions survive being bucketed into a bar. Past three series, shape stops separating them and the answer is small multiples — one chart per series, same axes — rather than a fourth mark.
+
+### Props
+
+- `config` (required) — `ChartConfig`. Series keys → their label and paint. Declaration order is ramp order.
+- `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 RechartsScatterChart>`. Escape hatch onto the raw Recharts chart element.
+- `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.
+- `table` — `ScatterTable | false`. The rows behind the hidden table view, with the fields to print. Scatter data lives on each `<Scatter>` rather than on the root, so unlike every other chart here the table cannot be inferred — it is declared.
+
+## Types
+
+- `ScatterShape` = `'circle' | 'square' | 'triangle' | 'diamond' | 'cross' | 'ring'`
+- `ScatterVariant` = `'solid' | 'outline' | 'gradient'`
+
+## Examples
+
+```tsx
+<ScatterChart title="Load time against bundle size" config={config}>
+  <ScatterChart.Grid />
+  <ScatterChart.XAxis dataKey="kb" name="Bundle" unit=" kB" />
+  <ScatterChart.YAxis dataKey="ms" name="Load" unit=" ms" />
+  <ScatterChart.Tooltip />
+  <ScatterChart.Scatter dataKey="desktop" data={desktop} />
+</ScatterChart>
+```

package/dist/agent/ScrollArea.md

@@ -0,0 +1,40 @@
+# ScrollArea
+
+A box that scrolls, with a scrollbar that looks the same everywhere.
+
+- Group: Surfaces
+- Import: `import { ScrollArea } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/scroll-area/
+- Related: table
+
+## When to reach for it
+
+A bounded panel — a long option list, a log. For page-level or prose scroll the scroll-slim utility is lighter and needs no component.
+
+## Accessibility
+
+- The viewport stays focusable. A scrollable region whose contents are not focusable has nothing to Tab to, so everything past the fold does not exist without a mouse.
+- label is required, because an unnamed keyboard stop announces "group" and nothing else.
+
+## Keyboard
+
+- Tab — Moves focus into the region, which is what makes it scrollable at all without a mouse.
+- ↑ / ↓ / Page Up / Page Down — Scrolls it.
+
+## ScrollArea
+
+A box that scrolls, with a scrollbar that looks the same on every platform. The reason to reach for this over `overflow-auto` is not the scrollbar — it is that Radix keeps the viewport focusable and the bar operable, which a bare overflow container does not. A scrollable region whose contents are not themselves focusable is unreachable by keyboard: there is nothing to Tab to, so everything past the fold does not exist without a mouse. For a page-level or prose scroll, the `scroll-slim` utility is lighter and needs no component. This is for a bounded panel: a long option list, a log, a sidebar that outgrows its column.
+
+### Props
+
+- `label` (required) — `string`. Names the region. Required, and not decoration: a scroll container is a keyboard stop, and an unnamed stop announces "group" and nothing else.
+- `orientation` — `'vertical' | 'horizontal' | 'both'` default `'vertical'`.
+
+Also accepts: `ComponentProps<typeof ScrollAreaPrimitive.Root>`.
+
+## Examples
+
+```tsx
+<ScrollArea label="Deploy log" className="h-48">…</ScrollArea>
+```

package/dist/agent/SearchableMenu.md

@@ -0,0 +1,46 @@
+# SearchableMenu
+
+A menu of actions you can type into.
+
+- Group: Overlays
+- Import: `import { SearchableMenu } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/searchable-menu/
+- Related: dropdown-menu, command, combobox
+
+## When to reach for it
+
+A DropdownMenu past about a dozen rows stops being scannable, and nesting submenus makes it worse. This is the same list with a filter over it. Not a Command palette: that is page-level and modal; this is anchored to a control.
+
+## 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.
+- The rows are options inside a listbox rather than menuitems, because filtering requires it — the highlight moves through aria-activedescendant while focus stays in the input, and a menu cannot do that.
+- The trade is deliberate: a menu that cannot be filtered is worse for the reader than a listbox that runs actions.
+
+## Keyboard
+
+- Enter / Space — Opens the menu.
+- ↑ / ↓ — Moves the highlight while focus stays in the filter.
+- Enter — Runs the highlighted action.
+- Escape — Closes without running anything.
+
+## SearchableMenu
+
+A menu of actions you can type into. The fourth corner of a square the system otherwise had three of, and the distinction is worth stating because reaching for the wrong one is easy: | | few options | many options | |---|---|---| | **sets a value** | `Select` | `Combobox` | | **runs an action** | `DropdownMenu` | `SearchableMenu` | A `DropdownMenu` past about a dozen rows stops being scannable, and the usual response — nesting submenus — makes it worse. This is the same list with a filter over it. Not the same thing as `Command`: that is a page-level palette, usually modal and usually bound to ⌘K. This is anchored to a control, like the menu it replaces. The rows are `option`s inside a listbox rather than `menuitem`s, because that is what the filtering pattern requires — the highlight moves through `aria-activedescendant` while focus stays in the input, and a menu cannot do that. The trade is deliberate: a menu that cannot be filtered is worse for the reader than a listbox that runs actions.
+
+### Props
+
+- `actions` (required) — `MenuAction[]`.
+- `children` (required) — `ReactNode`. The trigger's text.
+- `label` (required) — `string`. Names the menu for assistive tech.
+- `searchPlaceholder` — `string` default `'Filter…'`.
+- `emptyMessage` — `string` default `'Nothing matches.'`.
+- `align` — `'start' | 'center' | 'end'` default `'start'`.
+- `className` — `string`.
+
+## Examples
+
+```tsx
+<SearchableMenu label="Actions" actions={ACTIONS}>Actions</SearchableMenu>
+```

package/dist/agent/Select.md

@@ -0,0 +1,75 @@
+# Select
+
+A choice from a list, styled the whole way down.
+
+- Group: Forms
+- Import: `import { Select } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/select/
+- Related: combobox, native-select, field
+
+## When to reach for it
+
+Up to roughly a dozen options. Past that a Combobox wins, because a list nobody can filter is slower to scan than one you can type into.
+
+## 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.
+- The option list is ours, so it does not change typeface, spacing and selection colour the moment it opens — which is what a native select does.
+- The keyboard contract is the platform's: typeahead, arrows, Home and End, Escape to close without choosing.
+- label is required. The trigger shows a value, and a value is not a name.
+
+## Keyboard
+
+- Enter / Space / ↓ — Opens the list.
+- ↑ / ↓ — Moves between options.
+- a–z — Typeahead — jumps to the next option starting with that letter.
+- Home / End — Jumps to the first or last option.
+- Escape — Closes without choosing.
+
+## SelectRoot
+
+Radix Select root, group and label, as typed passthroughs.
+
+## SelectGroup
+
+## Select
+
+A choice from a list, styled the whole way down. The option list is ours — drawn from the same tokens as everything else, so it does not change typeface, spacing and selection colour the moment it opens. That is the whole reason this replaced the native control as the default: a design system whose most common form control stops being part of the system on click is not a design system, it is a stylesheet for closed states. The keyboard contract is Radix's, which means it is the platform's: typeahead works, the arrows move, Home and End reach the ends, and Escape closes without choosing. That was the one genuine argument for staying native, and it is answered. Past roughly a dozen options, reach for `Combobox` — a list nobody can filter is worse than one they can type into. Where the platform picker is genuinely better — a phone, or a form that must survive without JavaScript — reach for `NativeSelect`.
+
+### Props
+
+- `contentClassName` — `string`. Classes for the option PANEL, not the trigger. `className` styles the trigger, which is the common case. This exists for the uncommon one: a select inside a bounded surface, where the default 18rem of list would cover the thing the reader is choosing for — a year picker over its own calendar, say.
+- `label` (required) — `string`. Names the control. Required — the trigger shows a value, and a value is not a name.
+- `placeholder` — `string` default `'Select…'`.
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `disabled` — `boolean`.
+- `className` — `string`.
+- `children` (required) — `ReactNode`. `SelectItem`s, optionally wrapped in `SelectGroup` with a `SelectLabel`.
+
+Also accepts: `ComponentProps<typeof SelectPrimitive.Root>`.
+
+## SelectItem
+
+One option. The tick marks the chosen one; the fill marks the highlighted one.
+
+Also accepts: `ComponentProps<typeof SelectPrimitive.Item>`.
+
+## SelectLabel
+
+Mono eyebrow heading for a group of options. Must sit inside a `SelectGroup` — Radix throws otherwise, because a heading with no group is a heading for nothing, and assistive tech would announce it as an option.
+
+## SelectSeparator
+
+Hairline divider between groups.
+
+## Examples
+
+```tsx
+<Field label="Region">
+  <Select label="Region" defaultValue="au">
+    <SelectItem value="au">Australia</SelectItem>
+    <SelectItem value="nz">New Zealand</SelectItem>
+  </Select>
+</Field>
+```

package/dist/agent/Separator.md

@@ -0,0 +1,35 @@
+# Separator
+
+A rule, in the three weights a monochrome page needs.
+
+- Group: Display
+- Import: `import { Separator } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/separator/
+
+## When to reach for it
+
+Hairline between rows, edge between blocks, hard under a masthead.
+
+## Accessibility
+
+- role="none" by default. A rule that only groups things visually must not be announced.
+
+## Separator
+
+A rule. In a monochrome system the rule does the work colour would otherwise do, so it has three weights rather than one: hairline between rows, edge between blocks, hard under a masthead. Picking by name keeps a page from drifting into five hand-tuned greys.
+
+### Props
+
+- `orientation` — `'horizontal' | 'vertical'` default `'horizontal'`.
+- `weight` — `'hairline' | 'edge' | 'hard'` default `'hairline'`. `hairline` divides rows inside one block; `edge` divides one block from the next.
+- `decorative` — `boolean` default `true`. A rule that only groups things visually is decoration and must not be announced. Set `false` when the rule genuinely separates two sections a screen reader should hear as distinct.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Examples
+
+```tsx
+<Separator weight="hard" />
+<Separator orientation="vertical" className="h-4" />
+```

package/dist/agent/Sheet.md

@@ -0,0 +1,57 @@
+# Sheet
+
+A panel docked to an edge of the viewport.
+
+- Group: Overlays
+- Import: `import { Sheet } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/sheet/
+- Related: dialog, popover
+
+## When to reach for it
+
+A modal that needs room — a filter panel, a detail view. It IS a Dialog, docked; the sides are named in reading order, so `end` is the right in English and the left in Arabic.
+
+## Accessibility
+
+- Shares Dialog’s focus trap, Escape handling and scroll lock rather than reproducing them — a second focus trap is a second one to get wrong.
+- The title is required, visible or not.
+
+## Keyboard
+
+- Escape — Closes it, and focus returns to the trigger.
+- Tab — Cycles inside the sheet.
+
+## Sheet
+
+Radix Dialog root, trigger and close — a sheet IS a dialog, docked.
+
+## SheetTrigger
+
+## SheetClose
+
+## SheetContent
+
+A panel docked to an edge of the viewport. It is a modal dialog — Radix's, so the focus trap, the escape key, the scroll lock and the `aria-modal` wiring are the same ones `Dialog` gets. The only differences are where it sits and which way it arrives, which is why this shares that implementation rather than reproducing it: a second focus trap is a second focus trap to get wrong. The title is required, visible or not. A modal with no accessible name drops a screen reader into an unnamed region with no way back out.
+
+### Props
+
+- `side` — `SheetSide` default `'end'`. Which edge it is docked to. `end` by default.
+- `title` (required) — `ReactNode`.
+- `description` — `ReactNode`.
+- `hideTitle` — `boolean` default `false`. Hide the title visually while keeping it for assistive tech.
+
+Also accepts: `Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title'>`.
+
+## Types
+
+- `SheetSide` = `'start' | 'end' | 'top' | 'bottom'`
+
+## Examples
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild><Button variant="secondary">Filters</Button></SheetTrigger>
+  <SheetContent title="Filters" description="Narrow the list.">…</SheetContent>
+</Sheet>
+```