@misoto22/folio 0.0.0 → 0.17.0

package/dist/agent/Conversation.md

@@ -0,0 +1,247 @@
+# Conversation
+
+Conversation threads, answers, citations, composers and floating chat surfaces.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { ConversationLayout } from '@misoto22/folio/website'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/conversation/
+
+## When to reach for it
+
+Compose a localized assistant interface while the host owns streaming, history and service calls.
+
+## 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.
+
+## ConversationLayout
+
+A reading-width conversation with a separate, sticky evidence rail.
+
+### Props
+
+- `evidence` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ConversationFacts
+
+### Props
+
+- `items` (required) — `DescriptionListItem[]`.
+
+Also accepts: `HTMLAttributes<HTMLDListElement>`.
+
+## ConversationSuggestions
+
+### Props
+
+- `label` (required) — `string`.
+- `items` (required) — `ConversationSuggestion[]`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ConversationThread
+
+Host owns turns and folding; this composition owns their hierarchy and controls.
+
+### Props
+
+- `label` (required) — `string`.
+- `intro` — `{ title: ReactNode; description: ReactNode; suggestionsLabel: string; suggestions: ConversationSuggestion[] }`.
+- `summary` — `ReactNode`.
+- `controls` — `ConversationControl[]` default `[]`.
+- `composer` (required) — `ReactNode`.
+- `proposal` — `ReactNode`.
+- `hasTurns` (required) — `boolean`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## ConversationLog
+
+### Props
+
+- `compact` — `boolean`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## QuestionComposer
+
+A controlled, labelled composer. Request limits and sending remain host concerns.
+
+### Props
+
+- `id` (required) — `string`.
+- `label` (required) — `string`.
+- `hideLabel` — `boolean`.
+- `value` (required) — `string`.
+- `onValueChange` (required) — `(value: string) => void`.
+- `onSubmit` (required) — `() => void`.
+- `inputRef` — `Ref<HTMLInputElement>`.
+- `placeholder` — `string`.
+- `maxLength` — `number`.
+- `disabled` — `boolean`.
+- `submitDisabled` — `boolean`.
+- `pending` — `boolean`.
+- `submitLabel` (required) — `string`.
+- `hint` — `ReactNode`.
+- `hideHint` — `boolean`.
+- `counter` — `ReactNode`.
+- `actions` — `ReactNode`.
+- `compact` — `boolean`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLFormElement>, 'onSubmit'>`.
+
+## ConversationTurn
+
+### Props
+
+- `title` (required) — `ReactNode`.
+- `metadata` — `ReactNode`.
+- `expanded` (required) — `boolean`.
+- `onToggle` (required) — `() => void`.
+- `bodyId` (required) — `string`.
+- `preview` — `ReactNode`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.
+
+## ConversationQuote
+
+### Props
+
+- `label` (required) — `string`.
+- `compact` — `boolean`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## ConversationAnswer
+
+### Props
+
+- `question` (required) — `ReactNode`.
+- `questionLabel` (required) — `string`.
+- `quote` — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ConversationProse
+
+Trusted React nodes from the host's sanitized answer parser, never raw model HTML.
+
+## ConversationAnswerHeading
+
+Model-generated headings are prose labels, so they do not alter the page outline.
+
+## StreamingCaret
+
+## ConversationSources
+
+### Props
+
+- `label` (required) — `string`.
+- `count` (required) — `ReactNode`.
+- `items` (required) — `ConversationSource[]`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ActionProposal
+
+### Props
+
+- `label` (required) — `string`.
+- `destination` (required) — `ReactNode`.
+- `detail` — `ReactNode`.
+- `approveLabel` (required) — `string`.
+- `dismissLabel` (required) — `string`.
+- `onApprove` (required) — `() => void`.
+- `onDismiss` (required) — `() => void`.
+- `approvalAttributes` — `Record<`data-${string}`, string>`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ConversationLauncher
+
+### Props
+
+- `visible` (required) — `boolean`.
+- `buttonRef` — `Ref<HTMLButtonElement>`.
+
+Also accepts: `ButtonHTMLAttributes<HTMLButtonElement>`.
+
+## ConversationDock
+
+The host supplies placement, dismissal and stream state; the dock draws them.
+
+### Props
+
+- `label` (required) — `string`.
+- `open` (required) — `boolean`.
+- `card` (required) — `boolean`.
+- `corner` (required) — `ConversationDockCorner`.
+- `dragging` — `boolean`.
+- `moving` — `boolean`.
+- `panelRef` — `Ref<HTMLElement>`.
+- `logRef` — `Ref<HTMLDivElement>`.
+- `roomLink` (required) — `ReactElement`.
+- `closeLabel` (required) — `string`.
+- `onClose` (required) — `() => void`.
+- `onHeaderPointerDown` — `(event: PointerEvent<HTMLElement>) => void`.
+- `handles` — `ReactNode`.
+- `proposal` — `ReactNode`.
+- `notice` — `ReactNode`.
+- `composer` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## ConversationDockWelcome
+
+### Props
+
+- `lead` (required) — `ReactNode`.
+- `suggestionsLabel` (required) — `string`.
+- `suggestions` (required) — `ConversationSuggestion[]`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ConversationResizeHandle
+
+Keyboard equivalents for the host's pointer resize controller.
+
+### Props
+
+- `axis` (required) — `'size-vertical' | 'size-horizontal'`.
+- `side` (required) — `'top' | 'bottom' | 'left' | 'right'`.
+- `label` (required) — `string`.
+- `dragging` (required) — `boolean`.
+- `onStart` (required) — `(axis: 'size-vertical' | 'size-horizontal', event: PointerEvent<HTMLElement>) => void`.
+- `onNudge` (required) — `(axis: 'size-vertical' | 'size-horizontal', delta: number) => void`.
+
+## SelectionToolbar
+
+Selection actions with a real toolbar's single tab stop and arrow navigation.
+
+### Props
+
+- `label` (required) — `string`.
+- `actions` (required) — `SelectionToolbarAction[]`.
+- `floating` (required) — `boolean`.
+- `toolbarRef` — `Ref<HTMLDivElement>`.
+- `style` — `CSSProperties`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ConversationRoomLink
+
+A router link keeps its own destination and behavior inside a standard action.
+
+## Types
+
+- `ConversationDockCorner` = `'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'`

package/dist/agent/DataflowFigure.md

@@ -0,0 +1,49 @@
+# DataflowFigure
+
+A pipeline: where data comes from, what happens to it, and who ends up with it.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { DataflowFigure } from '@misoto22/folio/diagrams'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/dataflow-figure/
+- Related: architecture-figure, lifecycle-figure
+
+## When to reach for it
+
+Structurally close to an architecture map, read for a different question. classification gets its own chip because a governance reviewer is looking for exactly that.
+
+## Anatomy
+
+- **Figure shell** (required) — The frame around the picture. What a pipeline hands it is a flow list with the classification folded in — "clickstream — PII touch" — so the fact the diagram was opened for reaches a reader who never sees the chip.
+- **Stage heading** (required) — One mono caption per stage on a rule across the top. It is the axis: a node’s stage is how far along the pipeline it sits, so "has this been aggregated yet" is answered by looking up rather than by tracing arrows.
+- **Node plate** (required) — One box per node, placed by stage across and row down. The row pitch leaves a clear band between two boxes in the same column, which is where a line and its wording go.
+- **Flow** — A routed line with a single arrowhead, at its to end. It is the direction claim the whole figure is read for.
+- **Classification chip** — classification, printed in mono under the wording rather than inside it. "clickstream" and "clickstream / PII touch" are two different facts, and only one of them is what a governance review came for.
+
+## Best practices
+
+### Do
+
+- Put the governance fact in classification rather than in the label. It prints as its own chip on the line and is appended to the flow’s summary line, so it survives both a reader who is scanning the picture and one who only has the text.
+- Keep stage inside the stages you declared. A node’s x is computed from its own stage index rather than looked up, so a node at stage 5 beside four stages is drawn a full column past the last heading, under no heading at all — development prints DIAGRAM_STAGE_OUT_OF_RANGE, and the summary files it under a band called outside the declared stages rather than beside the nodes the axis does label.
+- Write a two-way exchange as two flows. Every line carries a head at its to end only, so one flow between a service and its cache says data moves one way, whatever the label claims about the round trip.
+
+### Don’t
+
+- via, channelX and channelY are never honoured here — a data-flow node is always placed by stage and row, so an author’s waypoints refer to a grid this renderer did not build. They are dropped and every line is routed from scratch: the specification still typechecks and the picture is not the one it drew.
+- Watch the fan-in. Lines sharing a face are spread evenly across it, and an arrowhead is 11 user units wide against a plate about 55 units tall — so four lines into one face is where the heads meet, and the fifth and sixth arrive as one thick mark. A pipeline at that density wants splitting, not more edges.
+
+## Accessibility
+
+- A flow’s classification is folded into its summary line, so "clickstream — PII touch" reaches a reader who cannot see the chip.
+
+## DataflowFigure
+
+A pipeline: where data comes from, what happens to it, and who ends up with it. Structurally close to an architecture map and read for a completely different question, which is why it is a separate renderer rather than a preset. An architecture diagram is read for "what talks to what". A data-flow diagram is read for "what is IN this arrow" — and that question is why `classification` gets its own mono chip under the label rather than being folded into the wording. `clickstream / PII touch` and `clickstream` are two different facts, and a governance reviewer is looking for the second one. Stages are printed as column headings on a rule across the top. They are the axis of the figure: a node's `stage` is its position along the pipeline, and a reader should be able to answer "how far has this got" by looking up rather than by tracing arrows.
+
+### Props
+
+- `spec` (required) — `DataflowSpec`.
+
+Also accepts: `FigureChrome`.

package/dist/agent/DatePicker.md

@@ -0,0 +1,104 @@
+# DatePicker
+
+A date — or a span of them — chosen from a calendar.
+
+- Kind: component
+- Group: Forms
+- Import: `import { DatePicker } from '@misoto22/folio'`
+- Version: 0.17.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.
+
+## Anatomy
+
+- **Trigger** (required) — A <button> printing format(value) or the placeholder, with a calendar glyph pinned at the end. It is named by the label and the printed date together, so the format is heard as well as seen.
+- **Panel** — A Popover holding the rail and the grid — side by side from sm up, stacked below it, where two months would not fit anyway.
+- **Preset rail** — A role="group" of plain buttons, present only when presets is set: on by default for DateRangePicker, off by default for DatePicker. A shortcut that lands on a disabledDates day is drawn unavailable and refuses the click.
+- **Calendar grid** — The shared Calendar, autoFocus on open so the keyboard lands in the month rather than back at the trigger. Two months at once on the range picker, from months.
+- **Half-range text** — The range trigger prints “from – …” while only one end is chosen, so a half-answered range says so on the closed control instead of looking finished.
+
+## Best practices
+
+### Do
+
+- Put the restriction in disabledDates rather than in your own handler. The rail asks it too, so a shortcut on a blocked day is disabled instead of committing a date the grid beside it refuses — a range preset is tested at its ENDS, so one straddling a blocked day is still offered, exactly as the grid still allows it.
+- Pick controlled or uncontrolled and stay there. The current value is value ?? uncontrolled, so a controlled picker that clears by setting value to undefined falls through to whatever defaultValue seeded and the old date reappears.
+- Validate a range before you use it: half a range is a legal state here — from set, to undefined — so a submit handler that reads value.to without checking gets undefined from a reader who simply closed the panel early.
+
+### Don’t
+
+- A Field’s required does not reach the trigger. It is a plain <button>, a role with nowhere to put aria-required, so the asterisk above is the whole of the marking and a screen reader meets an ordinary optional field.
+- Do not reach for it for a birth date. There is no defaultMonth to pass: the panel always opens on the current month, so a date decades back begins with every reader in the month-and-year picker.
+- Do not disable it to show a fixed date. disabled takes the trigger out of the tab order and blocks its pointer events, and the trigger is the only place the chosen date is printed at all.
+
+## Accessibility
+
+- The trigger prints the date in the visitor’s own locale, not a fixed dd/mm/yyyy, and announces it as part of its own name — so format reaches a screen reader too.
+- 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. Announced together with the printed date rather than instead of it, so `format` reaches a screen reader as well as the screen. Inside a `Field` with a label, that label names the trigger and this one is not repeated.
+- `placeholder` — `string` default `'Pick a date'`.
+- `disabled` — `boolean` default `false`.
+- `disabledDates` — `ComponentProps<typeof Calendar>['disabled']`. Days the reader may not choose. Reaches the calendar AND the shortcut rail: a preset landing on a blocked day is drawn unavailable and refuses the click, rather than committing a value the grid beside it would not accept.
+- `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`.
+- `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'`. Announced on the trigger. A `Field` sets it from `error`.
+
+## 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`. Names the control. Announced together with the printed range, not instead of it.
+- `placeholder` — `string` default `'Pick a range'`.
+- `disabled` — `boolean` default `false`.
+- `disabledDates` — `ComponentProps<typeof Calendar>['disabled']`. Days the reader may not choose. Reaches the shortcut rail as well as the grid, at the ENDS of each preset range — a shortcut whose interior straddles a blocked day is still offered, the way the grid still lets a reader drag a range across one.
+- `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`.
+- `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'`. Announced on the trigger. A `Field` sets it from `error`.
+
+## Examples
+
+```tsx
+<Field label="Publish on"><DatePicker label="Publish on" /></Field>
+<DateRangePicker label="Reporting period" />
+```

package/dist/agent/DescriptionList.md

@@ -0,0 +1,69 @@
+# DescriptionList
+
+One record’s fields, as a real <dl> rather than a grid of divs.
+
+- Kind: component
+- Group: Surfaces
+- Import: `import { DescriptionList } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/description-list/
+- Related: table, card, timestamp
+
+## When to reach for it
+
+One record seen from the front — a detail page, a summary panel. Several records seen from above is a Table.
+
+## Anatomy
+
+- **List** (required) — The <dl>. It is the element that carries the pairing: a grid of divs looks identical and tells a screen reader there are two columns of unrelated text.
+- **Pair** (required) — A <div> around each dt/dd, which the HTML specification allows inside a <dl> precisely so a pair can be laid out as a unit. It is what the hairline is drawn on, so the rule crosses the whole row rather than stopping in the column gap.
+- **Term** (required) — item.term, rendered as <dt> at --ink-3-aa. In the row layout it holds a 12rem column at sm and above and stacks below it, because a 12rem label column on a phone leaves the value about eight characters wide.
+- **Description** (required) — item.description, rendered as <dd> at --ink-2 with its browser margin reset. It takes a node, not a string, so a value can be a Badge, a link or a Timestamp.
+- **Hairline** — divided, on by default: a --rule under every pair but the last. Turn it off inside a Card, which already has an edge of its own.
+
+## Best practices
+
+### Do
+
+- Let it render nothing when items is empty. It returns null rather than an empty bordered box, so the page above is free to show an EmptyState instead of a hairline around no content.
+- Put an element in description when the value is a state or a link — it is a <dd>, so a Badge, an anchor or a Timestamp belongs there and a string of text does not have to be faked into one.
+- Pass id on each item when rows are added, removed or reordered. The index is the key without one, which is right for the fixed field list a record page renders and wrong for a list that changes shape.
+
+### Don’t
+
+- Do not reach for it to show several records. Every dt would repeat down the page and a reader comparing two records has to hold both in their head — that is what a Table’s column headings exist to avoid.
+- Do not use layout="row" inside a narrow sidebar. It only collapses on the sm breakpoint, which is the viewport, not the container — a 12rem label column inside a 20rem panel leaves nothing for the value. Use layout="stacked" there.
+
+## Accessibility
+
+- A real <dl>, <dt> and <dd>, which is what tells a screen reader that a label names the value beside it.
+- Each pair is grouped in a <div>, which the specification permits inside a <dl> and which assistive technology reads through.
+- An empty list renders null rather than an empty <dl>, so nothing announces a list with no items in it.
+
+## DescriptionList
+
+A record's fields: label, value, label, value. The single most repeated shape in any detail page, and the one most often hand-built out of a `<div>` grid — which loses the only thing the markup was carrying. A `<dl>` tells a screen reader that "Owner" names the thing beside it; a grid of divs tells it there are two columns of unrelated text, and the reader has to infer the pairing from reading order alone. Reach for `Table` instead when there are several records. This is one record seen from the front; a table is many records seen from above. Each pair is wrapped in a `<div>` — which the HTML specification allows inside a `<dl>` precisely so a pair can be laid out as a unit — so the hairline runs the full width of the row rather than stopping in the column gap. An empty `items` renders `null` rather than an empty bordered box. A record with no fields is a state the page above should be handling with an `EmptyState`, and a hairline around nothing looks like a component that failed to load.
+
+### Props
+
+- `items` (required) — `DescriptionListItem[]`. The pairs, in the order they should read. An empty array renders nothing.
+- `layout` — `DescriptionListLayout` default `'row'`. How the value sits relative to its label. See DescriptionListLayout.
+- `divided` — `boolean` default `true`. Draws a hairline under every pair but the last. Off for a list inside a card that already has an edge, on for a list that is the page's structure.
+
+Also accepts: `HTMLAttributes<HTMLDListElement>`.
+
+## Types
+
+- `DescriptionListLayout` = `'row' | 'stacked'`
+
+## Examples
+
+```tsx
+<DescriptionList
+  items={[
+    { term: 'Owner', description: 'Henry Chen' },
+    { term: 'Status', description: <Badge tone="success">Deployed</Badge> },
+  ]}
+/>
+<DescriptionList layout="stacked" divided={false} items={fields} />
+```

package/dist/agent/Diagram.md

@@ -0,0 +1,71 @@
+# Diagram
+
+A flow or architecture figure, drawn out of the system’s own parts.
+
+- Kind: component
+- Group: Display
+- Import: `import { Diagram } from '@misoto22/folio'`
+- Version: 0.17.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.
+
+## Anatomy
+
+- **Frame** (required) — The <figure role="group"> and the panel inside it: a --rule hairline on the --radius-lg corner over --paper-2, with fluid padding and overflow-x-auto on a hairline scrollbar — so a wide figure scrolls inside its own box instead of widening the page.
+- **Leaf plate** — A node with NO children: a bordered card on --paper, or filled with --accent when accent is set. Its label breaks inside itself, because an identifier like TenantMainMiddleware has no break opportunity and would otherwise run into the plate’s edge.
+- **Container band** — A node WITH children: a labelled hairline — ink at the top rank, --rule-2 below it — with its children underneath and no frame of its own. That is the whole design: drawing a container as another box puts three borders around anything two levels deep.
+- **Node note** — node.note, a mono line beside a band’s label or under a plate’s. One short line, a step back from the name.
+- **Edge mark** — The arrow between two adjacent siblings an edge names, with the edge’s label under it. aria-hidden, and rotated a quarter turn below the sm breakpoint, where a row of nodes stacks into a column and the arrow has to point the way the layout actually runs.
+- **Caption** — spec.caption, printed under the frame — as a <div>, not a <figcaption>, because an article stylesheet styles figcaption unlayered and an unlayered rule beats a utility whatever the specificity.
+
+## Best practices
+
+### Do
+
+- Write an edge from a node to the node immediately after it in the same rank, in that order. An edge between non-adjacent nodes, or one written to→from, draws no arrow — and now says so in the console rather than leaving the author to spot a missing arrow in a picture that otherwise looks finished.
+- Keep ids unique across the whole spec. Each edge is now spent at the first pair that matches it, so a reused pair no longer draws the arrow twice — but the arrow lands on whichever pair comes first, which is a diagram asserting something nobody wrote.
+- Give the spec a caption or a label. The figure’s role="group" is named by whichever is present, and with neither the reader is told there is a group and never told what of.
+
+### Don’t
+
+- accent is read only in the plate branch, so setting it on a node with children compiles, type-checks and paints nothing — a container is a band, and a band has no fill to take. Development says so; a production build does not.
+- direction is read only from a node that HAS children. Set on a leaf it is ignored, because the axis a leaf sits on belongs to its parent — and, like accent on a band, it is reported in development rather than silently dropped.
+- Do not put six nodes across the top rank. A row is flex-col below sm and only flex-row above it, so a figure that reads as a pipeline on a desktop is six stacked plates and five arrows on a phone.
+
+## 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.
+- A spec the renderer cannot honour — an unmatched edge, a duplicate id, accent on a band, direction on a leaf — prints a named warning in development, because the alternative is a confident picture of something else.
+
+## 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', children: [
+        { label: 'Router', accent: true },
+        { label: 'Handlers' },
+      ] },
+    ],
+  }}
+/>
+```

package/dist/agent/DiagramCanvas.md

@@ -0,0 +1,71 @@
+# DiagramCanvas
+
+A frame that a picture larger than it can be panned and zoomed inside.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { DiagramCanvas } from '@misoto22/folio/diagrams'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/diagram-canvas/
+- Related: diagram-minimap, architecture-figure, scroll-area
+
+## When to reach for it
+
+Any oversized figure — an SVG, an image, a table that will not fold. It knows nothing about nodes, which is what makes it reusable.
+
+## Anatomy
+
+- **Frame** (required) — The outer box: a fixed height — 24rem unless height says otherwise — a hairline, the diagram ground, and overflow hidden. It is the window the artwork is bigger than.
+- **Viewport** (required) — The focusable layer inside it: role="group" with a name, tabIndex 0, the drag handlers, the key handler and a focus ring drawn inside the frame. This is the tab stop, and it is what makes the keys pressable at all.
+- **Stage** (required) — The wrapper the translate and scale are applied to. The transform is on the wrapper and never on the child, so the figure inside keeps its own coordinate space and every measurement taken inside it stays true.
+- **Zoom controls** — The cluster pinned to the bottom corner: zoom out, the current percentage — which is also the reset button, named for what it does — and zoom in. controls={false} removes the cluster and leaves the keys.
+- **Keyboard hint** (required) — A visually hidden paragraph, referenced by aria-describedby, saying that the frame drags and which keys pan, zoom and reset. Nothing on screen carries that sentence.
+
+## Best practices
+
+### Do
+
+- Name it. label is the group’s accessible name and it defaults to "Diagram canvas", so two canvases on one page announce the same thing until each is given its own.
+- Strip the figure inside to its artwork with heading={false}, legend="hidden" and cards={false}. Everything in the frame pans and zooms together, so a title left on travels away from the diagram it names and a key leaves the frame at exactly the zoom that made a reader want it.
+- Move the view through the ref — zoomIn, zoomOut, reset, centerOn — rather than re-rendering the child at a new size. centerOn takes a point in the content’s own coordinates, which is what a minimap reports back.
+- Hand onViewChange straight to a minimap. Each view carries the frame it was measured against as well as the scale and the offset, and that pair is the whole of the arithmetic a viewport rectangle is — the frame being the one number nothing outside the canvas can measure.
+
+### Don’t
+
+- Nothing clamps the pan. The offset is whatever the drag or the arrow keys left it at, so the artwork can be pushed entirely outside the frame; 0 and the reset button are the whole way back, and controls={false} without a replacement takes the pointer’s half of that away.
+- The scale stops at 0.35. A figure more than about three times the frame cannot be zoomed out far enough to be seen whole, so the frame has to be sized for the diagram — a minimap answers where you are, never what is there.
+- The wheel is left alone and the thumb is not: the frame sets touch-action to none, so a finger dragged inside it pans the diagram and never scrolls the page. A full-width canvas in an article is a band a touch reader has to swipe around rather than through, which is the argument for giving it a height short enough to leave page beside it.
+
+## Accessibility
+
+- The frame is a real tab stop, so the keyboard controls can be pressed at all.
+- A plain wheel scrolls the page. Zoom needs the platform modifier, so the canvas is never a scroll trap in the middle of an article.
+
+## Keyboard
+
+- + / = — Zooms in about the centre of the frame.
+- - — Zooms out.
+- 0 — Resets the scale and the offset together.
+- ← / → / ↑ / ↓ — Pans. Shift pans further per press.
+
+## DiagramCanvas
+
+A frame that a picture larger than it can be moved around inside. Pan with a drag, zoom with the controls or with ⌘/Ctrl and the wheel, and reset with a key. That is the whole of it — this is deliberately a VIEWPORT and not a diagram editor: nothing here knows what a node is, so it works for any oversized figure, an SVG, an image, a table that will not fold. Three decisions here are not obvious. **A plain wheel scrolls the page, not the diagram.** A canvas that swallows the wheel is a scroll trap: a reader flicking down an article hits the figure and the page stops moving for no reason they can see. Zooming needs the modifier — which is also the platform gesture for zoom everywhere else, and is what a trackpad pinch already sends. **The transform is on a wrapper, not on the content.** The child keeps its own coordinate space, so a figure inside can still be measured, exported and read by anything that walks it. Scaling the child directly would make every `getBoundingClientRect` inside it a lie. **Keyboard first, and the frame is a real tab stop.** `+` / `-` / `0` and the arrow keys move the view; the frame takes focus so they can be pressed at all. A canvas that only answers a drag is a canvas half the readers cannot operate.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `className` — `string`.
+- `height` — `string` default `'24rem'`. How tall the frame is. Anything CSS accepts.
+- `onViewChange` — `(view: CanvasView) => void`. Told about every view change, for a minimap or a percentage readout.
+- `controls` — `boolean` default `true`. Hides the built-in zoom controls, for a caller supplying its own.
+- `label` — `string` default `'Diagram canvas'`. Names the region for assistive tech.
+- `ref` — `Ref<DiagramCanvasHandle>`.
+
+## Examples
+
+```tsx
+<DiagramCanvas height="26rem" label="Request path">
+  <ArchitectureFigure spec={spec} heading={false} legend="hidden" cards={false} />
+</DiagramCanvas>
+```