@misoto22/folio 0.0.0 → 0.17.0

package/dist/agent/Badge.md

@@ -0,0 +1,62 @@
+# Badge
+
+A count or a state, set in mono so it reads as metadata.
+
+- Kind: component
+- Group: Display
+- Import: `import { Badge } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/badge/
+- Related: tag, status-pill
+
+## When to reach for it
+
+One fact about one record. If it names what something is ABOUT, that is a Tag.
+
+## Anatomy
+
+- **Chip** (required) — The <span>: inline-flex on the --radius-sm corner, mono at 12px with wide tracking. The mono face is the whole signal — it is what tells a reader this is metadata rather than a word of the sentence it sits in.
+- **Ground** (required) — The tone’s fill — --stone for neutral, the soft tint of --ok, --warn or --danger for the three status tones, and nothing at all for outline.
+- **Border** (required) — Always drawn, and transparent for every tone but outline, so the box reserves the pixel either way and swapping tone at runtime moves nothing beside it.
+- **Content** (required) — children, with a 6px gap between them — so a StatusDot or a Kbd set beside the text spaces itself without a wrapper.
+
+## Best practices
+
+### Do
+
+- Leave tone at neutral unless the badge names a STATE: the three status tones are the only chroma this system spends, and a badge that is red because the page wanted red is the thing the scale exists to prevent.
+- Reach for outline when the badge sits on --stone already — every other tone fills its own ground, and a neutral badge on stone is a chip with no visible edge at all.
+- Keep it to a count, a word, or a short state. It is 12px mono sized for one line, so a phrase in it is prose set in the metadata face and wraps inside a box that was never given a second line.
+
+### Don’t
+
+- A row of them is a Tag list drawn in the wrong component: Badge has no active state, so the filter bar it turns into cannot show which facet is on.
+- A neutral Badge and an inactive Tag are the same corner, the same padding and the same 12px mono, separated by one ink step — so a row that mixes states and topics reads as one undifferentiated run of chips.
+- There is no dismiss affordance here. A × written into children is text inside the accessible name, so the badge is announced as “beta ×” and the close it advertises does not exist.
+
+## Accessibility
+
+- Not interactive. A badge with an onClick is a control a keyboard cannot reach.
+- The status tones double their colour with words, so the meaning survives monochrome and colour-blindness.
+
+## Badge
+
+A count, a state, a small inline marker. Mono and small, so it reads as metadata rather than as content. A badge is not interactive — if it can be clicked or dismissed it is a `Tag` or a button, and giving this one an `onClick` produces a control a keyboard cannot reach.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `tone` — `BadgeTone` default `'neutral'`. `neutral` is the default and the right answer nearly always. The three status tones are the system's only chroma and are bound to STATE — a badge that is red because the design wanted a red badge is the thing this scale exists to prevent.
+
+Also accepts: `HTMLAttributes<HTMLSpanElement>`.
+
+## Types
+
+- `BadgeTone` = `'neutral' | 'success' | 'warning' | 'danger' | 'outline'`
+
+## Examples
+
+```tsx
+<Badge>12</Badge>
+<Badge tone="success">Deployed</Badge>
+```

package/dist/agent/BarChart.md

@@ -0,0 +1,93 @@
+# BarChart
+
+Discrete categories compared by length.
+
+- Kind: component
+- Group: Charts
+- Import: `import { BarChart } from '@misoto22/folio/charts'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/bar-chart/
+- Related: area-chart, composed-chart, radial-chart
+
+## When to reach for it
+
+The categories are buckets rather than a continuum. If the axis is time and the reader is following a trend, an AreaChart or LineChart reads it faster.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, named by title whether or not the page prints a heading above it.
+- **Bars** (required) — <BarChart.Bar>, drawn through a custom shape: a transparent rectangle for the hit area, then the painted bar three pixels shorter than its slot so a stacked segment keeps a hairline of page between it and the one above. A bar shorter than that trim is floored at one pixel rather than taken to nothing, so a small count is never pixel-identical to an absent one.
+- **Axes** — <BarChart.XAxis> and <BarChart.YAxis>, both flat by default — no tick line, no axis line. Every Recharts prop passes straight through, domain included, which is the door a truncated baseline comes in through.
+- **Legend** — <BarChart.Legend>. With isClickable each entry is a real <button> carrying aria-pressed rather than a div with a handler, which is the difference between a filter a keyboard can reach and one it cannot.
+- **Value labels** — <BarChart.Values>, a slot composed inside a bar. show defaults to last; all is for five or six bars where the exact figures are the point, and past that it is a table wearing a chart.
+- **Hidden data table** — The sr-only table of the FULL data rather than of the brushed window, so a reader on the table is never shown less than the CSV export holds. hideDataTable removes it, and zero rows render nothing.
+- **Empty state** — ChartEmpty, rendered in place of the plot when data is empty — a title, a reason and an optional action, so a filter that matched nothing is told apart from a load that failed. empty={false} keeps the bare axes instead.
+
+## Best practices
+
+### Do
+
+- Reach for buffer on a period still open. It hatches the last ROW rather than the last bar on screen, so brushing back into the middle of the range hatches nothing — a month that closed in March is never drawn as still being counted.
+- Leave the value axis anchored at zero. A bar encodes by LENGTH from the baseline, so a domain of ["dataMin", "dataMax"] passed through <BarChart.YAxis> turns a two percent gap into a doubled bar. This is the distortion a bar chart cannot survive and a LineChart can: a line encodes by slope, so clipping its domain rescales the reading rather than inventing one.
+- Reach for orientation="horizontal" when the category names are long. The alternative is a tick label rotated under every column, and a rotated label is slower to read than the bar it names.
+- Pass a tickFormatter to <BarChart.YAxis> under stackType="percent". Unlike AreaChart’s expanded stack, which swaps in percentTick itself, the bar chart’s axis keeps defaultTick — so a normalised chart reads 0 to 1 instead of 0% to 100%.
+- Put the series that has to be compared across categories at the BASELINE of a stack. Only the bottom segment starts at zero; every band above it floats on the ones below, and reading a third band across twelve months is a comparison the eye cannot make. When that comparison is the point, group the bars instead.
+
+### Don’t
+
+- hideDataTable leaves no exact figure anywhere. defaultTick compacts at ten thousand and above, so the axis says 1.2M and so do the <BarChart.Values> labels; the sr-only table, where every cell is a full toLocaleString, was the only place the real number was written.
+- Twenty bars at variant="default" is a wall rather than twenty values. stripped draws a 2px cap over a wash and stays countable at that density, which is the density it exists for.
+- Do not close barCategoryGap up. The space between groups is the only thing telling a reader that two adjacent bars are two series rather than two categories, so a grouped chart with no category gap reads as a stacked one.
+
+## Accessibility
+
+- title is required; the rows are also rendered as a visually hidden table.
+- Every bar carries an invisible full-height hit rectangle, so a 3px bar at the bottom of the scale is as easy to hit as a full-height one.
+- A clickable legend entry is a real button with aria-pressed, not a div with a click handler.
+- The staggered grow-in is anchored to the chart’s own start rather than to each bar’s mount, so a hover cannot replay it — and reduce-motion drops it entirely.
+
+## BarChart
+
+Discrete categories compared by length — the shape for "how much, per thing". Reach for `<AreaChart>` or `<LineChart>` when the axis is continuous and the reader is following a trend rather than comparing buckets.
+
+### Props
+
+- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`.
+- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
+- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
+- `stackType` — `BarStackType` default `'default'`. How several marks combine: side by side, stacked, or normalised to 100%.
+- `orientation` — `BarOrientation` default `'vertical'`. Which way the bars run. Reach for `horizontal` when the category names are long enough to need rotating under a column.
+- `barRadius` — `number` default `BAR_RADIUS`. The corner every `<BarChart.Bar>` inherits.
+- `animationType` — `ChartRevealType` default `'forward'`. The grow-in order every `<BarChart.Bar>` inherits.
+- `barGap` — `number`. Gap between bars inside one category.
+- `barCategoryGap` — `number`. Gap between categories.
+- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
+- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
+- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
+- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
+- `loadingBars` — `number`. How many bars the skeleton draws.
+- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
+- `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. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `BarVariant` = `'default' | 'hatched' | 'duotone' | 'duotone-reverse' | 'gradient' | 'stripped'`
+- `BarStackType` = `'default' | 'stacked' | 'percent'`
+- `BarOrientation` = `'vertical' | 'horizontal'`
+
+## Examples
+
+```tsx
+<BarChart title="Visitors by month" config={config} data={data} xDataKey="month">
+  <BarChart.Grid />
+  <BarChart.XAxis dataKey="month" />
+  <BarChart.Tooltip />
+  <BarChart.Bar dataKey="desktop" variant="duotone" />
+</BarChart>
+```

package/dist/agent/BarList.md

@@ -0,0 +1,67 @@
+# BarList
+
+A ranked list, with the bar behind the name rather than beside it.
+
+- Kind: component
+- Group: Data
+- Import: `import { BarList } from '@misoto22/folio/charts'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/bar-list/
+- Related: bar-chart, table
+
+## When to reach for it
+
+Top referrers, slowest endpoints, biggest accounts. A horizontal BarChart spends a third of its width on an axis repeating labels the rows could simply contain.
+
+## Anatomy
+
+- **Caption** (required) — label, as the table’s real caption — sr-only unless showLabel prints it as an eyebrow above the rows. It is what names the list for a screen reader.
+- **Header row** (required) — An sr-only thead of two th scope="col" cells, Name and Value, so both columns are named even though the list never shows a header.
+- **Name cell** (required) — A th scope="row" holding the row’s name truncated to one line, with item.icon before it as aria-hidden decoration and item.href turning the name itself into the link.
+- **Bar** (required) — Not an element: a linear-gradient on the name cell’s inner span, a hard stop at the row’s share of the ceiling. Drawn as a sibling div it would be one more empty thing in the accessibility tree saying nothing.
+- **Value cell** (required) — A td at the end edge in mono tabular figures at --ink-2, written by formatValue — the same compact default the axes use unless the call site replaces it.
+- **Other row** — What limit adds: one final row named Other carrying the summed tail, so the rows shown still account for the whole they were cut from.
+- **Empty state** — ChartEmpty under the label when there is nothing to rank. A caption over an empty tbody is a list that failed to load as far as the reader can tell, and reloading does not change it.
+
+## Best practices
+
+### Do
+
+- Pin max when rows arrive over time. The ceiling is the largest row currently shown, so one new leader rescales every bar under it — a track that was two thirds full yesterday is a quarter full today with exactly the same number in it, and the movement the reader sees happened to a different row.
+- Reach for limit rather than slicing items at the call site. The tail is summed into the Other row instead of being dropped, so the five rows shown still add up to the whole; a top five cut by hand discards the other forty silently, and nothing in the list says so.
+- Keep names short enough to survive the truncation. The name is a single truncated line sharing its width with the value column, so two endpoints that differ only past the fortieth character render as the same row with the same ellipsis.
+- Pass sort={false} when the order is the point — a funnel, a set of steps, a fixed set of regions. sort defaults to true and orders descending, which turns a sequence into a ranking without saying that it did.
+
+### Don’t
+
+- The bar is the row over the largest row, never a share of a total: the leading row always fills its track, so five rows that make up 3 percent of traffic look exactly like five that make up all of it. Where the whole matters, the caption is where it goes.
+- Do not mix number shapes down the value column. It is end-aligned mono with tabular figures, which lines digits up only while the strings are the same shape — and the default formatter switches to the compact form at 10,000, so a list spanning that threshold puts 9,400 under 1.2M and there is nothing left to compare down.
+- Two rows cannot share a name. It is the row’s label and its React key at once, so a list built from a query that can repeat a label renders duplicate keys, which React warns about and reconciles wrongly the moment the list updates.
+
+## Accessibility
+
+- A real <table> with two columns and one row per thing, because that is what a ranked list is. The bar is a background on the name cell, so it is never a second element a screen reader has to walk past.
+- limit sums the tail into an “Other” row rather than dropping it — a top five that silently discards the other forty misstates the whole, and the reader has no way to tell.
+- Pin max to compare two lists side by side: on independent scales the leading row of each fills its track, and two very different numbers look identical.
+
+## BarList
+
+A ranked list, with the bar behind the name rather than beside it. The answer to "top referrers", "slowest endpoints", "biggest accounts" — and a better one than a horizontal bar chart, which spends a third of its width on a category axis repeating labels the rows could simply contain. Reading a name off a y-axis and matching it to a bar is two steps; reading it off the bar is none. It is a `<table>`, because that is what it is: two columns, a header, and one row per thing. The bar is a background on the name cell, so it never becomes a second element a screen reader has to walk past. Reach for `<BarChart orientation="horizontal">` instead when the categories are few and fixed and the axis is doing real work — a scale a reader needs to read values off, rather than a ranking they need to skim.
+
+### Props
+
+- `label` (required) — `string`. What the list ranks. Required: it names the table for a screen reader.
+- `showLabel` — `boolean` default `false`. Prints the label above the list instead of hiding it from sight.
+- `items` (required) — `BarListItem[]`.
+- `limit` — `number`. Keeps the top N and folds the rest into one "Other" row.
+- `formatValue` — `(value: number) => string` default `defaultTick`. Formats each value. Defaults to the same compact form the axes use.
+- `max` — `number`. The scale's ceiling. Derived from the largest row when omitted. Pin it to compare two lists side by side — on independent scales the leading row of each fills its track, and two very different numbers look identical.
+- `sort` — `boolean` default `true`. Sorts descending before rendering.
+- `className` — `string`.
+- `empty` — `ChartEmptyProps`. What the list shows when it has nothing to rank. A caption over an empty `<tbody>` is a list that failed to load as far as the reader can tell, and the reader's next move is to reload the page.
+
+## Examples
+
+```tsx
+<BarList label="Top referrers" items={referrers} limit={5} />
+```

package/dist/agent/BigNumber.md

@@ -0,0 +1,70 @@
+# BigNumber
+
+One number, at the size of a headline.
+
+- Kind: component
+- Group: Data
+- Import: `import { BigNumber } from '@misoto22/folio/charts'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/big-number/
+- Related: sparkline, figure-band
+
+## When to reach for it
+
+There is exactly one figure to report. A plot of a single value is a plot whose shape carries nothing, and the reader has to decode an axis to recover a number that could simply have been printed.
+
+## Anatomy
+
+- **Label** (required) — What the number counts, as an eyebrow at --ink-3-aa above it. Nothing binds it to the value programmatically — no aria-labelledby, no role — so document order is the whole association.
+- **Value** (required) — The number itself, in the editorial face at --fs-lead with tabular figures. Rendered exactly as handed over: no unit, currency or locale is guessed on its behalf.
+- **Delta** — The line under the number, from delta: the change through format — a signed percentage unless replaced — and delta.label at --ink-3-aa saying what it is a change from.
+- **Direction mark** — Inside the delta: an aria-hidden arrow, up, down or flat at zero, and the status tint, --ok or --danger, or --ink-2 while nothing has been judged. Two carriers, so the reading survives greyscale and forced colours.
+- **Verdict** — The sr-only words beside the arrow — up or down, then better or worse once intent has been set. It is what a screen reader gets in place of the tint.
+- **Note slot** — children, under the number with a margin: where a Sparkline, a denominator or a caveat goes.
+
+## Best practices
+
+### Do
+
+- Give the figure something to be judged against. On its own a number cannot be read — 48,210 is neither good nor bad until it is beside last month — and this component carries exactly two places for that: delta for one comparison, children for the Sparkline or the denominator under it.
+- Pass delta.value as a ratio. The default formatter multiplies by a hundred and prefixes the sign, so 0.124 prints as +12.4% and 12.4 prints as +1240%. A change already expressed in points needs its own format handed over with it.
+- Set intent on any delta meant to be coloured. It defaults to neutral, which renders the change at --ink-2 and says only which way it moved — correct for a figure nobody has judged, and rarely what the author of a revenue card thought they had written.
+- Let value be null when there is no reading. It prints an em dash at --ink-3-aa with an sr-only “No data” behind it, which is a number nobody has; a blank line under a label is a broken layout as far as the reader can tell. emptyValue changes what the dash is.
+
+### Don’t
+
+- Do not expect a delta of exactly zero to carry the intent’s verdict. There is no direction for an intent to judge, so the tone, the arrow and the announced words all say “no change” and stop — a zero under up-is-good used to be announced as “no change, worse” while the page showed no judgement at all.
+- Do not separate the label from the number. The value is text in a span rather than a labelled element, and the label is a sibling read before it, so a layout that moves the figure into its own column — or reuses one label over two figures — hands a screen reader a bare number with nothing naming it.
+
+## Accessibility
+
+- The delta’s direction is stated by the call site through intent, never inferred from the sign: “errors down 12%” is good news and “revenue down 12%” is not, and no component can tell which it is holding.
+- The arrow and the words carry the direction; the status tint is the third signal, never the only one — so the reading survives greyscale, forced colours and colour blindness.
+- value is taken already formatted. The component does not guess a unit, a currency or a locale.
+
+## BigNumber
+
+One number, at the size of a headline. The form most dashboards need most often and most chart libraries do not ship, on the grounds that it is not a chart. It is the right answer whenever there is exactly one figure to report: a plot of a single value is a plot whose shape carries nothing, and the reader has to decode an axis to recover a number that could simply have been printed. The delta is where this earns its place over a `<p>`. Direction is stated by the CALL SITE (`intent`), never inferred: "errors down 12%" is good news and "revenue down 12%" is not, and no component can tell which it is holding. Where the direction is known, the arrow and the word carry it — the status colour is the third signal, never the only one.
+
+### Props
+
+- `label` (required) — `ReactNode`. What the number counts.
+- `value` (required) — `ReactNode`. The number, already formatted — this component does not guess a unit. `null` and `undefined` are the empty state rather than a blank space: a headline with nothing under it reads as a figure that failed to load, and the reader's next move is to reload a page that will look the same.
+- `emptyValue` — `ReactNode` default `'—'`. What stands in for the number when there is none.
+- `delta` — `BigNumberDelta`.
+- `children` — `ReactNode`. A sparkline, a note, a caveat. Sits under the number.
+- `className` — `string`.
+
+## Types
+
+- `DeltaIntent` = `'up-is-good' | 'down-is-good' | 'neutral'`
+
+## Examples
+
+```tsx
+<BigNumber
+  label="Monthly revenue"
+  value="$48,210"
+  delta={{ value: 0.124, label: 'vs last month', intent: 'up-is-good' }}
+/>
+```

package/dist/agent/BoxPlot.md

@@ -0,0 +1,82 @@
+# BoxPlot
+
+The spread of a measurement, per category.
+
+- Kind: component
+- Group: Charts
+- Import: `import { BoxPlot } from '@misoto22/folio/charts'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/box-plot/
+- Related: histogram, scatter-chart
+
+## When to reach for it
+
+How variable is this, across six things at once. When the shape of ONE distribution is the question it wants a Histogram; when there are few enough observations to draw them all, a ScatterChart.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state when no category survives resolving. empty={false} keeps the axes for a chart whose emptiness is itself the reading.
+- **Boxes** (required) — <BoxPlot.Boxes>: one range bar per category spanning min to max, entirely unpainted, with the glyph drawn over it. Recharts supplies the category band and the scale; the box, the median rule, the whiskers and the outlier dots are the package’s own.
+- **Value axis** — <BoxPlot.YAxis>, and it is deliberately NOT anchored at zero — a box plot compares distributions, and dragging the domain to zero to be honest about bar length flattens every box into the same band of pixels. The honesty it owes is a labelled axis, which it has.
+- **Notch** — notch pinches the box in at the median by 1.58 times IQR over the square root of n — a confidence interval drawn inside the shape it belongs to. It needs count on every box; a box without one is drawn square and says nothing about it.
+- **Outlier dots** — showOutliers, on by default. Points past Tukey’s 1.5 IQR fences are drawn one dot each, and the whiskers then stop at the most extreme observation still INSIDE the fence rather than at the fence itself, so no whisker claims a reading the data does not contain.
+- **Hidden data table** (required) — The sr-only table carries all five numbers per category plus the outlier count, so the figure is fully readable without seeing the glyph.
+
+## Best practices
+
+### Do
+
+- Carry count on every box. A box over six observations and a box over six thousand are drawn identically, and count is also what a notch reads — without it, notch is accepted and quietly does nothing.
+- Say which quantile rule produced a pre-computed summary. This component uses R type 7 when it summarises raw values, and on [1, 2, 3, 4] that puts the lower quartile at 1.75 where the median-of-the-lower-half rule puts it at 1.5 — the same data under two rules is two different pictures.
+- Hand it the raw values rather than a summary when you have them. One pass applies Tukey’s fences, splits the outliers out and fills count in, so the five numbers and the dots cannot drift apart.
+
+### Don’t
+
+- A box cannot tell one hump from two. A latency series with a cache path and a database path in it draws exactly the box a smooth distribution centred in the same place draws, and the middle of that box is a value almost nothing takes. When the SHAPE is the question it is a Histogram.
+- A category whose values array is empty is dropped outright — no box, no tick, no table row — because summarising it yields nothing to draw. The chart renders six boxes where seven were asked for and says nothing about the seventh.
+- One observation draws a box with no box: q1, the median and q3 are the same number, the IQR is zero, and the glyph collapses to a single rule. It is not an error and it is not a distribution, so guard it at the call site.
+
+## Accessibility
+
+- A box is five numbers, and five numbers cannot tell one hump from two. A bimodal distribution draws exactly the same box as a smooth one centred in the same place — the component says so in its own description rather than in a footnote.
+- It also hides sample size: a box over six points and a box over six thousand are drawn identically. Carry count, and turn on notched whenever medians are being compared.
+- Raw values are summarised with Tukey’s fences, which is stated on the page rather than assumed — a different fence rule draws different outliers from the same data.
+- The hidden data table carries all five numbers per category, so the figure is readable without seeing the glyph.
+
+## BoxPlot
+
+The spread of a measurement, per category — median, middle half, reach, and the points that sit outside it. The form to reach for when the question is "how variable is this", and the one that answers it in a tenth of the ink a histogram per category would take. Six response-time distributions fit across one screen as six boxes; as six histograms they do not fit at all. **What a box plot hides is multimodality.** A box is five numbers, and five numbers cannot tell a single hump from two. A bimodal distribution — a fast cache path and a slow database path, two cohorts inside one average — draws exactly the same box as a smooth one centred in the same place, and the reader has no way to tell from the picture that the middle of the box is a value almost nothing takes. It also hides sample size: a box over six points and a box over six thousand are drawn identically, which is why `count` is worth carrying and why a notch, which does read `count`, is worth turning on when medians are being compared. When the SHAPE of one distribution is the question, reach for `<Histogram>`; when there are few enough observations to draw them all, reach for `<ScatterChart>` and plot the points. Recharts earns its place here: the boxes need a shared value axis with real ticks, a category axis, a grid and a tooltip, which is most of a cartesian chart. What it does not have is a box mark, so each box is drawn as a custom shape over a range bar — the bar supplies the category band and the scale, and the glyph inside it is ours.
+
+### Props
+
+- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a box plot has one measurement and as many categories as it has boxes.
+- `data` (required) — `BoxPlotDatum[]`. One entry per category, as raw observations or as a summary.
+- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, and `<BoxPlot.Boxes>`.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
+- `orientation` — `BoxPlotOrientation` default `'vertical'`. Which way the boxes run. Reach for `horizontal` when the category names are long enough to need rotating under a column.
+- `formatValue` — `(value: number) => string` default `defaultTick`. Formats every number the chart prints — ticks, tooltip, table.
+- `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 axes, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `BoxPlotOrientation` = `'vertical' | 'horizontal'`
+- `BoxPlotDatum` = `BoxPlotSample | (BoxPlotSummary & { values?: never })`
+
+## Examples
+
+```tsx
+<BoxPlot title="Response time by region" data={regions}>
+  <BoxPlot.Grid />
+  <BoxPlot.XAxis />
+  <BoxPlot.YAxis label="ms" />
+  <BoxPlot.Tooltip />
+  <BoxPlot.Boxes showOutliers />
+</BoxPlot>
+// Raw observations, summarised for you with Tukey's fences.
+const data = [{ name: 'Sydney', values: [180, 194, 210, 205, 640] }]
+```

package/dist/agent/Breadcrumb.md

@@ -0,0 +1,55 @@
+# Breadcrumb
+
+Where you are, as a path.
+
+- Kind: component
+- Group: Navigation
+- Import: `import { Breadcrumb } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/breadcrumb/
+- Related: pagination
+
+## Anatomy
+
+- **Trail** (required) — A <nav> named by label, which defaults to “Breadcrumb”. It is a landmark whether or not the page wanted another one, set in mono-meta at --ink-3-aa.
+- **List** (required) — An <ol> — the order is the hierarchy, not the reader’s history. It wraps rather than truncating, so a deep path takes a second line instead of losing a level.
+- **Crumb link** — An <a> for every item that has an href and is not the last. The label is a ReactNode, so whatever you put in it becomes part of the link’s accessible name.
+- **Current crumb** (required) — The last item, always: plain text at full --ink with aria-current="page", whether or not it was given an href.
+- **Separator** — A slash by default, in its own <li aria-hidden> between crumbs. Decorative by construction — it is never part of what is read out.
+
+## Best practices
+
+### Do
+
+- Pass label when a page can hold two trails: both nav landmarks are named “Breadcrumb” otherwise, and two landmarks with one name are two entries a reader cannot choose between.
+- Give every crumb but the last an href — one without renders as plain text in the same colour as the links beside it, with no destination and no aria-current, so it reads as the page the reader is on when it is not. Development names the crumb rather than leaving an omission that is invisible in the browser and in review.
+- Start the trail above the current page: a one-item Breadcrumb renders that item as the current crumb with no path at all, which is a landmark announcing a journey of length one.
+
+### Don’t
+
+- Leave the href off the last item rather than passing one it ignores: the last crumb is text whatever you hand it, so an href there reads as a link in review and is not one at run time.
+- Do not hide it on a phone to save a line. That is the layout where the sidebar is behind a drawer, which makes the trail the only way up a level that is on the screen.
+
+## Accessibility
+
+- The last crumb is text with aria-current="page", never a link to itself.
+- Separators are aria-hidden, so the trail is not read as “home slash work slash”.
+- A middle crumb with no href takes no aria-current and no colour of its own, which is why the omission is reported in development instead of shipped as a crumb that impersonates the current page.
+
+## Breadcrumb
+
+Where you are, as a path. The last crumb is plain text with `aria-current="page"` rather than a link to itself — a self-link is the most common breadcrumb bug, and it makes a screen reader offer a navigation that goes nowhere. Separators live in `<li aria-hidden>` so the trail is read as its items and not as "home slash work slash". A middle crumb with no `href` is a defect that is invisible twice over: it renders as plain text in the same `--ink-3-aa` as the links beside it, and it carries no `aria-current` either — so it reads as the page the reader is on when it is not, and neither the browser nor a review says a word. The console does, in development.
+
+### Props
+
+- `items` (required) — `Crumb[]`.
+- `label` — `string` default `'Breadcrumb'`. Names this trail when a page has more than one.
+- `separator` — `ReactNode` default `'/'`. Rendered between crumbs. A slash by default; it is decorative either way.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+<Breadcrumb items={[{ label: 'Components', href: '/components' }, { label: 'Button' }]} />
+```

package/dist/agent/BulletChart.md

@@ -0,0 +1,71 @@
+# BulletChart
+
+A measure, its target, and the bands that say whether it is any good.
+
+- Kind: component
+- Group: Data
+- Import: `import { BulletChart } from '@misoto22/folio/charts'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/bullet-chart/
+- Related: bar-list, big-number
+
+## When to reach for it
+
+A status page of ten tracked numbers. Stephen Few designed it to replace the dashboard gauge, which spends a whole card saying one number badly.
+
+## Anatomy
+
+- **Figure caption** (required) — title on the shared chart figure, referenced by aria-labelledby rather than left to be inferred from the figcaption, and hidden from sight unless showTitle prints it with description beneath.
+- **Measure line** (required) — The row above each track: the measure’s name with its optional detail at the start, the formatted value at the end, and the target after a slash where there is one. This line is the reading a screen reader gets, because the graphic under it is not in the accessibility tree at all.
+- **Track** (required) — The 24px aria-hidden box holding the bands, the bar and the target rule, laid out with inline-axis offsets rather than in SVG user space — which is what makes the whole chart mirror correctly in a right-to-left document.
+- **Bands** — The qualitative ground, built from ranges as ascending upper bounds: heaviest at the low end of the scale and lightening as it rises, so the solid bar stands out most where performance is best.
+- **Measure bar** (required) — The value, solid --series-1 at a third of the track’s height, running from the start of the scale. The one mark here that is a measurement rather than a judgement, and the only one drawn at full weight.
+- **Target rule** — target, as a 2px rule of --ink straight across the bar rather than a second bar beside it — so which number was achieved and which was asked for is a glance rather than a comparison.
+
+## Best practices
+
+### Do
+
+- Keep every range bound inside the domain. Bounds at or outside the two ends have no boundary to draw and are dropped before the bands are built, so ranges of 60 and 80 on a domain of 0 to 50 draws one flat band — the row LOOKS evaluated and is not. They stay in the table’s range-bounds cell, which is the only place the mismatch is visible.
+- Hold to five bands. The weights are spread evenly from the full --chart-fill down to three tenths of it across however many bands are passed, so a sixth and a seventh boundary only slice that same span thinner and the ground stops having edges a reader can read a threshold off.
+- Leave hideDataTable off unless the page prints the measures itself. The whole graphic is aria-hidden — bands, bar and target alike — so the generated sr-only table of value, target and range bounds is the only account of the chart a screen reader ever reaches.
+
+### Don’t
+
+- A value past the end of the scale is clamped, not overflowed: 130 on a domain of 0 to 100 fills the track exactly as 100 does. A notch at the end of the track says it happened and the figure printed above says by how much — but the track itself cannot, so pin domain wide enough for the overshoot you expect rather than reading the row that blew through its target as one that merely finished.
+- Do not put a range bound on the target. Both are placed by the same scale, so the rule lands exactly on a band edge and the one mark that says what was ASKED for disappears into the ground it was meant to be read against.
+
+## Accessibility
+
+- Plain HTML with logical properties — no rendering engine, server-renderable, and correct in a right-to-left document. Usable with recharts absent.
+- The bands are a JUDGEMENT drawn in the same ink as the measurement, so the page has to say where they came from. Ranges that encode nothing but thirds make the chart look evaluated when it is not.
+- It shows one instant and no change over time; target is the only comparison it carries. “How did we get here” wants a LineChart.
+- Shared bands only mean something when the measures share a scale — a latency beside a conversion rate needs ranges and domain per measure.
+
+## BulletChart
+
+A measure, its target, and the bands that say whether the number is any good — one dense row per thing being tracked. Stephen Few designed this to replace the dashboard gauge, and the argument has held: a speedometer spends a whole card saying one number badly, where a bullet graph says the same number, its target, and the qualitative context around it in the height of a line of text. Ten of them stack into a status page a reader can scan in one pass. What it will not do is show change over time. A bullet graph is one instant, and `target` is the only comparison it carries; when the question is "how did we get here" it wants a `<LineChart>`, and when several measures have to be compared against each OTHER rather than each against its own target, a `<BarList>` ranks them and this does not. **The bands are the part to be careful with.** They are a judgement — someone decided that 80 is "good" — drawn in the same ink as the measurement, and a reader has no way to tell an agreed threshold from a number somebody typed. They also compress: a value near the top of the scale sits in the same band whether it cleared the boundary by a point or by thirty. The band answers "is this acceptable", never "by how much". No rendering engine, deliberately — this is the one chart in the set with nothing to compute. Each row is a single linear scale with no axis, no ticks and no shared plot area, so it is laid out as HTML: the bands and the bar are inline-axis offsets, which means the whole chart mirrors correctly in a right-to-left document, where an SVG drawn in user space would not.
+
+### Props
+
+- `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 rows instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `data` (required) — `BulletMeasure[]`. One entry per measure. Order is the reading order; it is not sorted.
+- `ranges` — `number[]`. The bands every measure falls back to, as ascending upper bounds. Shared bands only mean something when the measures share a scale. Where they do not — a latency beside a conversion rate — put `ranges` and `domain` on each measure instead.
+- `domain` — `[number, number]`. The scale every measure falls back to, as `[min, max]`.
+- `formatValue` — `(value: number) => string` default `defaultTick`. Formats every number the chart prints.
+- `showScale` — `boolean` default `false`. Prints the scale's two ends under each track.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps`. What the chart shows when it has nothing to draw.
+
+## Examples
+
+```tsx
+<BulletChart
+  title="Service levels against target"
+  data={[{ name: 'Uptime', value: 99.4, target: 99.9, ranges: [98, 99.5] }]}
+  domain={[95, 100]}
+/>
+```

package/dist/agent/Button.md

@@ -0,0 +1,81 @@
+# Button
+
+The system’s action, on the same corner as the field beside it.
+
+- Kind: component
+- Group: Actions
+- Import: `import { Button } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/button/
+- Related: floating-icon-button, spinner
+
+## When to reach for it
+
+Anything that DOES something. If it navigates and looks like text, it is a link, not a ghost button.
+
+## Anatomy
+
+- **Control box** (required) — The <button>, the <a> it becomes when given href, or whatever asChild slots in. It carries the variant, the size, and the same --radius corner as the field beside it.
+- **Label** — children, and the accessible name of a text button. It stays put while loading, so the width does not move under the pointer.
+- **Icon** — The same children slot on an iconOnly button: the box goes square, the padding to zero, and nothing text-shaped is left behind for a screen reader.
+- **Keycap** — keycap, after the label — a mono glyph in a bordered box at reduced opacity. Real text, not decoration hidden from assistive tech.
+- **Spinner** — loading, before the label — a Spinner toned to the ground it sits on and passed label={null}, so it is aria-hidden and aria-busy on the control carries the state instead.
+
+## Best practices
+
+### Do
+
+- Spell out type="submit" on a form’s submit control: the default here is type="button", so the button at the foot of a form looks right and submits nothing.
+- Keep one primary to a view. variant defaults to primary, so a row written without the prop is a row in which every button claims to be the one thing the screen wants.
+- Reach for loading rather than swapping the label by hand: it holds the label, sets aria-busy and disables the control in one move, so the box does not collapse under the pointer that just clicked it.
+- Use href when it navigates and asChild when a router owns the navigation — a <button> whose onClick calls router.push cannot be opened in a new tab, and is announced as a button that goes nowhere.
+
+### Don’t
+
+- asChild passes the styling to the child and nothing else: keycap and loading never reach it, so a loading state written that way shows no spinner and blocks no clicks.
+- sm is 36px at the default density, under the 44px md clears on its own — a toolbar built out of sm is a row of targets a thumb misses (WCAG 2.5.5).
+- danger is a state, not emphasis. Spent on the merely important action, nothing is left that reads as destructive when one actually is.
+- The keycap is not hidden from assistive tech, so the glyph joins the accessible name — the control is read out as “Save S”, and a keycap for a shortcut nothing binds announces a promise the page never keeps.
+
+## Accessibility
+
+- A native <button> by default, so Enter and Space both fire it.
+- loading sets aria-busy and disables the control; the label stays, so the box does not collapse under the pointer that just clicked it.
+- A link cannot be disabled, so href + loading sets aria-disabled and blocks pointer events instead.
+- iconOnly has no text, so it requires aria-label — the single most common way a design system ships an unusable control.
+
+## Keyboard
+
+- Enter — Activates the button.
+- Space — Activates the button. A native <button> answers to both; a styled <div> answers to neither.
+
+## Button
+
+The system's action. Renders a `<button>`, or an `<a>` when given `href`, or whatever you hand it via `asChild`. No router is imported, so the package stays framework-agnostic and a Next or React Router app wires its own `Link` at the call site. Server-component friendly: there is no client boundary here, so it renders in a static page as well as an interactive one.
+
+### Props
+
+- `children` — `ReactNode`.
+- `variant` — `ButtonVariant` default `'primary'`. Which action this is. `primary` is the one thing the screen wants you to do, so there is at most one per view; `danger` is reserved for destructive actions and is the only place chroma is allowed on a control.
+- `size` — `ButtonSize` default `'md'`. 36 / 44 / 48px tall. `md` meets the pointer-target floor on its own.
+- `keycap` — `string`. Optional mono keycap glyph rendered after the label (e.g. "P").
+- `loading` — `boolean` default `false`. Swaps the leading content for a spinner and blocks interaction. The label stays put — a button that empties out while it works loses its width, and the page reflows under the pointer that just clicked it.
+- `iconOnly` — `boolean` default `false`. Square control with no label. REQUIRES `aria-label`: an icon-only button with no accessible name is invisible to a screen reader, and this is the single most common way a design system ships an unusable control.
+- `asChild` — `boolean` default `false`. Render the child element instead of a `<button>`, keeping these styles. Use it to hand the styling to a router's `Link` — `asChild` is what keeps this package free of any one router. The decoration slots (`keycap`, `loading`) are not injected into a slotted child; compose them inside it yourself.
+- `className` — `string`.
+- `href` — `string`.
+
+Also accepts: `AnchorHTMLAttributes<HTMLAnchorElement>`, `ButtonHTMLAttributes<HTMLButtonElement>`.
+
+## Types
+
+- `ButtonVariant` = `'primary' | 'secondary' | 'ghost' | 'danger'`
+- `ButtonSize` = `'sm' | 'md' | 'lg'`
+
+## Examples
+
+```tsx
+<Button variant="secondary" keycap="P">View projects</Button>
+<Button loading disabled>Saving…</Button>
+<Button iconOnly aria-label="Close"><X size={16} /></Button>
+```