@misoto22/design 0.7.0 → 0.9.0

package/dist/agent/DatePicker.md

@@ -4,7 +4,7 @@ A date — or a span of them — chosen from a calendar.
 
 - Group: Forms
 - Import: `import { DatePicker } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/date-picker/
 - Related: calendar, field
 
@@ -12,9 +12,31 @@ A date — or a span of them — chosen from a calendar.
 
 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.
+- 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.
@@ -41,13 +63,16 @@ A date, chosen from a calendar. A trigger and a `Calendar` in a `Popover` — no
 - `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.
+- `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. Passed straight to the calendar.
+- `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
 
@@ -58,14 +83,17 @@ A span of dates — a stay, a reporting period, a filter. Two months side by sid
 - `value` — `DateRange`.
 - `defaultValue` — `DateRange`.
 - `onValueChange` — `(value: DateRange | undefined) => void`.
-- `label` (required) — `string`.
+- `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']`.
+- `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
 

package/dist/agent/DescriptionList.md

@@ -0,0 +1,68 @@
+# DescriptionList
+
+One record’s fields, as a real <dl> rather than a grid of divs.
+
+- Group: Surfaces
+- Import: `import { DescriptionList } from '@misoto22/design'`
+- Version: 0.9.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

@@ -4,7 +4,7 @@ A flow or architecture figure, drawn out of the system’s own parts.
 
 - Group: Display
 - Import: `import { Diagram } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/diagram/
 - Related: card, figure-band
 
@@ -12,11 +12,35 @@ A flow or architecture figure, drawn out of the system’s own parts.
 
 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
 
@@ -36,8 +60,8 @@ A flow or architecture diagram, drawn out of the system's own parts. The alterna
     edges: [{ from: 'edge', to: 'app', label: 'HTTPS' }],
     nodes: [
       { id: 'edge', label: 'Edge', note: 'CDN' },
-      { id: 'app', label: 'Application', accent: true, children: [
-        { label: 'Router' },
+      { id: 'app', label: 'Application', children: [
+        { label: 'Router', accent: true },
         { label: 'Handlers' },
       ] },
     ],

package/dist/agent/DiagramCanvas.md

@@ -4,7 +4,7 @@ A frame that a picture larger than it can be panned and zoomed inside.
 
 - Group: Diagrams
 - Import: `import { DiagramCanvas } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/diagram-canvas/
 - Related: diagram-minimap, architecture-figure, scroll-area
 
@@ -12,6 +12,29 @@ A frame that a picture larger than it can be panned and zoomed inside.
 
 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.

package/dist/agent/DiagramExportMenu.md

@@ -4,7 +4,7 @@ Taking the figure off the page: PNG, JPEG, WebP, SVG and a 1200×630 share card.
 
 - Group: Diagrams
 - Import: `import { DiagramExportMenu } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/diagram-export-menu/
 - Related: dropdown-menu, diagram-toolbar
 
@@ -12,13 +12,38 @@ Taking the figure off the page: PNG, JPEG, WebP, SVG and a 1200×630 share card.
 
 It does the export rather than emitting a format name, because the interesting half — baking custom properties into real colours before serialising — is the half a caller would not know to write.
 
+## Anatomy
+
+- **Trigger** (required) — A small secondary button reading Export, or whatever trigger replaces it — the replacement is slotted, so it becomes the menu’s own control rather than sitting next to one.
+- **Menu** (required) — A dropdown aligned to the trigger’s end, in three labelled groups separated by rules: Image, Vector, Share. The grouping is the answer to "which of these five do I want".
+- **Format row** (required) — One menu row per format, with its name and a mono hint under it — "Lossless, 2× for retina", "Compact, flattened onto paper". Real menu rows, so the arrow keys walk them, typing jumps to one, and picking one closes the menu over the file it just wrote. The running one gains an ellipsis and every row is disabled until it finishes, so a second click cannot start a second export.
+- **Serialiser** (required) — The part with nothing to point at: the artwork is cloned, every node’s computed paint is written inline, and the clone is placed on a plate the size of the picture plus its padding. It is what stops var(--ink) arriving in a document with no stylesheet and painting nothing.
+- **Share card** — A fixed 1200 × 630 frame with the title printed on it and the whole diagram letterboxed inside — never cropped to fill, because a card cropped to fill is a picture of a different diagram.
+- **Result** — onResult, called with the format, an ok or the Error, and the source that produced it. It is the only place a failed export is reported.
+
+## Best practices
+
+### Do
+
+- Point targetRef at the wrapper rather than at an svg you found yourself. The export looks for the artwork marker first, which is what stops a page whose toolbar sits inside the same wrapper from exporting a picture of a chevron.
+- Export after the artwork has been measured. The serialiser reads the element’s box and throws when it is still zero, so a call made in the same tick as the mount fails loudly instead of writing an empty file.
+- Take onResult and put a failure in front of the reader. An unmeasured figure, a canvas tainted by a cross-origin image, a browser that returned no 2D context — each is reported there rather than thrown at the click, and the alternative is a menu item that quietly does nothing.
+- Read source alongside ok. built-in says a file reached the browser; caller says your own onExport resolved, which is exactly what a handler that did nothing also does — the menu cannot see inside your pipeline and no longer reports as though it can.
+- Pass background={null} for a figure going onto a coloured page. Every other export paints the reader’s own surface behind the artwork, and JPEG is flattened onto that surface whatever this says, because a transparent JPEG is a black one.
+
+### Don’t
+
+- The file is the artwork and the theme the reader was in. Paint is read off the live element, so a figure exported from a dark page is a dark image in a light document; and the toolbar, the inspector and the figure’s own hidden summary list are HTML, so none of them travels with it.
+- Do not treat the SVG as a pixel-exact record. The isolated document cannot fetch the page’s web fonts, so the type falls back to what the machine has — the words and the line breaks are already fixed, but a name that just fitted its plate on screen can overrun its own rule in the file.
+- The output is sized from the artwork’s box ON SCREEN rather than from its viewBox, so a figure sitting at 4× inside a DiagramCanvas serialises four times larger and then rasterises at 2× on top of that. Reset the view before exporting, or a reader gets a file whose dimensions record where the zoom happened to be.
+
 ## Accessibility
 
 - A failed export is reported through onResult rather than swallowed: a click that quietly does nothing is indistinguishable from a broken button.
 
 ## DiagramExportMenu
 
-Taking the figure off the page: five files, one menu. WHY THE MENU DOES THE WORK rather than handing back a format: every one of these exports is the same six steps — find the `<svg>`, walk it with `getComputedStyle` to bake the custom properties into real colours, serialise, rasterise, name the file, hand it to the browser — and only the last two differ between them. A menu that emitted `'png'` and left the caller to do the rest would be a menu that every consumer reimplements, badly, and the interesting half (a serialised SVG resolves `var(--ink)` to nothing and comes out invisible) is exactly the half a caller would not know to write. `onExport` is still there for a page with its own pipeline — a server-side renderer, a different frame size — and taking it turns everything below into a no-op. What each format actually is, stated rather than implied. **SVG** is the artwork with resolved colours. It is editable and it is the only lossless one, but it carries no web fonts: a machine without the family renders it in a fallback, so type metrics will differ. **PNG, JPEG and WebP** are the browser's own rasteriser re-drawing that SVG at 2×. Not a screenshot — antialiasing and any effect a page stylesheet applied from OUTSIDE the `<svg>` are not in it. **JPEG has no alpha**, so it is flattened onto the resolved paper colour rather than onto black, which is what a transparent PNG becomes when a format with no transparency is asked to hold it. **The share card** is a 1200 × 630 frame with the title on it and the whole diagram letterboxed inside — never cropped. A card that cropped to fill the frame would be a picture of a different diagram.
+Taking the figure off the page: five files, one menu. WHY THE MENU DOES THE WORK rather than handing back a format: every one of these exports is the same six steps — find the `<svg>`, walk it with `getComputedStyle` to bake the custom properties into real colours, serialise, rasterise, name the file, hand it to the browser — and only the last two differ between them. A menu that emitted `'png'` and left the caller to do the rest would be a menu that every consumer reimplements, badly, and the interesting half (a serialised SVG resolves `var(--ink)` to nothing and comes out invisible) is exactly the half a caller would not know to write. `onExport` is still there for a page with its own pipeline — a server-side renderer, a different frame size — and taking it turns everything below into a no-op, which is why a result from that path says `source: 'caller'`: this component cannot see whether the handler produced a file, so it does not report that it did. What each format actually is, stated rather than implied. **SVG** is the artwork with resolved colours. It is editable and it is the only lossless one, but it carries no web fonts: a machine without the family renders it in a fallback, so type metrics will differ. **The ground** is the reader's own surface unless `background` says otherwise. `background={null}` exports on transparency — for a figure being dropped onto a coloured page — except in JPEG, which has no alpha and is flattened onto paper whatever is asked for. **PNG, JPEG and WebP** are the browser's own rasteriser re-drawing that SVG at 2×. Not a screenshot — antialiasing and any effect a page stylesheet applied from OUTSIDE the `<svg>` are not in it. **JPEG has no alpha**, so it is flattened onto the resolved paper colour rather than onto black, which is what a transparent PNG becomes when a format with no transparency is asked to hold it. **The share card** is a 1200 × 630 frame with the title on it and the whole diagram letterboxed inside — never cropped. A card that cropped to fill the frame would be a picture of a different diagram.
 
 ### Props
 
@@ -26,8 +51,9 @@ Taking the figure off the page: five files, one menu. WHY THE MENU DOES THE WORK
 - `title` (required) — `string`. Names the file, and is printed on the share card.
 - `trigger` — `ReactNode`. Replaces the trigger.
 - `className` — `string`.
-- `onExport` — `(format: ExportFormat) => void | Promise<void>`. Runs instead of the built-in export — for a caller with its own pipeline.
+- `onExport` — `(format: ExportFormat) => void | Promise<void>`. Runs instead of the built-in export — for a caller with its own pipeline. Taking it turns everything below into a no-op, INCLUDING the part that knows whether a file was produced: a result from this path reports `source: 'caller'` and an `ok` that means only "your handler resolved".
 - `onResult` — `(result: ExportResult) => void`. Told what happened, so a page can raise a toast.
+- `background` — `string | null`. Painted behind the artwork. Defaults to the surface the reader is looking at; `null` exports on a transparent ground. JPEG has no alpha channel, so it is flattened onto the reader's own paper whatever this says — a transparent JPEG is a black one.
 
 ## exportFigure
 

package/dist/agent/DiagramInspector.md

@@ -4,7 +4,7 @@ What the reader just picked, written out beside the picture.
 
 - Group: Diagrams
 - Import: `import { DiagramInspector } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/diagram-inspector/
 - Related: card, diagram-canvas
 
@@ -12,6 +12,28 @@ What the reader just picked, written out beside the picture.
 
 A node holds about eight words before it stops being a node. Everything past those — the port, the owner, the six relationships — belongs here.
 
+## Anatomy
+
+- **Region** (required) — A <section> named "<title> details" with aria-live="polite", on a panel plate. A region and not a dialog: nothing traps focus and nothing demands dismissal, because the reader clicked a node rather than opening a window.
+- **Heading** (required) — The eyebrow over the title — what KIND of thing this is, then what it is called. The eyebrow is where the plate’s own kicker word belongs, so the panel and the picture say the same thing about the same node.
+- **Facts** — A definition list, one term and value per row, the value settable in mono for an id, a path, a port. A list rather than a grid of divs, because a grid tells a screen reader nothing about which value belongs to which label.
+- **Relationships** — One row per edge the node takes part in, each becoming a real button when it carries onSelect. The arrow glyph is hidden and the direction spelled out beside it, so "to" and "from" are heard rather than guessed.
+- **Close** — A small control named for what it does — clearing the selection, not closing a window. It is the only thing that can empty the panel.
+- **Actions** — A wrap of caller-supplied buttons under the facts: copy the id, open the source the node was read out of.
+
+## Best practices
+
+### Do
+
+- Pair it with the figure’s onSelectNode. That is what turns the hidden summary list into real buttons, and without it the panel can only ever be filled by a pointer — the plates in the picture are presentational by construction.
+- Give every relationship an onSelect. The rows become buttons and the graph becomes walkable peer by peer, which is how a keyboard reader gets from a node to the node it is connected to without going back through the list.
+- Move the long facts here and leave about eight words on the plate. A box holding a port, an owning team and a file path grows to fit all three rather than clipping them, and a figure of boxes that size is a document with lines drawn on it.
+
+### Don’t
+
+- Two facts sharing a label are two rows, and neither says which is which. They are keyed by position, so both render — and a panel with "Source" twice leaves the reader deducing from the values what the labels should have said. Name them apart when they mean different things.
+- floating pins the panel over the surface, so it covers that corner of the diagram for as long as it is mounted. It has no dismissal contract of its own — passing no onClose leaves the reader nothing to press and the corner hidden until the selection changes.
+
 ## Accessibility
 
 - A labelled region with aria-live="polite", not a dialog: the reader clicked a node, they did not open anything, so focus is never trapped or demanded.

package/dist/agent/DiagramLegend.md

@@ -4,7 +4,7 @@ The key: which drawn form means which kind of thing.
 
 - Group: Diagrams
 - Import: `import { DiagramLegend } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/diagram-legend/
 - Related: architecture-figure, lifecycle-figure
 
@@ -12,6 +12,27 @@ The key: which drawn form means which kind of thing.
 
 Not optional furniture in a monochrome system. When a queue and a cache differ by a sigil rather than a colour, this is the only place a reader is told what the sigil means.
 
+## Anatomy
+
+- **Row** (required) — A wrapping, baseline-aligned row over a top rule. Inside a figure it sits between the picture and the conclusion cards, which is where a reader looks after failing to recognise a mark.
+- **Kicker** — The word Key before the row. title={null} drops it for a bare row, and the list keeps that word as its own accessible name either way.
+- **List** (required) — A <ul> of pairs rather than a row of spans, so the count is part of what a screen reader says about it — "list, six items" is the first useful fact about a key.
+- **Sample** (required) — A 14 × 14 svg carrying the entry’s own markup, hidden from assistive technology. Markup rather than a name from a fixed list, because a key has to show the SAME mark the figure drew.
+- **Label** (required) — The word beside the mark, in the meta voice. The standard builders take it from the same table the plate’s eyebrow prints, so a plate reading SERVICE is never explained by a key reading Datastore.
+
+## Best practices
+
+### Do
+
+- Build the entries with kindLegend, variantLegend or stateLegend. They are made out of the renderers’ own drawing code, so the key cannot come to show a mark the figure does not draw or a word the plate does not print.
+- Leave a figure’s legend at "auto". It lists only the kinds actually drawn; "all" prints seven kinds beside a figure using three, which is four claims the picture does not support.
+- Pass title={null} when the key sits under a caption that already says what it is. The list keeps Key as its accessible name, so the kicker can go without the row losing its name.
+
+### Don’t
+
+- A key is not where a distinction is MADE. The two state tokens are the only hues these figures spend and each terminal is also its own plate shape — a difference carried by colour alone is one a reader can only look up, an entry at a time, after noticing there is a key at all.
+- legend="hidden" is not free on a figure of tagged plates. A plate prints its tag OR the kind word in the same eyebrow slot and the tag wins, so on a tagged plate the kind is carried by the sigil alone — hiding the key takes the only thing that teaches that sigil off the page.
+
 ## Accessibility
 
 - A list of pairs rather than a row of spans, so the count is part of what a screen reader says about it.

package/dist/agent/DiagramMinimap.md

@@ -4,7 +4,7 @@ Where you are in something bigger than the window.
 
 - Group: Diagrams
 - Import: `import { DiagramMinimap } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/diagram-minimap/
 - Related: diagram-canvas
 
@@ -12,18 +12,39 @@ Where you are in something bigger than the window.
 
 Pairs with DiagramCanvas. The viewport rectangle is derived from the canvas’s own view, never stored — a map that disagrees with its territory is worse than none.
 
+## Anatomy
+
+- **Map frame** (required) — A fixed-width plate — 200px unless width says otherwise — whose height follows the artwork’s own aspect ratio, named as a group so it is not an unlabelled box beside the figure.
+- **Miniature** (required) — The children under a CSS scale of width over content.width, anchored top-left, hidden from assistive technology and transparent to the pointer. Drawn only once content has a size — at width 0 the scale would be 1 and the miniature would be the artwork’s top-left corner at full size. It answers "what is there" at a glance and nothing more.
+- **Viewport rectangle** (required) — An accent-washed rectangle computed from the canvas’s view and the map’s scale, clipped to the plate so a viewport panned past the artwork stops claiming a map that reaches further, and floored at a few pixels so a deep zoom still leaves something on screen to see. It is derived on every render and never stored.
+- **Seek layer** — The transparent layer over the map that turns a press, or a drag that STARTED on it, into a point in CONTENT coordinates and hands it to onSeek. A button pressed elsewhere and dragged across it moves nothing. Nor does the map itself — it has no authority over the view.
+
+## Best practices
+
+### Do
+
+- Feed it the canvas’s own onViewChange. The rectangle is arithmetic on those three numbers, so a map wired that way cannot disagree with the frame it maps — and keeping a second copy of where the viewport is, is exactly how one comes to.
+- Measure content at the artwork’s natural CSS size. Everything here is scaled by width over content.width, so a wrong content width scales the miniature and the rectangle by the same wrong factor: the map still looks plausible and points at the wrong part of the picture. A width of 0 draws an empty plate instead, which is what a measurement that has not landed yet should look like.
+- Let the canvas say how big the frame is. Every view a DiagramCanvas emits carries the frame it was measured against, so passing onViewChange through is enough — the frame prop is for a frame this component cannot be told about, and a hand-declared one is the single number that makes the rectangle lie.
+- Send onSeek straight to the canvas handle’s centerOn. The point arrives in content coordinates, which is the space centerOn already takes, so recentring needs no conversion of your own.
+
+### Don’t
+
+- It is pointer-only and hidden from assistive technology: no tab stop, no keys, and the miniature deliberately publishes nothing because the figure it mirrors already does. The canvas’s arrow keys stay the keyboard’s route to a far corner, so the minimap must never be the only way to reach one.
+- The miniature is the same markup shrunk, not a simplified drawing — every label goes down with it, so a wide figure at 200px is a shape rather than a reading copy. It answers where you are; what a node says is the figure’s job.
+
 ## Accessibility
 
 - The miniature is aria-hidden. The figure it mirrors already publishes its own summary, and a second copy would read the whole diagram out twice.
 
 ## DiagramMinimap
 
-Where you are in something bigger than the window. Two things at once, and both are needed: a miniature of the whole artwork, and a rectangle showing which part of it the frame is currently over. The miniature alone answers "what is there"; the rectangle answers "and where am I", which is the question a reader who has just panned twice actually has. THE RECTANGLE IS DERIVED, never stored. Its position comes out of the canvas's own view — the same three numbers the canvas is already transforming by — divided by the map's scale. Keeping a second copy of "where the viewport is" is how a minimap comes to disagree with the thing it is a map of, and a map that disagrees is worse than none. CLICKING RECENTRES rather than jumping. `onSeek` reports a point in CONTENT coordinates, which is what a canvas's `centerOn` takes. The minimap does not move anything itself: it has no authority over the view, it only says where the reader pointed.
+Where you are in something bigger than the window. Two things at once, and both are needed: a miniature of the whole artwork, and a rectangle showing which part of it the frame is currently over. The miniature alone answers "what is there"; the rectangle answers "and where am I", which is the question a reader who has just panned twice actually has. THE RECTANGLE IS DERIVED, never stored. Its position comes out of the canvas's own view — the same three numbers the canvas is already transforming by — divided by the map's scale, and clamped to the plate: a viewport that has been panned past the edge of the artwork is a viewport half over blank paper, and drawing the rectangle out there claims the map extends somewhere it does not. Keeping a second copy of "where the viewport is" is how a minimap comes to disagree with the thing it is a map of, and a map that disagrees is worse than none. NOTHING IS DRAWN UNTIL THE ARTWORK HAS A SIZE. `content` is usually a measurement, and a measurement's first value is zero — so the scale would be 1, the miniature would be the artwork's top-left corner at full size, and the rectangle would sit over it meaning nothing. An empty plate for one frame is the honest version of "not yet". CLICKING RECENTRES rather than jumping. `onSeek` reports a point in CONTENT coordinates, which is what a canvas's `centerOn` takes. The minimap does not move anything itself: it has no authority over the view, it only says where the reader pointed. A drag keeps seeking, and only a drag that STARTED on the map does — a button held down somewhere else and dragged across is not this component's gesture to answer.
 
 ### Props
 
 - `content` (required) — `{ width: number; height: number }`. The whole artwork, at its natural size in CSS pixels.
-- `frame` (required) — `{ width: number; height: number }`. The frame the artwork is being looked at through, in CSS pixels.
+- `frame` — `{ width: number; height: number }`. The frame the artwork is being looked at through, in CSS pixels. Optional because a `DiagramCanvas` now reports its own frame on every view it emits: wire `onViewChange` straight through and this is already right. Pass it only for a frame this component cannot be told about.
 - `view` (required) — `CanvasView`. Where that frame currently sits — a `DiagramCanvas`'s `onViewChange`.
 - `children` — `ReactNode`. A miniature of the artwork. Usually the same figure, rendered again.
 - `onSeek` — `(x: number, y: number) => void`. Called with a point in CONTENT coordinates when the reader picks one.
@@ -39,7 +60,6 @@ const [view, setView] = useState({ scale: 1, x: 0, y: 0 })
 // …
 <DiagramMinimap
   content={{ width: 1400, height: 620 }}
-  frame={{ width: 720, height: 400 }}
   view={view}
   onSeek={(x, y) => canvas.current?.centerOn(x, y)}
 >

package/dist/agent/DiagramToolbar.md

@@ -4,7 +4,7 @@ A bar of actions belonging to the surface underneath them.
 
 - Group: Diagrams
 - Import: `import { DiagramToolbar } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/diagram-toolbar/
 - Related: floating-icon-button, diagram-export-menu
 
@@ -12,6 +12,28 @@ A bar of actions belonging to the surface underneath them.
 
 FloatingIconButton is one pinned action. This is the container for several, so they read as one object rather than as a scatter.
 
+## Anatomy
+
+- **Bar** (required) — role="toolbar" with a horizontal orientation, on a panel plate with a hairline and the system’s corner. One plate and one border is what makes six pinned buttons read as one object instead of as six.
+- **Name** (required) — label, which becomes the bar’s accessible name. It is a required prop with no default, because a toolbar that announces its role and nothing else is a group a screen reader cannot tell from the next one.
+- **Group** (required) — DiagramToolbarGroup: one run of related controls, divided by a hairline on its leading edge rather than by space. The first group carries no rule, so the bar does not open with a divider.
+- **Controls** (required) — The children, at whatever size the caller gives them. The bar sets the gap and paints no state of its own — a button in here is the same button it is anywhere else.
+- **Pin** — placement="floating" takes the bar out of the flow and pins it to the top edge of the nearest POSITIONED ancestor, at the sticky rank — under every anchored panel and every dialog — with align choosing the corner. placement="inline" leaves it in the flow and pins nothing.
+
+## Best practices
+
+### Do
+
+- Give label the bar’s job rather than its shape — "Diagram actions", not "Toolbar" — because a page with a figure and a table otherwise announces two toolbars and distinguishes neither.
+- Divide with DiagramToolbarGroup rather than with a gap. The rule is drawn on the group, and a gap wide enough to read as a boundary is also wide enough to stop the bar reading as one object, which is the reason the controls were collected at all.
+- Keep it to a handful of controls. There is no roving focus here, so Tab visits every one of them: ten actions in the bar is ten stops between the reader and the rest of the page.
+
+### Don’t
+
+- A floating bar sits over the surface, not beside it. Whatever is in that corner of the figure is underneath it — pad the surface, or use placement="inline" and let the bar take its own row.
+- role="toolbar" is a promise about the keyboard as well as a name: a reader is told this is a toolbar and expects the arrow keys to move inside it. For two buttons that merely sit next to each other, a plain div makes no promise this component then has to keep.
+- A floating bar is a SIBLING of the canvas inside a positioned wrapper, never a child of it. Everything handed to DiagramCanvas renders inside the transformed stage, so a bar passed as a child zooms and pans away with the diagram it was put there to control — and with no positioned ancestor at all it pins to whichever box further up the page happens to be one.
+
 ## Accessibility
 
 - role="toolbar" announces a toolbar rather than six unrelated buttons. It does not implement roving focus — Tab visits every control, which is honest for a bar of three.

package/dist/agent/Dialog.md

@@ -4,10 +4,33 @@ A modal surface: portal, scrim, centred panel.
 
 - Group: Overlays
 - Import: `import { Dialog } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/dialog/
 - Related: dropdown-menu, tooltip
 
+## Anatomy
+
+- **Scrim** (required) — The full-viewport --scrim layer at --z-overlay (200). It is what a click outside lands on, and it paints over everything the page had pinned below that rank — a FloatingIconButton at 100 included. Not over an anchored panel: those sit at 220 precisely so a Select opened inside this dialog is still reachable.
+- **Panel** (required) — The centred box at --z-modal (210), capped at min(92vw, 32rem) wide and 85vh tall, scrolling its own body past that. It centres itself with a translate, which has consequences for anything fixed inside it.
+- **Title** (required) — title, rendered as the Radix Title. Always present: when title is omitted a visually hidden one is rendered reading the literal word “Dialog”, and development warns DIALOG_TITLE_MISSING — the fallback exists so an unnamed modal is not shipped, not so one can be.
+- **Description** — description, a quiet line under the title. It shares one wrapper with the title, so hideTitle hides both.
+- **Close** — The 36px X in the top-end corner, rendered while showClose is true (the default) and carrying its own aria-label of “Close”.
+
+## Best practices
+
+### Do
+
+- Pass title even when you set hideTitle: with no title at all the fallback accessible name is the literal string “Dialog”, so every unnamed modal in the app is announced as the same thing — and it passes an automated accessibility check while doing it, which is why development warns instead of leaving it to a review.
+- Wrap the cancelling control in DialogClose rather than flipping your own state — the close then runs through Radix, which returns focus to the trigger instead of dropping it at the top of the document.
+- Keep it to what fits. The panel stops at 32rem by 85vh and scrolls its own body past that, so a form long enough to scroll has become a Sheet, which gets the full height of the viewport, or a page.
+- Leave showClose on unless the panel supplies its own exit: Escape and the scrim are the only other ways out and neither is visible, so showClose={false} on a dialog full of content is a room with an unmarked door.
+
+### Don’t
+
+- An OverlayContainer whose element is not positioned hands the dialog the wrong box: naming a container switches the panel from fixed to absolute, and an unpositioned container sends it to the nearest positioned ancestor instead — usually the page, which looks like the container was ignored.
+- Two dialogs open at once are ordered by the DOM, not by a rank: both sit at --z-modal, so the one mounted last paints over the first — a command palette summoned over a dialog lands on top because it opened second, and reversing that order reverses the picture.
+- The panel centres itself with a transform, which makes it the containing block for every position: fixed descendant — a FloatingIconButton dropped inside a dialog pins to the panel’s corner rather than the screen’s.
+
 ## Accessibility
 
 - Radix owns the focus trap, Escape, the scroll lock and aria-modal.
@@ -28,11 +51,11 @@ Radix Dialog root + trigger + close, re-exported as typed passthroughs.
 
 ## DialogContent
 
-A modal surface: portal → scrim → centred panel. Radix owns the focus trap, the escape key, the scroll lock and the `aria-modal` wiring — all of which a hand-rolled dialog gets subtly wrong, usually by leaving focus behind in the page underneath. Radix requires a `Dialog.Title` whether or not one is shown, so a dialog without a visible heading still renders a hidden one rather than logging a warning and shipping an unnamed modal.
+A modal surface: portal → scrim → centred panel. Radix owns the focus trap, the escape key, the scroll lock and the `aria-modal` wiring — all of which a hand-rolled dialog gets subtly wrong, usually by leaving focus behind in the page underneath. Radix requires a `Dialog.Title` whether or not one is shown, so a dialog without a visible heading still renders a hidden one rather than shipping an unnamed modal — and warns in development, because the fallback it renders is the literal word "Dialog" and a placeholder that passes an accessibility check is how the problem survives a review. Portals into the element an enclosing `OverlayContainer` names, and switches from viewport positioning to container positioning when there is one. A `fixed` panel covers the page whatever it is portalled into, so honouring the container without that swap would have moved the markup and left the picture unchanged.
 
 ### Props
 
-- `title` — `ReactNode`. Heading text. When omitted, a visually-hidden title is rendered for a11y.
+- `title` — `ReactNode`. Heading text. Pass one even when `hideTitle` is set. Radix requires a title, so omitting it renders a hidden fallback reading the literal word "Dialog" — which satisfies an automated accessibility check and announces every unnamed modal in the application as the same thing. Development says so out loud.
 - `description` — `ReactNode`. Sub-heading under the title.
 - `className` — `string`.
 - `showClose` — `boolean` default `true`. Show the top-right close control (default true).