@misoto22/folio 0.0.0 → 0.16.0

package/dist/agent/ErrorState.md

@@ -0,0 +1,67 @@
+# ErrorState
+
+A page that could not be shown.
+
+- Kind: component
+- Group: Feedback
+- Import: `import { ErrorState } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/error-state/
+- Related: empty-state, alert
+
+## Anatomy
+
+- **Screen** (required) — A section at least one viewport tall, painting its own --paper ground and holding 96px of clearance for a header. It is a page, not a block.
+- **Code** (required) — code at the top of the type ladder, aria-hidden. The largest thing on the screen and the one thing a screen reader is never told.
+- **Heading** (required) — heading through Heading at --fs-heading, and the first thing said aloud. level defaults to 1 because this replaces the page; the size is fixed, so an error state demoted to an h2 is the same size it was.
+- **Message** (required) — message at --measure-record, which is where the explanation of what happened goes.
+- **Action** (required) — The way back. Required rather than optional, and the only focusable thing on the screen.
+
+## Best practices
+
+### Do
+
+- Render it instead of the page, not inside it. It is a full viewport with its own ground and its own top clearance, so nested in a layout that already has a header it adds a second screen of blank below the fold.
+- Announce it or move focus into it on a client-side failure. There is no role and no live region here, so a route that swaps the whole screen for this one changes everything a sighted reader can see and says nothing at all.
+- Point action at a real destination rather than at history. A reader often arrives at an error page cold or from a link, so going back returns them to the page that just failed, or to nothing.
+
+### Don’t
+
+- Do not leave level at 1 inside an app shell that already has an h1. Two h1s on one document leave a heading list that no longer says which one is the page — pass level={2} for a state rendered into a shell rather than instead of one.
+- Do not put a request id, a trace or a sentence into code. It is set at --fs-title with leading-none and it is aria-hidden, so anything long becomes the biggest object on the page and is simultaneously invisible to the reader most likely to have to quote it.
+- Do not use it when one panel failed and the rest of the page still works. Replacing the whole screen throws away the navigation the reader needed to get out; an Alert inside the panel keeps both the error and the way past it.
+
+## Accessibility
+
+- The big status code is aria-hidden; the heading immediately after says the same thing in words.
+
+## ERROR_ACTION_CLASS
+
+The recovery affordance's look, exported so every error page offers the same one rather than each inventing a link style.
+
+## ErrorState
+
+A page that could not be shown. The code is set at the top of the type ladder and marked `aria-hidden` — read aloud, "404" before the sentence explaining it is noise, and the heading immediately after says the same thing in words.
+
+### Props
+
+- `code` (required) — `ReactNode`. The status, set large — "404", "500". Decorative; the heading carries the meaning.
+- `heading` (required) — `ReactNode`.
+- `message` (required) — `ReactNode`.
+- `action` (required) — `ReactNode`. The way back. Render it with ERROR_ACTION_CLASS.
+- `level` — `HeadingLevel` default `1`. The heading level `heading` opens, in the document the error state lands in. Defaults to `1`, and that is not a compromise: this component replaces the page rather than sitting inside one — its own ground, its own viewport, its own top clearance — so the page's single `h1` is the one it renders. Kept as the default, existing call sites render exactly the markup they did. The prop exists because the level was previously fixed, and the one piece of advice this component's documentation gives about headings — do not put it inside a shell that already has an `h1` — was advice a caller had no way to take. Now they do: inside a shell that owns the page heading, pass `2`. The size does not follow the level. `heading` renders at `--fs-heading` at every level; a failure demoted in the outline is the same failure.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+<ErrorState
+  code="404"
+  heading="Page not found"
+  message="The page you're looking for has moved, or never existed."
+  action={<a href="/" className={ERROR_ACTION_CLASS}>Back home</a>}
+/>
+// Inside a shell that already owns the page's h1.
+<ErrorState level={2} code="503" heading="Invoices could not be loaded" … />
+```

package/dist/agent/Evidence.md

@@ -0,0 +1,165 @@
+# Evidence
+
+Expandable traces, source stages, scores and timing summaries.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { EvidenceStatus } from '@misoto22/folio/website'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/evidence/
+
+## When to reach for it
+
+Explain supplied evidence and progress without exposing private prompts or service details.
+
+## Best practices
+
+### Do
+
+- Supply localized labels, descriptive links and meaningful image alternatives.
+
+### Don’t
+
+- Do not put service credentials, routing logic or backend models inside presentation components.
+
+## EvidenceStatus
+
+### Props
+
+- `state` (required) — `EvidenceState`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## ActivityTrace
+
+Tool and job traces share one presentation; the caller supplies truthful, localized labels.
+
+### Props
+
+- `label` (required) — `string`.
+- `items` (required) — `ActivityTraceItem[]`.
+- `waiting` — `boolean`.
+- `waitingLabel` — `string`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## EvidencePanel
+
+### Props
+
+- `title` (required) — `string`.
+- `eyebrow` (required) — `ReactNode`.
+- `state` (required) — `EvidenceState`.
+- `stateLabel` (required) — `string`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.
+
+## EvidenceSelection
+
+### Props
+
+- `label` (required) — `string`.
+- `selectedId` (required) — `string | null`.
+- `options` (required) — `{ id: string; label: string }[]`.
+- `onSelect` (required) — `(id: string) => void`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'>`.
+
+## EvidenceFacts
+
+### Props
+
+- `title` — `ReactNode`.
+- `description` — `ReactNode`.
+- `items` (required) — `DescriptionListItem[]`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.
+
+## EvidenceDisclosure
+
+### Props
+
+- `label` (required) — `string`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## EvidenceQuery
+
+### Props
+
+- `label` (required) — `string`.
+- `query` (required) — `string`.
+- `fingerprint` (required) — `string`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## EvidenceStages
+
+## EvidenceStage
+
+### Props
+
+- `number` (required) — `string`.
+- `state` (required) — `'idle' | 'active' | 'done'`.
+- `stateLabel` (required) — `string`.
+- `title` (required) — `ReactNode`.
+- `description` (required) — `ReactNode`.
+- `time` (required) — `ReactNode`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLLIElement>, 'title'>`.
+
+## EvidenceScores
+
+### Props
+
+- `items` (required) — `EvidenceScore[]`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## SignalFigure
+
+A decorative signature supplied by the host, kept out of the evidence's accessibility tree.
+
+### Props
+
+- `bars` (required) — `{ height: number; opacity: number }[]`.
+- `running` — `boolean`.
+- `settled` — `boolean`.
+- `caption` (required) — `ReactNode`.
+- `detail` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## EvidenceMeter
+
+### Props
+
+- `label` (required) — `string`.
+- `value` — `number | null`. Leave unset while the total is unknown.
+- `valueText` (required) — `ReactNode`.
+- `detail` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## EvidenceDurations
+
+### Props
+
+- `label` (required) — `string`.
+- `total` (required) — `number | null`.
+- `totalText` (required) — `string`.
+- `items` (required) — `EvidenceDuration[]`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## EvidenceSummary
+
+### Props
+
+- `items` (required) — `DescriptionListItem[]`.
+
+Also accepts: `HTMLAttributes<HTMLDListElement>`.
+
+## Types
+
+- `EvidenceState` = `'idle' | 'running' | 'done' | 'failed' | 'restored'`

package/dist/agent/Facet.md

@@ -0,0 +1,107 @@
+# Facet
+
+The same chart once per group, on one shared scale.
+
+- Kind: component
+- Group: Charts
+- Import: `import { Facet } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/facet/
+- Related: line-chart, sparkline
+
+## When to reach for it
+
+Eight series overplot into a hairball in one frame. Two or three series that genuinely need comparing point-for-point still belong in one chart.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure> around the whole grid, named by title. Its empty state has no false escape hatch, unlike a single chart’s: an empty pair of axes is at least a chart, and an empty grid is nothing.
+- **Panel grid** (required) — A role="list" of <li> panels on a CSS auto-fit track. list-none strips the list role in Safari, so it is set back by hand — a grid of twelve plots that does not announce twelve items takes away the reader’s only cue for how far they have to go.
+- **Panel name** — A <p> above each plot. showPanelNames={false} makes it sr-only rather than removing it, because a grid whose panels a screen reader cannot tell apart is one figure with twelve anonymous plots in it.
+- **Shared domain** (required) — panel.domain, computed across the panels that survive the cap and handed to the render function. It is not applied for you: a panel that does not pass it to its own value axis has opted back into independent scales.
+- **Grid-level legend and axis labels** — legend, yLabel and xLabel, printed once above and below the grid. A legend inside every panel is the same three swatches twelve times, restating what the reader learned from the first one.
+- **Overflow note** — The line under a capped grid, saying how many groups were left out or folded. limit is 12 by default and nothing is ever dropped in silence.
+
+## Best practices
+
+### Do
+
+- Pass panel.domain to the panel chart’s value axis. That one line is what the component is for: on independent scales a group peaking at 40 and one peaking at 4,000 draw the same shape, so the comparison is not merely lost, it is inverted — and nothing on screen says so.
+- Name every plotted field in value. It is what the shared domain is measured over, so a panel that draws a series value does not mention can overflow its own axis while the rest of the grid looks correct.
+- Set hideDataTable when the panel charts carry their own. Every chart in the package renders its rows as an sr-only table, so a twelve-panel grid otherwise puts thirteen tables into the accessibility tree.
+- Keep sort="max" for a grid a reader scans and switch to "name" for one they look things up in. Reading order is what a reader takes as ranking, so it is a decision in either direction.
+
+### Don’t
+
+- overflow="fold" is not free. The folded panel is the SUM of the tail at each category and its statistics go into the shared domain, so folding twenty-eight small groups can produce one tall panel that squashes the twelve the reader came for. Use note when the tail is numerous rather than large.
+- Do not turn includeZero off under bars or areas. It is on by default for the same reason a bar axis is anchored at zero — a length read against a truncated baseline overstates every difference, and a grid exists to have its differences compared.
+- Do not reach for it at two or three series. Faceting buys back every individual shape and pays for it with the direct overlay, and crossovers, gaps and shares of one total are exactly what the overlay was for.
+
+## Accessibility
+
+- The shared domain is the default and the whole point: on independent scales a group peaking at 40 and one peaking at 4,000 draw the same shape, and the comparison the reader came for is not merely lost but inverted.
+- Every panel is a figure with its own accessible name, so a screen reader walks eight named charts rather than one unnamed grid.
+- Panels beyond max fold into a stated overflow rather than being dropped, and the count is printed — a grid silently missing four groups is not something a reader can detect.
+- Panel order is a choice the call site makes explicitly through sort, because reading order is what a reader takes as ranking.
+
+## Facet
+
+The same chart repeated once per group, on one shared scale — small multiples. The answer to the question a multi-series chart stops being able to answer at around five series: eight lines in one plot is a hairball, and the reader spends their attention untangling strands instead of reading them. Splitting the same lines across eight small plots costs the direct overlay comparison and buys back every individual shape, which is almost always the better trade — this is Tufte's small multiple, and Observable Plot and Vega-Lite both treat it as a first-class operation for the same reason. Reach for a multi-series `<LineChart>` or `<AreaChart>` instead when the series really do have to be read AGAINST each other — crossovers, gaps, shares of one total — and when there are few enough of them to tell apart. Reach for this when each group has its own shape worth seeing, when the groups are many, or when the reader's question is "which of these is different". What it gets right that a hand-rolled `data.map()` does not: the panels share one domain by default. On independent scales every panel fills its own plot, so a group peaking at 40 and a group peaking at 4,000 come out the same shape — the comparison is not merely lost, it is inverted, and nothing on screen says so. `panel.domain` is that shared scale; the render function has to pass it to the panel's value axis. It also caps the grid, folds or counts the tail, and prints one legend and one axis label instead of twelve.
+
+### Props
+
+- `title` (required) — `string`. What the whole grid shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the grid instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `data` (required) — `TRow[]`. Every row, across every group. The split happens here, not at the call site.
+- `by` (required) — `keyof TRow & string`. The row field the data is split on. One panel per distinct value.
+- `value` (required) — `(keyof TRow & string) | (keyof TRow & string)[]`. The row field, or fields, holding the numbers. This is what the shared domain is measured over and what a statistical sort reads, so it has to name every series a panel draws — a panel that plots a field this does not mention can still overflow its own axis.
+- `xDataKey` — `keyof TRow & string`. The shared category field — the x axis every panel has in common. Feeds the hidden table view, and is what lets `overflow="fold"` add the tail up at each category instead of concatenating it.
+- `scales` — `FacetScales` default `'shared'`. Whether every panel is drawn against one domain or against its own. `"shared"` — the default, and the entire reason this component exists. On independent scales every panel fills its own plot, so a group peaking at 40 and a group peaking at 4,000 come out the same shape, and the comparison the reader opened the grid to make is not merely hard but actively wrong. The shared domain is computed across all the panels that survive the cap and handed to each one as `panel.domain`; a panel that does not pass it to its value axis has opted back into the broken version. `"independent"` is the escape hatch for the case where the panels are not comparable — different units, different orders of magnitude that carry no relation — and where each panel's own shape is the only reading. It is never the safe answer, which is why it is not the default.
+- `domain` — `[number, number]`. Pins the domain outright, ignoring the data and `scales` alike.
+- `includeZero` — `boolean` default `true`. Pulls the shared domain out to include zero. On by default, and the same default Recharts applies on its own: bars and areas read against a truncated baseline overstate every difference in the grid, and a grid exists to be compared. Turn it off when the values live far from zero and the differences between them ARE the reading — temperatures, latencies, ratings out of five.
+- `nice` — `boolean` default `true`. Rounds the domain out so the panels' ticks land on numbers a reader recognises. Off, a shared domain of `[0, 314]` gives ticks at 78.5.
+- `sort` — `FacetSort<TRow>` default `'max'`. The panel order. Defaults to the largest peak first, because that is what makes a grid readable: eye order becomes rank order, and "which of these is the problem" is answered by position before a single axis is read. `"name"` for a grid a reader will look things up in, an explicit array of names for an order the data does not carry — stages, weekdays, severities — and a comparator over `{ name, rows, stats }` for anything else.
+- `order` — `'asc' | 'desc'`. The sort direction. Omit and it follows the sort: A→Z for a name or an explicit list, biggest first for a statistic.
+- `limit` — `number | false` default `12`. How many panels are drawn before the rest are dealt with. Twelve by default rather than unlimited, because the failure this prevents is silent: a `by` field with forty values renders forty plots, each one roughly a postage stamp, and nothing on the page says the grid stopped being readable. `false` lifts the cap when the call site has genuinely decided to draw them all.
+- `overflow` — `FacetOverflow` default `'note'`. What happens to the groups past the cap. `"note"` — the default — draws the top N and prints a line under the grid saying how many are missing. `"fold"` adds one more panel holding the tail summed at each category, the same bargain `BarList`'s "Other" row makes: the total stays true, and one panel absorbs the long tail. Either way a capped grid says so; nothing is dropped in silence.
+- `otherLabel` — `string` default `'Other'`. What the folded panel is called.
+- `overflowNote` — `(info: FacetOverflowInfo) => ReactNode` default `defaultOverflowNote`. Writes the line under a capped grid. The default sentence is English; this is where a translated call site replaces it.
+- `columns` — `'auto' | number` default `'auto'`. How many columns the grid holds at its widest. `"auto"` — the default — fits as many panels as `minPanelWidth` allows and reflows on its own, which is the behaviour a card, a sidebar and a full-width page all need from the same call site. A number caps the count without pinning it: the grid still drops to fewer columns when the container is narrow, rather than shrinking twelve plots to nothing.
+- `minPanelWidth` — `number` default `MIN_PANEL_PX`. How narrow a panel may get before the grid drops a column, in pixels.
+- `legend` — `ReactNode`. One key for the whole grid, printed above it. A legend inside every panel is the same three swatches repeated twelve times, which is ink spent restating what the reader learned from the first panel. Put `<LineChart.Legend>` in one panel and this is unnecessary; put it here and take it out of the panels.
+- `yLabel` — `ReactNode`. The value axis's name, printed once above the grid instead of per panel.
+- `xLabel` — `ReactNode`. The category axis's name, printed once under the grid.
+- `showPanelNames` — `boolean` default `true`. Prints each panel's group name above its plot. On by default. Turning it off only hides the name — it stays in the accessibility tree, because a grid whose panels a screen reader cannot tell apart is a grid with one figure and twelve anonymous plots in it.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view of every row. Worth setting when the panels' own charts already ship theirs — each chart in the package renders its rows as a table too, so a twelve-panel grid can otherwise put thirteen tables in the accessibility tree.
+- `empty` — `ChartEmptyProps`. What the grid shows when the data yields no groups at all. No `false` escape hatch, unlike a single chart's: an empty pair of axes is at least a chart, but an empty grid is nothing — there is no reading for the absence to be.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `children` (required) — `(panel: FacetPanel<TRow>) => ReactNode`. One panel, called once per group. Hand `panel.domain` to the panel chart's value axis. That single line is what the component is for; without it the panels are on independent scales and the grid is decorative.
+
+## Examples
+
+```tsx
+<Facet title="Visitors by channel" data={rows} by="channel" value="visitors" xDataKey="month">
+  {(panel) => (
+    <LineChart title={`${panel.name} visitors`} config={config} data={panel.rows}>
+      <LineChart.XAxis dataKey="month" />
+      <LineChart.YAxis domain={panel.domain} />
+      <LineChart.Line dataKey="visitors" />
+    </LineChart>
+  )}
+</Facet>
+// Biggest first, six panels, the rest summed into one — and the grid says so.
+<Facet
+  title="Requests by endpoint"
+  data={rows}
+  by="endpoint"
+  value="requests"
+  xDataKey="hour"
+  sort="sum"
+  limit={6}
+  overflow="fold"
+  columns={3}
+>
+  {(panel) => <MiniBars rows={panel.rows} domain={panel.domain} />}
+</Facet>
+```

package/dist/agent/Field.md

@@ -0,0 +1,79 @@
+# Field
+
+A labelled form row: label, control, and the one message below it — and, in row layout, the settings row.
+
+- Kind: component
+- Group: Forms
+- Import: `import { Field } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/field/
+- Related: input, select, switch
+
+## When to reach for it
+
+Any labelled control. layout="row" is the settings row — label and description at the inline start, control at the inline end — which is a layout here rather than a second component, because the label wiring, the required marker and the message slot are the same three things either way.
+
+## Anatomy
+
+- **Label** — label, rendered as a Radix <Label> carrying htmlFor and an id. The id is what a trigger names itself from, alongside its own value, and what a group points back at — neither of which htmlFor can do.
+- **Required mark** — The --danger asterisk after the label when required. aria-hidden, but still inside the label’s text, so the accessible name ends “Email *”.
+- **Control slot** (required) — children — ONE element, which the field clones to add id, aria-describedby, aria-required and aria-invalid, and which each control forwards to whatever element carries its role: the trigger for Select, Combobox and DatePicker, the root for a group, the thumb for a Slider. This is the whole contract; everything else is layout.
+- **Description** — description, a second line under the LABEL explaining what the setting does — as distinct from hint, which sits under the control and belongs to the input. It has its own id and joins aria-describedby ahead of the message, so a row with both announces both.
+- **Message** — A single <p> below the control: error if there is one, hint otherwise, never both. It owns the id that aria-describedby points at, and it is --danger or --ink-3-aa accordingly.
+- **Row layout** — layout="row": the label and description in a column at the inline start, the control at the inline end, the message underneath both. The two columns are TOP-aligned — items-start on the block axis, not items-center — so a two-line description does not drag the switch down to the middle of the paragraph, and a column of settings rows keeps every control on the same line as the words that name it.
+
+## Best practices
+
+### Do
+
+- Make children the control itself, not a layout wrapper around it: the wiring is a cloneElement on the single child, so a <div> in between takes the id and the aria-describedby and the label ends up naming a box.
+- Let error carry the invalid state. The field sets aria-invalid on the control, and Input, Textarea, NativeSelect, Select and Combobox all read either spelling through isInvalid, so passing invalid as well states the same fact twice from two places that can disagree.
+- Pass htmlFor, and the same id on the control, whenever something outside the row has to address it — a form library, a scroll-to-first-error, a test. The generated id is a useId value nothing else can predict.
+- Build a settings screen out of layout="row" with description, not out of three hand-rolled divs. The label still reaches the control through the same wiring, so the switch on the far side of the row is named by the words on the near side.
+
+### Don’t
+
+- required here is aria-required and an asterisk, and nothing else: it never reaches the control’s own required attribute, so the browser will not block the submit and the row stays unmarked until you pass error yourself.
+- The words above a RadioGroup or a ToggleGroup name it but do not click through. Both roots are <div role="radiogroup">, which htmlFor does not bind to, so the label is pointed AT by the group instead — a reader who clicks it the way they click "Email" gets nothing, exactly as with a <legend>.
+- Do not reach for description as a second hint. It explains the SETTING and sits under the label; hint explains the INPUT and sits under the control. A row that uses one for the other reads correctly and lands in the wrong place.
+- required is announced on every control here except DatePicker, whose trigger is a plain <button> — a role with nowhere to put aria-required. There the asterisk is the whole of the marking, and a screen reader meets an ordinary optional field.
+
+## Accessibility
+
+- Generates an id when none is given, so the label always points at something.
+- Wires aria-describedby, aria-required and aria-invalid onto the control, so validation is announced and not merely drawn.
+- hint and error are one slot: when a field is wrong, the thing to read is what is wrong with it.
+- description joins aria-describedby ahead of the message, so a settings row announces what the setting does and then what is wrong with it.
+- Every control forwards the wiring to the element that carries its role, so the hint under a Select or a Slider is announced and not merely drawn.
+- The row layout moves the label to the other side of the row and changes nothing about the association, so a settings row with a Switch or a Select in it is named by the words on the near side. Slider is the exception, and the layout cannot fix it: role="slider" is on the THUMB while the field’s label points at the roleless root, so there the label prop on the Slider is still the only name a reader hears.
+
+## Field
+
+A labelled form row: label, control, and the one message below it. The visible message is only half of accessible validation — it must also reach the control. This wires `aria-describedby`, `aria-required` and `aria-invalid` onto the single control child so the requirement and the error are announced, not merely drawn (WCAG 1.3.1 / 3.3.1 / 4.1.2). An earlier version derived the message id from `htmlFor`, which meant a caller who left `htmlFor` off got a hint that was rendered and never announced — the failure was invisible in the browser and total for a screen reader. The id is now generated when it is not supplied. `hint` and `error` are one slot, not two stacked messages: when a field is wrong, the thing to read is what is wrong with it. `description` is a different slot again — it explains the SETTING, not the input, and it is what `layout="row"` puts under the label to make a settings row. **How the wiring reaches the control.** `cloneElement` puts the four attributes on the single child, and each control forwards them to whatever element carries the role — which is the child itself for `Input`, `Textarea`, `NativeSelect`, `Checkbox`, `Switch` and any host element written by hand, and a trigger, a group or a thumb further down for `Select`, `Combobox`, `DatePicker`, `Slider`, `RadioGroup` and `ToggleGroup`. The composites used to drop them on the floor, which drew a hint under a control that never announced it; a wrapper that appears to wire things up and does not is worse than one that never claimed to. The label's own id travels separately, through context, because a name is the one thing a prop cannot carry: a trigger whose text is its VALUE is named by the label AND by itself, so `<Field label="Region"><Select/></Field>` announces "Region, Australia" rather than either half. Three things stay out of reach, and each of them is the control's own markup rather than a gap in this wiring. A `<label for>` binds only to a labellable element, so the words do not click through to a `RadioGroup`, a `ToggleGroup` or a `Slider`: the first two are a `role="radiogroup"` named by pointing back at the label instead, exactly as a `<legend>` is, and the third carries `role="slider"` on a thumb below a roleless root. `required` reaches a control as `aria-required`, which `DatePicker`'s plain `<button>` trigger and a multiple-value `ToggleGroup`'s `role="toolbar"` have nowhere to put; there the asterisk is the only marker. And `aria-invalid` reaches `Slider`'s root rather than its thumb, so an errored slider is drawn wrong without being announced wrong. Each composite still takes its own `label` prop — that is what names it standing outside a field, and `Select`, `Combobox` and `DatePicker` warn when it is blank. It is no longer used INSTEAD of this one's. What no wiring can reach, the field says out loud in development rather than failing silently: `FIELD_CONTROL_NOT_LABELLABLE` when the child is a host element a label cannot bind to — the `<div>` wrapper that takes the id and leaves the control inside it with nothing — and `FIELD_CONTROL_NOT_WIRED` when there is no single element to wire at all.
+
+### Props
+
+- `label` — `ReactNode`. Visible label text; renders a `--danger` asterisk when `required`.
+- `htmlFor` — `string`. The control's `id`. Optional: when omitted, the field generates one and puts it on the control child itself, so the label still points at something. Pass it explicitly when the id has to be stable across renders — a form library referencing it by name, say.
+- `description` — `ReactNode`. A second line under the LABEL, explaining what the setting does. Distinct from `hint`, which sits under the control and belongs to the input — "We never share it". This belongs to the thing being switched on, and it is what makes a settings row a settings row. Both reach the control through `aria-describedby`, so a row that has a description and an error announces both.
+- `hint` — `ReactNode`. Helper copy shown below the control when there is no `error`.
+- `error` — `ReactNode`. Validation message; takes precedence over `hint` when present.
+- `required` — `boolean`.
+- `layout` — `FieldLayout` default `'stacked'`. Where the control sits relative to its label. See FieldLayout.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Types
+
+- `FieldLayout` = `'stacked' | 'row'`
+
+## Examples
+
+```tsx
+<Field label="Email" required hint="We never share it."><Input type="email" /></Field>
+<Field label="Name" error="Name is required."><Input /></Field>
+<Field layout="row" label="Email notifications" description="A digest every Monday.">
+  <Switch defaultChecked />
+</Field>
+```

package/dist/agent/FigureBand.md

@@ -0,0 +1,49 @@
+# FigureBand
+
+A row of counted facts, divided by hairlines and nothing else.
+
+- Kind: component
+- Group: Display
+- Import: `import { FigureBand } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/figure-band/
+- Related: table
+
+## Anatomy
+
+- **Query wrapper** (required) — A plain <div> around the list, and it has to be: a container query resolves against an ANCESTOR container, never against the element declaring one. Its w-full is load-bearing too — contain: inline-size computes width without looking at the contents, so as a shrink-to-fit flex item it resolved to zero and the band rendered as two 0px columns.
+- **Band** (required) — The <dl>: ruled top and bottom in --rule, two columns until the wrapper reaches @3xl and four after — a decision about how wide THIS band is, not how wide the window is.
+- **Cell** (required) — One <div> per figure. Each divider width names the cells that do NOT open a row rather than adding a rule and taking it back, so no edge is ever painted past the last column.
+- **Label** (required) — The <dt>: the mono uppercase kicker over the value.
+- **Value** (required) — The <dd>, set in the heading face at --fs-lead or --fs-sub depending on scale.
+- **Note** — A second <dd> under the same term — a trend, a qualifier, a second fact.
+
+## Best practices
+
+### Do
+
+- Give it two or four figures. The grid is two columns until @3xl and four after, so three leaves a hole in both arrangements and five leaves three holes once the band goes four across.
+- Use scale="sub" for a band that supports the page rather than being it: --fs-lead is the band-heading step, so a supporting figure set at lead is competing with the page’s own subject.
+- Key each figure by the fact it counts — id is required rather than optional, because it is the React key and an index puts the next render’s number under the previous label as soon as the list reorders.
+
+### Don’t
+
+- Do not put a sentence in note. The value and the note are two <dd>s under one <dt>, so a screen reader reads them as two values of the same term: “Posts: 48, +6 this year” works, a clause does not.
+- Do not set the column count with a viewport breakpoint through className. The band reads a container query, so a sm:grid-cols-4 written on it is wrong in a 390px sidebar of a 1440px window — which is the arrangement this replaced.
+- figures={[]} renders null, so a band fed a filtered-empty array leaves no rules behind and no zero state either — if the absence is the news, the call site has to say so.
+
+## Accessibility
+
+- A <dl>: each cell is a term and its value, which a grid of divs cannot express.
+
+## FigureBand
+
+A framed, responsive group of related facts with semantic term/value pairs.
+
+### Props
+
+- `figures` (required) — `Figure[]`.
+- `scale` — `'lead' | 'sub'` default `'lead'`. How large the value is set. `lead` is for a band that is the point of its page — a stats headline, where the numbers ARE the content. `sub` is for a band that supports the page around it, and keeps the ladder honest: a supporting figure must not be set at the same size as the page's own subject.
+- `label` — `string`. Names the band for assistive tech when it has no visible heading of its own.
+
+Also accepts: `Omit<HTMLAttributes<HTMLDListElement>, 'children'>`.

package/dist/agent/FloatingIconButton.md

@@ -0,0 +1,61 @@
+# FloatingIconButton
+
+A round action pinned to a screen corner.
+
+- Kind: component
+- Group: Actions
+- Import: `import { FloatingIconButton } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/floating-icon-button/
+- Related: button
+
+## When to reach for it
+
+A page-level affordance that must stay reachable while the reader scrolls — back to top, a mobile table of contents.
+
+## Anatomy
+
+- **Control box** (required) — A real <button type="button">, --control-h-md square with a pill radius, position: fixed to a bottom corner at --z-drawer. There is no asChild and no href here: it cannot become a link.
+- **Icon** (required) — children, and the only thing in the box. Nothing text-shaped renders, so the control is as wide as the square and no wider.
+- **Ground** (required) — A 90% --paper fill over a backdrop blur, with a --rule-2 hairline. The White Reset has no elevation ramp, so the blur and the hairline are what lift it off the page — not a shadow.
+- **Name** (required) — label, set as aria-label. It never renders, so a screen reader has the name and a sighted reader has the glyph alone.
+
+## Best practices
+
+### Do
+
+- Spell out position — it is required and has no default, and the values are start and end in reading order. The component’s own doc example says position="right", which is not one of them and does not type-check.
+- Wrap it in a Tooltip when the glyph is not universal: label is aria-label only, so it names the control for a screen reader and for nobody else — and a tooltip does not open on touch, which is where a floating control is most often the only affordance on screen.
+- Keep it to two. start is deliberately raised to 5rem while end sits at 1.5rem, which is exactly enough clearance for a pair; a third has nowhere left to go, and the corners already compete with a cookie bar and a chat launcher.
+- Move it with className when the page has a fixed footer — the classes go through tailwind-merge, so className="bottom-24" REPLACES the corner offset rather than losing to it.
+
+### Don’t
+
+- --control-h-md is 44px at the default density and 36px under data-density="compact", so a compact page ships the one control a thumb reaches for without looking at eight pixels under the WCAG 2.5.5 floor.
+- It is position: fixed, so any ancestor with a transform, filter or backdrop-filter becomes its containing block — put one inside a DialogContent, which centres itself with a translate, and it pins to the panel’s corner instead of the screen’s.
+- It sits at --z-drawer, 100, and every rank that can appear over it is higher: a scrim is 200, a modal 210, an anchored panel 220 — --z-dropdown now resolves to --z-anchored, not to this rank. So a menu opening into the same corner covers the button outright rather than tying with it, and a dialog covers it too. Nothing here is settled by document order; move the button with className if it must stay reachable beside something else.
+
+## Accessibility
+
+- label is the only name the control has; it is required rather than optional.
+- 44px square, which is the pointer-target floor (WCAG 2.5.8).
+
+## FloatingIconButton
+
+A round action pinned to a screen corner. A translucent paper ground with a backdrop blur rather than a drop shadow — the White Reset has no elevation ramp, so what separates the control from the page under it is the blur and the hairline, not a glow.
+
+### Props
+
+- `position` (required) — `'start' | 'end'`. Which bottom corner the control is pinned to, in READING order — `end` is the right in English and the left in Arabic. Naming the sides `left`/`right` would have hard-coded one script's layout into the API.
+- `label` (required) — `string`. Accessible name — the button has no visible text, so this is its only name.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'>`.
+
+## Examples
+
+```tsx
+<FloatingIconButton position="right" label="Back to top" onClick={scrollUp}>
+  <ArrowUp size={16} />
+</FloatingIconButton>
+```

package/dist/agent/FunnelChart.md

@@ -0,0 +1,75 @@
+# FunnelChart
+
+Stages that only ever narrow.
+
+- Kind: component
+- Group: Charts
+- Import: `import { FunnelChart } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/funnel-chart/
+- Related: sankey-chart, bar-chart
+
+## When to reach for it
+
+A signup flow, a hiring pipeline, a checkout. When the flow can SPLIT rather than only shrink, it is a SankeyChart — a funnel has one path through it by construction.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero stages. There is still no loading skeleton, so that state remains the call site’s job.
+- **Stages** (required) — <FunnelChart.Funnel>. The rows are drawn in the order given and never sorted, and each stage is cut from the next by a --chart-surface stroke gap pixels wide rather than by a transparent gap, so the stages still touch.
+- **Stage labels** — <FunnelChart.Label>, positioned right by default. Its dataKey defaults to the NAME field, not the value — printing the numbers means pointing it at the value key yourself.
+- **Tooltip** — <FunnelChart.Tooltip>, heading suppressed and cursor off. There is no axis here for a crosshair to run along.
+- **Hidden data table** — The sr-only table, one row per stage. It is the only exact reading this form offers, because a funnel has no axis and no ticks anywhere on it.
+
+## Best practices
+
+### Do
+
+- Point <FunnelChart.Label> at the value field. With no dataKey it prints the stage NAME, which the reader already has, and the number — the one thing the taper cannot be read for — goes unprinted.
+- Order the rows widest first yourself. The component draws them in the order it is handed and does not sort, so a stage out of place renders a funnel that widens, which a reader will read as a data error.
+- Keep variant="stepped" unless the stages are also a sequence of kinds. ramp walks the series ramp stage by stage, which encodes the drop a second time when the taper has already said it.
+
+### Don’t
+
+- Do not use it for a flow that splits. A funnel has one path through it by construction; where a stage divides into two outcomes the honest form is a SankeyChart, which can draw both branches.
+- Do not read the fall-off off the shape. The taper is a ratio between neighbours and the eye reads the enclosed AREA, so a shallow drop is exaggerated and a steep one flattened, with no axis anywhere to check it against.
+
+## Accessibility
+
+- title is required; the stages are also rendered as a visually hidden table.
+- The taper encodes a ratio between neighbouring stages and the eye reads the enclosed area, so a funnel exaggerates a shallow drop. Compose a Label to print the numbers — that is the relief.
+- The default variant holds one fill for every stage and lets the shape carry the drop. A ramp that also darkens each stage encodes the same fact twice.
+
+## FunnelChart
+
+Stages that only ever narrow — a signup flow, a hiring pipeline, a checkout. The caveat is the same one every funnel has: the taper encodes a RATIO between neighbouring stages, and the eye reads the enclosed area, so a funnel exaggerates a shallow drop and flattens a steep one. Where the exact fall-off is the point, put the percentages on the stages — `<Funnel.Label>` does — or use a `<BarChart>`, which encodes each stage on one honest scale. Reach for `<SankeyChart>` instead when the flow can SPLIT rather than only shrink: a funnel has one path through it by construction.
+
+### Props
+
+- `config` (required) — `ChartConfig`. Stage names → their label and paint. Keys must match the `nameKey` values.
+- `data` (required) — `TData[]`. The stages, widest first. Order is the funnel; it is not sorted for you.
+- `dataKey` (required) — `keyof TData & string`. The row field holding each stage's number.
+- `nameKey` (required) — `keyof TData & string`. The row field naming each stage.
+- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `children` (required) — `ReactNode`. The composed parts — `<Funnel>`, `<Tooltip>`.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `chartProps` — `ComponentProps<typeof RechartsFunnelChart>`. Escape hatch onto the raw Recharts chart element.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `FunnelVariant` = `'stepped' | 'ramp'`
+
+## Examples
+
+```tsx
+<FunnelChart title="Signup funnel" config={config} data={stages} dataKey="people" nameKey="stage">
+  <FunnelChart.Funnel>
+    <FunnelChart.Label />
+  </FunnelChart.Funnel>
+  <FunnelChart.Tooltip />
+</FunnelChart>
+```