@misoto22/folio 0.0.0 → 0.17.0

package/dist/agent/DiagramExportMenu.md

@@ -0,0 +1,65 @@
+# DiagramExportMenu
+
+Taking the figure off the page: PNG, JPEG, WebP, SVG and a 1200×630 share card.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { DiagramExportMenu } from '@misoto22/folio/diagrams'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/diagram-export-menu/
+- Related: dropdown-menu, diagram-toolbar
+
+## When to reach for it
+
+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, 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
+
+- `targetRef` (required) — `RefObject<HTMLElement | SVGSVGElement | null>`. The `<svg>` to export, or an element containing exactly one. A ref rather than a selector, because a page can hold several figures and a selector would export whichever the document happened to reach first.
+- `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. 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
+
+One figure, one format, one file. Exported so a page can wire a keyboard shortcut or its own button to exactly what the menu does, without reimplementing the six steps.
+
+## Types
+
+- `ExportFormat` = `'png' | 'jpeg' | 'webp' | 'svg' | 'share-card'`

package/dist/agent/DiagramInspector.md

@@ -0,0 +1,73 @@
+# DiagramInspector
+
+What the reader just picked, written out beside the picture.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { DiagramInspector } from '@misoto22/folio/diagrams'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/diagram-inspector/
+- Related: card, diagram-canvas
+
+## When to reach for it
+
+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.
+- Relationships are real buttons when they carry onSelect, which is how the graph becomes walkable peer by peer from the keyboard.
+
+## DiagramInspector
+
+What the reader just picked, written out. A diagram can hold about eight words per node before it stops being a diagram and starts being a document with lines drawn on it. Everything past those eight — the port, the owning team, the file it was read out of, the six relationships it takes part in — belongs beside the picture rather than inside it, and this is that place. NOT A DIALOG, and that is deliberate. An inspector is a REGION that changes with the selection, not a modal. Giving it `role="dialog"` would trap focus and demand dismissal for something the reader never opened — they clicked a node, and the panel followed. So it is a labelled region with `aria-live="polite"`, which is what makes a screen reader announce the new selection without stealing the cursor from whatever the reader was doing. The relationships are real buttons when they carry `onSelect`, which is how the diagram becomes navigable from the keyboard: a reader can walk the graph peer by peer without ever touching the picture.
+
+### Props
+
+- `eyebrow` — `string`. The kicker over the title — what KIND of thing this panel is showing.
+- `title` (required) — `string`.
+- `description` — `ReactNode`.
+- `facts` — `InspectorFact[]` default `[]`.
+- `links` — `InspectorLink[]` default `[]`.
+- `actions` — `ReactNode`. Buttons under the facts — copy a link, open the source.
+- `onClose` — `() => void`.
+- `className` — `string`.
+- `floating` — `boolean`. Renders as a floating panel over the surface rather than in the flow.
+
+## Examples
+
+```tsx
+<DiagramInspector
+  eyebrow="Service"
+  title="API Server"
+  description="FastAPI, behind the load balancer."
+  facts={[
+    { label: 'Port', value: '8000', mono: true },
+    { label: 'Id', value: 'api', mono: true },
+  ]}
+  links={[{ direction: 'out', label: 'SQL', peer: 'PostgreSQL' }]}
+  onClose={() => setSelected(null)}
+/>
+```

package/dist/agent/DiagramLegend.md

@@ -0,0 +1,56 @@
+# DiagramLegend
+
+The key: which drawn form means which kind of thing.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { DiagramLegend } from '@misoto22/folio/diagrams'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/diagram-legend/
+- Related: architecture-figure, lifecycle-figure
+
+## When to reach for it
+
+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.
+- kindLegend, variantLegend and stateLegend build the standard sets out of the renderers’ own drawing code, so the key can never drift from the figure.
+
+## DiagramLegend
+
+The key: which drawn form means which kind of thing. Not optional furniture in a monochrome system, and this is the one place that has to be said plainly. When the difference between a queue and a cache is a sigil rather than a colour, the key is the only place a reader is told what the sigil means — a figure whose forms are undocumented is a figure whose forms might as well not have been drawn. A `<ul>` rather than a row of `<span>`s: it is a list of pairs, and the count is part of what a screen reader should say about it.
+
+### Props
+
+- `entries` (required) — `DiagramLegendEntry[]`.
+- `title` — `string | null` default `'Key'`. The kicker before the row. Pass null for a bare row.
+- `className` — `string`.
+
+## Examples
+
+```tsx
+<DiagramLegend entries={kindLegend(['backend', 'database'])} />
+```

package/dist/agent/DiagramMinimap.md

@@ -0,0 +1,69 @@
+# DiagramMinimap
+
+Where you are in something bigger than the window.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { DiagramMinimap } from '@misoto22/folio/diagrams'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/diagram-minimap/
+- Related: diagram-canvas
+
+## When to reach for it
+
+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, 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` — `{ 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.
+- `width` — `number` default `200`. How wide the map is, in CSS pixels. Height follows the aspect ratio.
+- `className` — `string`.
+- `label` — `string` default `'Diagram overview'`.
+
+## Examples
+
+```tsx
+const canvas = useRef<DiagramCanvasHandle>(null)
+const [view, setView] = useState({ scale: 1, x: 0, y: 0 })
+// …
+<DiagramMinimap
+  content={{ width: 1400, height: 620 }}
+  view={view}
+  onSeek={(x, y) => canvas.current?.centerOn(x, y)}
+>
+  <ArchitectureFigure spec={spec} heading={false} legend="hidden" cards={false} />
+</DiagramMinimap>
+```

package/dist/agent/DiagramToolbar.md

@@ -0,0 +1,70 @@
+# DiagramToolbar
+
+A bar of actions belonging to the surface underneath them.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { DiagramToolbar } from '@misoto22/folio/diagrams'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/diagram-toolbar/
+- Related: floating-icon-button, diagram-export-menu
+
+## When to reach for it
+
+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.
+
+## DiagramToolbar
+
+A bar of actions that belong to the surface underneath them. The package already has `FloatingIconButton` for ONE pinned action. This is the container for several — which is a different problem, because several pinned buttons need to read as one object rather than as a scatter: one plate, one border, hairlines between the groups, and a single `role="toolbar"` so a screen reader announces a toolbar instead of six unrelated buttons. `role="toolbar"` also changes the keyboard contract, and callers should know what they are opting into: arrow keys are expected to move between the controls and Tab is expected to leave the bar. This component does not implement roving focus for you — a bar of three buttons where Tab visits all three is honest and fine — so pass `placement="inline"` and skip the role by using a plain `<div>` if that is not what you want.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `placement` — `'inline' | 'floating'` default `'inline'`. Where it sits. `floating` pins it over the surface it acts on.
+- `align` — `'start' | 'end'` default `'end'`. Which corner a floating bar pins to.
+- `label` (required) — `string`.
+
+Also accepts: `Omit<ComponentProps<'div'>, 'children'>`.
+
+## DiagramToolbarGroup
+
+One run of related controls inside the bar. Separated by a hairline rather than by space, because a gap large enough to read as a group boundary is also large enough to stop the bar reading as one object — which is the whole reason the controls were collected into a bar.
+
+## Examples
+
+```tsx
+<DiagramToolbar label="Diagram actions" placement="floating">
+  <DiagramToolbarGroup>
+    <Button size="sm" variant="ghost">Theme</Button>
+  </DiagramToolbarGroup>
+  <DiagramToolbarGroup>
+    <DiagramExportMenu targetRef={svg} title="Request path" />
+  </DiagramToolbarGroup>
+</DiagramToolbar>
+```

package/dist/agent/Dialog.md

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

package/dist/agent/DropdownMenu.md

@@ -0,0 +1,110 @@
+# DropdownMenu
+
+A menu of actions.
+
+- Kind: component
+- Group: Overlays
+- Import: `import { DropdownMenu } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/dropdown-menu/
+- Related: dialog, select
+
+## When to reach for it
+
+Actions. Items that navigate belong in a nav; items that set a value are a Select or a RadioGroup.
+
+## Anatomy
+
+- **Trigger** (required) — A passthrough to Radix, which renders its own bare button unless you pass asChild. It carries aria-haspopup and data-state, which is what lets a Button show that its menu is open.
+- **Panel** (required) — The portalled menu: at least 11rem wide, 6px off the trigger, colliding with 8px of padding against the viewport or the OverlayContainer frame. It has no max height, so it flips rather than scrolls.
+- **Item** — A row. icon takes either spelling — the icon component, sized to 16px here, or a rendered element, placed as given; destructive paints the row --danger; disabled drops pointer events and the opacity.
+- **Label** — A mono eyebrow, on its own. Visual only — Radix renders it as a plain div, and the arrow keys skip it. DropdownMenuGroup is the one that heads rows: it renders role="group" and points its aria-labelledby at this.
+- **Group** — A named section: role="group" around the rows, with label rendered inside it as the Label and named through aria-labelledby. The wiring is the component’s job because a caller doing it by hand has to invent an id.
+- **Separator** — A hairline between groups, and a real role="separator" — which a menu permits, unlike the listbox a Command palette is built on.
+
+## Best practices
+
+### Do
+
+- Pass icon the component — icon={Settings} — and let the row size it, so a menu of ten rows draws ten icons at one size rather than ten sizes. The element spelling is accepted too, and used to be the exact opposite of what CommandItem took one import away.
+- Give the trigger asChild and a real Button: without it Radix renders its own unstyled button, and the menu ends up hanging off a control that is not part of the system’s set.
+- Hold a dialog’s open state yourself and call event.preventDefault() in the item’s onSelect — selecting a row closes the menu, and Radix’s close moves focus back to the trigger, which arrives after the dialog has claimed it and pulls the reader straight back out.
+- Stop at about a dozen rows. There is no max height on the panel, so a longer menu grows until it hits the collision padding and flips above the trigger — SearchableMenu is the same list once it has outgrown this one.
+
+### Don’t
+
+- Radix defaults modal to true and nothing here overrides it, so while the menu is open the page behind is scroll-locked and its pointer events are off — a menu is not the place for something the reader is meant to consult the page while using.
+- A bare DropdownMenuLabel over rows is a picture of a heading: Radix’s MenuLabel is a plain div with no role and nothing tying it to what follows, so the sections a sighted reader sees arrive as one undivided list. DropdownMenuGroup renders both halves and wires them together.
+- There is no checkbox item, radio item or submenu in this package’s exports — a menu that needs a checked state has to import from @radix-ui/react-dropdown-menu directly, and that row arrives with none of this file’s styling on 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.
+- Highlight is driven by data-highlighted, which covers hover AND keyboard focus — styling :hover alone leaves the keyboard user unable to see where they are.
+- DropdownMenuGroup segments the menu for a screen reader as well as for the eye; a bare Label does it for the eye alone.
+
+## Keyboard
+
+- Enter / Space / ↓ — Opens the menu and lands on the first item.
+- ↑ / ↓ — Moves between items.
+- a–z — Jumps to the next item starting with that letter.
+- Escape — Closes the menu and returns focus to the trigger.
+
+## DropdownMenu
+
+Radix DropdownMenu root + trigger, re-exported as typed passthroughs.
+
+## DropdownMenuTrigger
+
+## DropdownMenuContent
+
+A menu surface. A menu is a list of ACTIONS. If the items navigate somewhere, they belong in a nav; if they set a value, that is a `Select` or a `RadioGroup` — this package ships no checkbox or radio menu item, and a plain item pretending to be a choice loses the checked state a screen reader needs.
+
+Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Content>`.
+
+## DropdownMenuItem
+
+A menu row. Highlight is driven by Radix's `data-highlighted`, which covers both pointer hover and keyboard focus — styling `:hover` alone leaves the keyboard user unable to see where they are.
+
+### Props
+
+- `icon` — `RemixiconComponentType | ReactNode`. Optional leading icon, rendered before the label. Either spelling: `icon={Settings}` passes the component and this sizes it, `icon={<Settings size={16} />}` passes the element and this places it. The two used to mean opposite things one import apart — `CommandItem.icon` took the element while this took the component — and the wrong one did not fail a type check into anything actionable, it failed at render.
+- `destructive` — `boolean` default `false`. Paints the row as destructive. Use for delete, revoke, disconnect.
+
+Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Item>`.
+
+## DropdownMenuSeparator
+
+Hairline divider between menu groups.
+
+## DropdownMenuLabel
+
+Mono eyebrow heading, on its own. Visual only: Radix renders it as a bare `<div>` with no role, so it segments the menu for a reader who can see it and for nobody else. Reach for `DropdownMenuGroup` when the eyebrow is a HEADING over rows; this is right for a line that heads nothing — the signed-in address at the top of an account menu.
+
+## DropdownMenuGroup
+
+A named section of a menu. The eyebrow alone was a picture of a heading. Radix's `MenuLabel` carries no role and no `aria-labelledby` wiring, and `MenuGroup` — which does carry `role="group"` — was not re-exported by this package at all, so a sighted reader saw three labelled sections and a screen-reader user got one undifferentiated list. This renders the group, renders the label inside it, and points the one at the other, which is the whole of the fix and not something a caller should have to remember.
+
+### Props
+
+- `label` — `ReactNode`. The eyebrow over the rows, and the group's accessible name.
+
+Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Group>`.
+
+## Examples
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild><Button variant="secondary">Menu</Button></DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuGroup label="Account">
+      <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+    </DropdownMenuGroup>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem icon={LogOut}>Sign out</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+<DropdownMenuGroup label="Account">
+  <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+</DropdownMenuGroup>
+```

package/dist/agent/EmptyState.md

@@ -0,0 +1,63 @@
+# EmptyState
+
+A collection with nothing in it — yet.
+
+- Kind: component
+- Group: Feedback
+- Import: `import { EmptyState } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/empty-state/
+- Related: error-state, skeleton
+
+## When to reach for it
+
+Nothing went wrong. The copy says what to do, not what failed.
+
+## Anatomy
+
+- **Frame** (required) — A centred column with 80px of padding above and below and --page-pad either side. View-scale, and carrying no role and no live region of its own.
+- **Medallion** — The optional Remix Icon glyph at 24px inside a 56px --stone circle, aria-hidden. Decoration that gives the column something to start from, never the message.
+- **Title** (required) — title in the heading face at --fs-sub, rendered through Heading. level picks the element and defaults to 2; the size does not follow it, so the title is --fs-sub at every level.
+- **Description** — description in --ink-3-aa, capped at 24rem so it stays a readable measure while the column stays centred.
+- **Action** — The one thing to do next, 32px below the description and the only interactive element the frame offers.
+
+## Best practices
+
+### Do
+
+- Announce the swap yourself. This component has no role and no live region, so replacing a SkeletonPage with it removes the region that said “Loading projects” and puts nothing in its place — a screen reader is left at the last thing it heard.
+- Say which kind of empty this is. The same component serves a collection that is new and one that a filter has emptied, and “No projects yet” shown over an active filter tells the reader their projects are gone.
+- Set level from the heading above it. The default of 2 is right directly under a page’s h1; inside a section that already has its own h2, pass 3. Get it wrong and the outline gains a hole a screen reader navigates by.
+
+### Don’t
+
+- Do not show it for a failed request. A reader told the collection is empty acts on it — creating the record they already have, or reporting a data loss that never happened — and the recovery from that costs more than the error page would have.
+- Do not put it inside a card or a panel. 160px of vertical padding is sized to stand in for a view, and in a bordered box it reads as a box with a hole in it.
+- Do not write a paragraph into description. It is capped at 24rem and centred, so long copy becomes a narrow ragged column that the eye returns from before the sentence that mattered.
+
+## EmptyState
+
+A collection with nothing in it — yet. Distinct from `ErrorState`: nothing went wrong here, so the copy says what to do rather than what failed. The two are different components because the shared temptation — one component with a `variant` — produces error pages that read like empty folders.
+
+### Props
+
+- `icon` — `RemixiconComponentType`. Optional Remix Icon glyph, shown muted inside a quiet circle.
+- `title` (required) — `ReactNode`.
+- `description` — `ReactNode`.
+- `action` — `ReactNode`. The one thing to do next. An empty state without an action is a dead end.
+- `level` — `HeadingLevel` default `2`. The heading level `title` opens, in the document the empty state lands in. Defaults to `2`, which is the placement this component is sized for: it stands in for a whole view inside a page that already has an `h1`, so the level below that one is the level that does not leave a hole in heading navigation. Under a section that already has its own `h2`, pass `3`. The default was `3` and fixed, which was wrong in the ordinary case and impossible to correct — the documentation could name the rule but a caller had no prop to follow it with. `2` is the common case rather than a compromise, and it is optional rather than required because the correct placement has one answer often enough that making every existing call site restate it would buy nothing. The size does not follow the level. `title` renders at `--fs-sub` at every level, because moving a state down the outline is a fact about the document and not a request for smaller type.
+
+Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.
+
+## Examples
+
+```tsx
+<EmptyState
+  icon={Inbox}
+  title="No projects yet"
+  description="Create your first project to get started."
+  action={<Button>New project</Button>}
+/>
+// Inside a section that already has its own heading.
+<EmptyState level={3} title="No invoices yet" />
+```