@misoto22/folio 0.0.0 → 0.16.0

package/dist/agent/ScatterChart.md

@@ -0,0 +1,80 @@
+# ScatterChart
+
+Two measures against each other, one mark per observation.
+
+- Kind: component
+- Group: Charts
+- Import: `import { ScatterChart } from '@misoto22/folio/charts'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with isLoading and an empty state. Emptiness is read from the declared table rows, for the same reason the table is declared at all: the observations live on each <Scatter>, and the root cannot see them.
+- **Numeric axes** (required) — <ScatterChart.XAxis> and <ScatterChart.YAxis>, both type="number" by default. The only chart in the group whose horizontal axis is a measurement rather than a category.
+- **Clouds** (required) — <ScatterChart.Scatter>, one per series, each carrying its OWN data array rather than reading the root’s. Six mark shapes, and a solid mark takes a 1px --chart-surface ring so two coincident observations stay countable.
+- **Size channel** — <ScatterChart.ZAxis>, range [40, 400] by default. That range is in AREA, not radius: doubling a radius quadruples the ink, which is how a bubble chart usually lies.
+- **Crosshair** — The tooltip’s cursor, a pair of rules rather than one band. A scatter point is located by two coordinates and a single vertical cursor answers half of that.
+- **Declared table** — table is a PROP here, not inferred. Scatter data lives on each series, so there are no rows on the root to read off — and passing nothing ships a figure with no table at all.
+
+## Best practices
+
+### Do
+
+- Declare table. It is the one chart in the group whose hidden table cannot be derived, so omitting it fails silently: the figure renders, is named, and has no numbers behind it.
+- Separate series by shape before anything else. Circle against cross stays legible where two steps of grey do not, and shape survives overprinting and forced colours — where every --series-* token becomes CanvasText and a lightness step is gone.
+- Reach for variant="outline" or shape="ring" on a dense cloud. A hollow mark shows what is under it; a solid one at two thousand points is a silhouette of the densest region and nothing else.
+
+### Don’t
+
+- Do not vary size between series to mean something. size is a flat radius in pixels, so it encodes nothing while looking exactly as if it does; <ScatterChart.ZAxis> is the only path that maps a value to a mark’s area.
+- Past three series shape stops separating them — circle, cross and triangle are distinct, and a fourth glyph is a diamond most readers see as a rotated square. Small multiples on shared axes is the answer, not a fourth mark.
+
+## 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, when the chart keeps its own selection.
+- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
+- `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.
+- `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.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading. Read from the declared `table` rows, for the same reason the table is declared: the observations live on each `<Scatter>`, and the root cannot see them.
+
+## 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,62 @@
+# ScrollArea
+
+A box that scrolls, with a scrollbar that looks the same everywhere.
+
+- Kind: component
+- Group: Surfaces
+- Import: `import { ScrollArea } from '@misoto22/folio'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Root** (required) — The bounded box, and where className lands. It is overflow-hidden and has no size of its own, so the height you give it here is the only thing that decides whether anything scrolls at all.
+- **Viewport** (required) — The element that actually scrolls, and the one carrying role="region", tabIndex 0 and label. Radix hides the platform’s scrollbar on it and sets the axis WITHOUT a bar to overflow: hidden. It is positioned, so an absolutely-positioned descendant travels with the content instead of hanging still over it.
+- **Bar** — One per orientation: an 8px track with a pill thumb at --rule-2, and touch-none — a finger scrolls the content, not the bar. It is drawn only while the pointer is inside the region and fades some 600ms after scrolling stops.
+- **Corner** — The square where two bars meet, which exists only at orientation="both" — the default.
+
+## Best practices
+
+### Do
+
+- Give it a height. With none, the root is as tall as its content, nothing ever overflows, and all the component added to the page was a keyboard stop.
+- Narrow orientation only when clipping the other axis is the thing you meant. Both axes scroll by default, because the axis without a bar is set to overflow: hidden — what is past that edge is not merely unmarked, it is unreachable by every key and every gesture, with the content perfectly well rendered.
+- Pass type="always" when the content ends flush at the boundary: the platform scrollbar is hidden and ours is not drawn until the pointer is inside, so at rest nothing on the screen says the box scrolls.
+
+### Don’t
+
+- Do not build a drag-to-scroll affordance over it — the thumb is deliberately touch-none and the viewport is a real overflow container, so touch dragging, momentum and the wheel are already the platform’s and behave as the reader expects.
+- Do not nest one inside another on the same axis: the inner viewport consumes the wheel until it reaches its own end, so a reader aiming at the outer list moves the inner one instead.
+
+## 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.
+- Both axes scroll unless a caller narrows orientation, so content wider than the box stays reachable rather than being clipped without a bar.
+
+## 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. Both axes scroll unless a caller says otherwise. The old vertical default read as a statement about which bar to draw and was in fact a statement about which half of the content existed: Radix sets the viewport's overflow from the mounted bars, so the axis without one was `hidden` and everything past it was unreachable — silently, and with the content perfectly well rendered.
+
+### 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 `'both'`. Which axes get a bar — and therefore which axes scroll at all. Radix sets the viewport's overflow from the bars that are mounted, so an axis without one is `hidden`: what is past that edge is not merely unmarked, it is unreachable by every key and every gesture. `both` is the default for that reason. Narrow it only when clipping the other axis is the thing you meant.
+
+Also accepts: `ComponentProps<typeof ScrollAreaPrimitive.Root>`.
+
+## Examples
+
+```tsx
+<ScrollArea label="Deploy log" className="h-48">…</ScrollArea>
+```

package/dist/agent/SearchPalette.md

@@ -0,0 +1,51 @@
+# SearchPalette
+
+Search results, actions and a detail view in one accessible modal.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { SearchPalette } from '@misoto22/folio/website'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/search-palette/
+
+## When to reach for it
+
+Pass already-filtered results; the package owns the combobox and focus behavior.
+
+## Best practices
+
+### Do
+
+- Supply localized labels, descriptive links and meaningful image alternatives.
+
+### Don’t
+
+- Do not put service credentials, routing logic or backend models inside presentation components.
+
+## SearchPalette
+
+Search, actions and an optional result detail inside one accessible modal.
+
+### Props
+
+- `open` (required) — `boolean`.
+- `onOpenChange` (required) — `(open: boolean) => void`.
+- `label` (required) — `string`.
+- `inputLabel` (required) — `string`.
+- `placeholder` (required) — `string`.
+- `query` (required) — `string`.
+- `onQueryChange` (required) — `(query: string) => void`.
+- `groups` (required) — `SearchPaletteGroup[]`. Already filtered results; search and data access belong to the consumer.
+- `emptyLabel` (required) — `ReactNode`.
+- `labels` (required) — `{ close: string; navigate: string; select: string; back: string }`.
+- `detail` — `{ label: string; content: ReactNode; onBack: () => void; onSubmit: () => void; submitDisabled?: boolean }`. Optional answer or detail view, with Escape returning to the results.
+- `onContentLinkClick` — `() => void`.
+- `onCloseAutoFocus` — `DialogContentProps['onCloseAutoFocus']`.
+
+## SearchExcerpt
+
+Render query highlights as text, never as consumer-supplied HTML.
+
+### Props
+
+- `segments` (required) — `ReadonlyArray<{ text: string; highlighted: boolean }>`.

package/dist/agent/SearchableMenu.md

@@ -0,0 +1,69 @@
+# SearchableMenu
+
+A menu of actions you can type into.
+
+- Kind: component
+- Group: Overlays
+- Import: `import { SearchableMenu } from '@misoto22/folio'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Trigger** (required) — A pill button built here rather than a Button: --control-h-sm tall, hairline bordered, with a chevron. Its accessible name is label, not the children you passed as its text.
+- **Panel** (required) — A Popover with its padding removed and a flat 16rem width, so the filter and the list run edge to edge inside it. Not modal — this is a Popover, not a Dialog.
+- **Filter** (required) — The Command input. Focus lands here on open and stays there; the highlight moves under it through aria-activedescendant.
+- **Rows** — One per MenuAction, as listbox options. shortcut prints as a Kbd at the end of the row, destructive paints it --danger, and selecting one closes the menu before running onSelect.
+- **Empty state** — emptyMessage, shown when the filter matches nothing. Say what would match rather than “no results”.
+
+## Best practices
+
+### Do
+
+- Give an action keywords for the word a reader reaches for that the label does not print — “download” for Export, “bin” for Delete. The label’s own text is lifted into the filter for you; a label built only from elements prints none, and development warns SEARCHABLE_MENU_LABEL_UNREADABLE rather than shipping a row nothing matches.
+- Make label the trigger’s visible text. It is set as aria-label on the trigger and overrides the children, so a button reading “Status” under a label of “Row actions” is announced as something the reader cannot say aloud (WCAG 2.5.3).
+- Keep actions that share a group next to each other in the array: groups are built by walking the list and extending only the LAST one, so the same group name appearing again after other rows produces a second heading with identical text.
+
+### Don’t
+
+- It is a Popover underneath, so it is not modal: the page behind still scrolls while the filter is open and the panel is re-anchored as it does. A surface that should hold the page still is CommandDialog.
+- className lands on the TRIGGER, not on the panel — the panel is a flat 16rem with no prop that widens it, so a long label wraps to a second line instead of the box growing to take it.
+- The trigger is --control-h-sm — 36px comfortable, 30px under data-density="compact" — which is below the 44px pointer target (WCAG 2.5.5), and it is not the system Button, so variant and size do not reach it.
+
+## 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,102 @@
+# Select
+
+A choice from a list, styled the whole way down.
+
+- Kind: component
+- Group: Forms
+- Import: `import { Select } from '@misoto22/folio'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Trigger** (required) — A <button role="combobox"> on CONTROL_BASE, so it matches the Input beside it exactly. It is named by the label and by its own value together, and carries the chevron that turns over while the panel is open.
+- **Value** — The chosen item’s text, or placeholder in --ink-3-aa when nothing is chosen. It truncates, and it is the half of the accessible name that says what was picked.
+- **Panel** — Portalled, at least as wide as the trigger and at most 18rem tall, with a scroll chevron appearing at each end once the list is longer than that.
+- **Item** — One option. The 3.5 tick box is always drawn and only the tick inside it appears, so choosing does not shunt every label sideways; data-highlighted is the fill, the tick is the chosen one.
+- **Group heading** — SelectLabel — a mono eyebrow inside a SelectGroup. It is a heading, not an option, which is the difference between it and a disabled item used as a divider.
+
+## Best practices
+
+### Do
+
+- Pass name when the value has to survive a submit. The trigger is a <button>; Radix renders the hidden native <select> that carries the value only when the control is inside a <form>, and only a named one sends anything.
+- Pick one spelling of invalid. The trigger reads the invalid prop and aria-invalid alike, including the one a Field sets from error, so setting both is two sources of truth for one border.
+- Divide long lists with SelectGroup and SelectLabel rather than a disabled item used as a heading: a disabled item is still an option, so a screen reader counts it and announces the list as one longer than it is.
+
+### Don’t
+
+- Inside a Field with a label, the label prop here is not announced — the field’s words name the trigger — so a label that disagrees with the one above it is dead text nobody will ever hear.
+- Do not lean on the closed trigger to show a long option: it truncates to keep the field’s height, so the end of the value is only readable with the panel open.
+- Do not point contentClassName at the trigger. className is the trigger; contentClassName is the panel, and confusing them is how a select gets a 18rem-wide dropdown over the thing it is choosing for.
+
+## 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, and it is announced WITH the value: the trigger reads "Region, Australia", because a value is not a name and a name without the value is not the answer. Inside a Field the FIELD’s label supplies the name half — the trigger’s aria-labelledby points at that label and at the value — and the label prop here is neither rendered nor announced, so one that disagrees with the words above it is text nobody will hear.
+
+## 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. It is announced together with the value, not instead of it: the trigger is named by the label and by its own text, so a reader hears "Region, Australia". Inside a `Field` with a label, that label is used and this one is not repeated.
+- `placeholder` — `string` default `'Select…'`.
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `disabled` — `boolean`.
+- `className` — `string`.
+- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
+- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
+- `aria-invalid` — `boolean | 'true' | 'false'`. The spelling a form library sets; read together with `invalid`.
+- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.
+- `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,60 @@
+# Separator
+
+A rule, in the three weights a monochrome page needs — with words in it when the break has something to say.
+
+- Kind: component
+- Group: Display
+- Import: `import { Separator } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/separator/
+
+## When to reach for it
+
+Hairline between rows, edge between blocks, hard under a masthead. label puts words in the break: "or continue with", "Older".
+
+## Anatomy
+
+- **Rule** (required) — One <div>. A pixel on its cross axis and 100% on its main axis, so it takes the width — or the height — of whatever contains it, and nothing else.
+- **Ink** (required) — The only thing weight changes: --rule inside a block, --rule-2 between blocks, --rule-hard under a masthead. The hard one is not a darker grey, it is --ink itself.
+- **Label** — label, horizontal only. It changes the construction rather than the styling: the rule is drawn TWICE, one aria-hidden piece either side of the words in mono-meta at --ink-3-aa, and the gap between them is a gap.
+
+## Best practices
+
+### Do
+
+- Give a vertical separator a height. It is h-full, which against a parent with no height of its own resolves to zero — the element renders, occupies nothing, and reads as a component that failed to load.
+- Pass decorative={false} when the rule is the only thing dividing two sections a screen reader should hear as distinct: that is what swaps role="none" for role="separator" and sets aria-orientation with it.
+- Use label rather than building "or continue with" out of two Separators and a span. The two rules are drawn for you and neither of them needs to know the ground it is on.
+
+### Don’t
+
+- Do not pick the weight by eye. The three are ordered, so a hard rule between two table rows tells the reader the table ended there.
+- Do not hand-tune a fourth grey through className. Three named weights are the whole set, and the names exist because a monochrome page drifts into five slightly different rules the moment one of them is chosen by feel.
+- Do not lay the label over a single rule with a background colour to punch a hole in it. That version has to be told the ground it is sitting on, and a --paper notch on a --stone card reads as a rendering bug.
+
+## Accessibility
+
+- role="none" by default. A rule that only groups things visually must not be announced.
+- With a label, the words are the content and the two rules are aria-hidden decoration — so decorative no longer applies, and nothing announces a separator over the top of the text.
+- A label on a vertical rule is ignored rather than silently redrawn as a horizontal bar: there is no sensible place for words inside a one-pixel column.
+
+## Separator
+
+A rule, with or without words in it. 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. **On the label.** "or continue with" was two Separators and a span at every call site, and the usual one-element version — text laid over a single rule with a background to punch a hole in it — needs to know the ground it is sitting on. Get that wrong and the notch is `--paper` on a card that is `--stone`, which reads as a rendering bug. So there is no ground: the rule is drawn twice, one piece either side of the label, and the gap is a gap. It is correct on any surface without being told which one it is on.
+
+### 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.
+- `label` — `ReactNode`. Words in the break — "or continue with", "Older". Horizontal only, and it changes the construction rather than the styling: see the note on the component. `decorative` no longer applies, because the label is content and the two rules beside it are decoration either way.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Examples
+
+```tsx
+<Separator weight="hard" />
+<Separator orientation="vertical" className="h-4" />
+<Separator label="or continue with" />
+```

package/dist/agent/SequenceFigure.md

@@ -0,0 +1,51 @@
+# SequenceFigure
+
+A call chain over time: who asks whom, in what order, and what comes back.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { SequenceFigure } from '@misoto22/folio/diagrams'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/sequence-figure/
+- Related: workflow-figure, architecture-figure
+
+## When to reach for it
+
+The only figure whose vertical axis means something. A message carries an explicit y, so two calls eight units apart happened together and two two hundred apart did not.
+
+## Anatomy
+
+- **Figure shell** (required) — The frame around the picture. What a trace hands it is a message list, and it is published in the order the messages array is written — which is the only ordering a reader who cannot see the axis is given.
+- **Participant head** (required) — A 148-unit plate per participant at the top of its column, in the order the participants array puts them. meta.column_fit: "spread" widens every column to the widest name instead of holding the fixed width.
+- **Lifeline** (required) — A hairline dropped from each head to below the last thing on the axis. A hairline and not a rule, because it is the axis: seven lifelines at message weight is seven vertical lines competing with twelve horizontal ones.
+- **Message** (required) — A horizontal line at its own y, inset from both lifelines so the arrowhead lands clear of the axis, with the wording on a mask above it. A return is dashed AND takes an open head — two signals, because the reply is what a reader picks out of a dense trace.
+- **Activation bar** — A narrow bar on a lifeline from one y to another: who is BUSY. It is the fact a sequence diagram carries that a list of calls does not, and one bar overlapping another is the reason to draw the picture at all.
+- **Segment band** — A dashed rule across the whole figure with a mono caption on a masked patch — request, fallback, response. A caption rather than a tinted panel, because a second ground inside the figure would sit under every message label’s mask.
+
+## Best practices
+
+### Do
+
+- Author the messages in ascending y. The picture reads the axis and the summary list beside it iterates the array, so a message written out of order is drawn at one point in the exchange and read aloud at another.
+- Reach for meta.column_fit: "spread" when a participant’s name is longer than the fixed column. The plate wraps to two lines and ellipsises whatever still does not fit, and shortening the name to make it fit is not a repair — the name is the data.
+- Space the messages by what actually happened. Nothing normalises y, so eight units between two calls reads as together and two hundred reads as a wait; an evenly spaced list is tidier and says something the trace does not.
+
+### Don’t
+
+- A message naming a participant that participants does not declare leaves the picture and the summary list together — there is no column to draw it between, and a text equivalent reporting a call the picture cannot show is two halves of one figure disagreeing. Development prints DIAGRAM_EDGE_DANGLING with both ends, which is now the only place that message is reported at all.
+- This figure ASSERTS order. Three calls a service makes concurrently, given three y values because they had to be given something, are a picture claiming the second waited for the first — an activation bar or a segment caption is where "these overlap" belongs.
+
+## Accessibility
+
+- Return messages are dashed AND take an open arrowhead — two signals, because the reply is what a reader most often needs to pick out of a dense trace.
+- The message list beside the picture reads in order, which is the same order the axis is drawn in.
+
+## SequenceFigure
+
+A call chain over time: who asks whom, in what order, and what comes back. The one diagram type here whose vertical axis MEANS something. Every other figure's y is layout; a sequence's y is time, which is why a message carries an explicit `y` rather than an index — two calls 8 units apart happened together, and two 200 apart did not, and an evenly spaced list of messages would erase that distinction while looking tidier. **Lifelines** are hairlines, not solid rules, because they are the axis rather than the content. A lifeline drawn at the weight of a message is a diagram where seven vertical lines compete with twelve horizontal ones. **Activation bars** say who is BUSY, which is the fact a sequence diagram carries that a list of calls does not — the third participant's bar overlapping the second's is the reason to draw them at all. **Segments** band the axis into phases — request, fallback, response — printed as a rule with a mono caption rather than as a tinted panel, for the same reason architecture boundaries are: a second ground inside the figure would sit under every message label's mask. A `return` message is dashed AND takes an open arrowhead. Two signals rather than one, because the reply is the thing a reader most often needs to pick out of a dense trace, and a dash alone is doing the same work as `dashed` already does for an asynchronous call.
+
+### Props
+
+- `spec` (required) — `SequenceSpec`.
+
+Also accepts: `FigureChrome`.

package/dist/agent/Sheet.md

@@ -0,0 +1,82 @@
+# Sheet
+
+A panel docked to an edge of the viewport.
+
+- Kind: component
+- Group: Overlays
+- Import: `import { Sheet } from '@misoto22/folio'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Scrim** (required) — The same --scrim at --z-overlay that Dialog uses — the same component, in fact, so the page behind is inert and scroll-locked exactly as it is under a dialog.
+- **Panel** (required) — The docked box. start and end are a min(24rem, 92vw) column at full height; top and bottom are a full-width band capped at 85vh. A flex column that scrolls itself.
+- **Title** (required) — title, typed as required rather than optional — there is no unnamed-sheet path to fall into, only a hidden-title one via hideTitle.
+- **Description** — description, under the title, sharing the wrapper that hideTitle hides.
+- **Close** (required) — The X in the top-end corner. Unlike Dialog there is no showClose to turn it off, so every sheet has one whichever edge it is docked to.
+
+## Best practices
+
+### Do
+
+- Reach for a Sheet over a Dialog when the content is a list or a form long enough to scroll: it gets the full height of the viewport rather than Dialog’s 32rem by 85vh box, and the reader keeps the page edge as an anchor.
+- Use top or bottom when the content is wide and short — a filter bar, a date range. start and end are a 24rem column, and a table pushed into one wraps into a ribbon.
+- Name the sides start and end rather than reaching for left and right: each edge has its own literal class string carrying its own rtl: variant, so end arrives from the right in English and the left in Arabic with no second code path.
+- Wrap the cancelling control in SheetClose so the close runs through Radix — a sheet closed by your own state setter leaves focus inside a panel that is no longer on the page.
+
+### Don’t
+
+- Do not re-declare the travel in className. The panel carries data-folio-animated, which removes its transform outright under reduced motion; a second transform of your own only gets the universal floor, so it still arrives — a hundredth of a millisecond later, from wherever you put it.
+- An OverlayContainer whose element is not positioned docks the sheet to the wrong box: naming a container switches the panel from fixed to absolute, so an unpositioned container sends it to the nearest positioned ancestor rather than to the frame.
+- It is a modal dialog, so the page behind is scroll-locked and pointer-inert: this is not the home for a filter panel the reader is meant to work alongside. That is a Popover, or a column in the layout.
+
+## 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. Portals into the element an enclosing `OverlayContainer` names, docking to that element's edge rather than the viewport's when there is one.
+
+### 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.
+- `closeLabel` — `string` default `'Close'`. Accessible close action, supplied by the host locale.
+
+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>
+```