@misoto22/design 0.3.1 → 0.6.0

package/dist/agent/Field.md

@@ -0,0 +1,37 @@
+# Field
+
+A labelled form row: label, control, and the one message below it.
+
+- Group: Forms
+- Import: `import { Field } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/field/
+- Related: input, select
+
+## 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.
+
+## 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.
+
+### 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.
+- `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`.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Examples
+
+```tsx
+<Field label="Email" required hint="We never share it."><Input type="email" /></Field>
+<Field label="Name" error="Name is required."><Input /></Field>
+```

package/dist/agent/FigureBand.md

@@ -0,0 +1,37 @@
+# FigureBand
+
+A row of counted facts, divided by hairlines and nothing else.
+
+- Group: Display
+- Import: `import { FigureBand } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/figure-band/
+- Related: table
+
+## Accessibility
+
+- A <dl>: each cell is a term and its value, which a grid of divs cannot express.
+
+## FigureBand
+
+A row of counted facts, divided by hairlines and nothing else. A `<dl>`, because that is what this is: each cell is a term and its value, and a grid of `<div>`s tells a screen reader nothing about which number goes with which label. Each divider width names the cells that do NOT open a row rather than adding a rule and taking it back — an `undo` at equal specificity resolves on Tailwind's own sort order, which is not something a layout should depend on. Drawn this way, no edge is ever painted past the last column.
+
+### 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'>`.
+
+## Examples
+
+```tsx
+<FigureBand
+  label="At a glance"
+  figures={[
+    { id: 'posts', label: 'Posts', value: '48', note: '+6 this year' },
+    { id: 'photos', label: 'Frames', value: '1,204' },
+  ]}
+/>
+```

package/dist/agent/FloatingIconButton.md

@@ -0,0 +1,38 @@
+# FloatingIconButton
+
+A round action pinned to a screen corner.
+
+- Group: Actions
+- Import: `import { FloatingIconButton } from '@misoto22/design'`
+- Version: 0.6.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.
+
+## 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,52 @@
+# FunnelChart
+
+Stages that only ever narrow.
+
+- Group: Charts
+- Import: `import { FunnelChart } from '@misoto22/design'`
+- Version: 0.6.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.
+
+## 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.
+
+## 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>
+```

package/dist/agent/Heatmap.md

@@ -0,0 +1,53 @@
+# Heatmap
+
+A grid of values read by weight.
+
+- Group: Data
+- Import: `import { Heatmap } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/heatmap/
+- Related: table, scatter-chart
+
+## When to reach for it
+
+A calendar of activity, a confusion matrix, an hour-by-weekday load. The one form a monochrome system renders better than a chromatic one.
+
+## Accessibility
+
+- A real <table>, not an SVG: the structure a screen reader walks is the structure the eye reads, and every cell announces its own row, column and value.
+- Lightness is the only channel that is unambiguously ordered, which is why the standing advice everywhere else is “one hue, light to dark”. Here there is no hue left to get wrong.
+- A null is drawn as a dashed outline, never as the palest cell — a missing reading is not a zero.
+- Pin domain whenever two grids are compared: on independent domains they look alike and mean different things, which is the one failure a shared legend cannot fix.
+
+## Heatmap
+
+A grid of values read by weight — a calendar of activity, a confusion matrix, an hour-by-weekday load. The one form in the set that a monochrome system renders BETTER than a chromatic one. A heatmap needs a scale whose order the eye can read without consulting a legend, and lightness is the only channel that is unambiguously ordered — which is why "one hue, light to dark" is the standing advice everywhere else, and why the rainbow heatmap is a perennial mistake. Here there is no hue left to get wrong. It is built as a real `<table>` rather than as an SVG, so the structure a screen reader walks is the structure the eye reads: a header row, a header column, and a cell that announces its own value. Nothing else in the package can say that, and nothing else needs to — which is also why this one takes no rendering engine at all.
+
+### Props
+
+- `title` (required) — `string`. What the grid shows. Required, and it names the table.
+- `showTitle` — `boolean` default `false`. 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.
+- `columns` (required) — `string[]`. Column headers, in the order they should appear.
+- `rows` (required) — `string[]`. Row headers, in the order they should appear.
+- `cells` (required) — `HeatmapCell[]`.
+- `scale` — `HeatmapScale` default `'sequential'`.
+- `domain` — `[number, number]`. The domain, as `[min, max]`. Derived from the data when omitted. Pin it whenever two grids are meant to be compared: two heatmaps on independent domains look alike and mean different things, which is the one failure a shared legend cannot fix.
+- `formatValue` — `(value: number) => string` default `(value) => value.toLocaleString()`. Formats a value for the cell's announcement and its printed label.
+- `showValues` — `boolean` default `false`. Prints the number inside each cell. Only legible on a coarse grid.
+- `className` — `string`.
+
+## Types
+
+- `HeatmapScale` = `'sequential' | 'diverging'`
+
+## Examples
+
+```tsx
+<Heatmap
+  title="Commits by weekday and hour"
+  columns={hours}
+  rows={weekdays}
+  cells={cells}
+/>
+```

package/dist/agent/Histogram.md

@@ -0,0 +1,63 @@
+# Histogram
+
+The shape of one distribution.
+
+- Group: Charts
+- Import: `import { Histogram } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/histogram/
+- Related: box-plot, bar-chart
+
+## When to reach for it
+
+A single distribution has to be understood — two clusters, a hard floor, a pile-up at a timeout. Several distributions side by side want a BoxPlot.
+
+## Accessibility
+
+- The shape is a property of the bin width, not only of the data: the same numbers cut into eight buckets and into eighty are two different pictures. The rule that drew it — Freedman–Diaconis by default — is named on the page.
+- The x axis is numeric and every bar is drawn from its own two edges, so an uneven bucket is as wide as it really is rather than flattened into an equal slot.
+- mode="density" corrects the trap uneven buckets create: under frequency a bucket twice as wide stands twice as tall at the same underlying rate.
+- The hidden data table prints each bucket’s two edges and its count, which is the only exact reading a binned chart can offer.
+
+## Histogram
+
+The shape of one distribution — where the mass sits, how it leans, whether there is more than one hump in it. The form that answers what a `<BoxPlot>` structurally cannot: two clusters, a hard floor, a pile-up at a timeout value. Reach for the box plot when several distributions have to be compared side by side, and for this one when a single distribution has to be understood. **A histogram's shape is a property of its bin width, not only of its data.** The same numbers cut into eight buckets and into eighty are two different pictures, and a gap between two humps can be created or erased by moving a bin edge. That is not a defect to be fixed, it is what binning IS, and the defence is to say which rule drew the picture — the default here is Freedman–Diaconis — and to look at more than one width before believing a feature. Uneven buckets add a second trap: under `frequency` a bucket twice as wide stands twice as tall at the same underlying rate, which is what `mode="density"` exists to correct. Recharts earns its place here for the axes, the grid and the tooltip, but not for the bars: a bar chart's bars are positioned by CATEGORY and a histogram's are positioned and SIZED by a continuous measurement. So the x axis is numeric and each bar is drawn from its own two edges — which is what lets an uneven bucket be as wide as it really is instead of being flattened into an equal slot beside its neighbours.
+
+### Props
+
+- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a histogram has one distribution and as many bars as it has buckets.
+- `values` — `number[]`. The raw observations, in any order. Binned for you by `bins`. Give this OR `data`, not both — `data` wins if both arrive.
+- `data` — `HistogramBin[]`. Buckets that were counted somewhere else — by a database, by a sketch, by a metrics backend that only ever ships histograms. Uneven bucket widths are drawn at their real widths, which is the whole reason this takes edges rather than labels. Set `mode="density"` when they are uneven, or the wide buckets will read as tall ones.
+- `bins` — `number | number[]`. How to cut `values` up: a number of equal-width bins, or the explicit edges. Defaults to Freedman–Diaconis (`2 × IQR × n^(-1/3)`), falling back to Sturges when the interquartile range is zero.
+- `mode` — `HistogramMode` default `'frequency'`. What the bar heights mean. `frequency` is the count in each bucket and is what a reader assumes. `density` is `count / (n × bin width)`, so the total area is 1 — which is what makes two histograms of different sample sizes comparable, and what makes uneven buckets honest.
+- `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 `<Histogram.Bars>`.
+- `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.
+- `formatValue` — `(value: number) => string` default `defaultTick`. Formats the measured values — bin edges, ticks, the tooltip's heading.
+- `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
+
+- `HistogramMode` = `'frequency' | 'density'`
+
+## Examples
+
+```tsx
+<Histogram title="Response times" values={samples} bins={20}>
+  <Histogram.Grid />
+  <Histogram.XAxis label="ms" />
+  <Histogram.YAxis />
+  <Histogram.Tooltip />
+  <Histogram.Bars />
+</Histogram>
+// Buckets that arrived already counted, with uneven widths.
+<Histogram title="Payload size" data={buckets} mode="density">
+  <Histogram.XAxis />
+  <Histogram.YAxis />
+  <Histogram.Bars />
+</Histogram>
+```

package/dist/agent/Input.md

@@ -0,0 +1,30 @@
+# Input
+
+A single line of text entry.
+
+- Group: Forms
+- Import: `import { Input } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/input/
+- Related: field, textarea
+
+## Accessibility
+
+- A placeholder is not a label — it disappears the moment anyone types. Pair with Field.
+
+## Input
+
+A single line of text entry. Shares `CONTROL_BASE` with Textarea and Select, so the three cannot drift apart. Pair with `Field` for the label, hint and error — an input with a placeholder and no label is not labelled, because the placeholder disappears the moment anyone types.
+
+### Props
+
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `ref` — `Ref<HTMLInputElement>`.
+
+Also accepts: `InputHTMLAttributes<HTMLInputElement>`.
+
+## Examples
+
+```tsx
+<Field label="Email" htmlFor="email"><Input id="email" type="email" /></Field>
+```

package/dist/agent/Kbd.md

@@ -0,0 +1,29 @@
+# Kbd
+
+A key on a keyboard, set as one.
+
+- Group: Display
+- Import: `import { Kbd } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/kbd/
+- Related: badge
+
+## Accessibility
+
+- Renders <kbd>, which carries the meaning a styled <span> does not.
+
+## Kbd
+
+A key on a keyboard, set as one. Renders a `<kbd>`, which is the element that means this — a `<span>` styled to look like a key tells a screen reader nothing. Sized in `em` so it tracks whatever type it sits beside rather than fixing itself at one px value, which is how the same shortcut ended up three different sizes across a page.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to open the palette.
+```

package/dist/agent/LineChart.md

@@ -0,0 +1,60 @@
+# LineChart
+
+Several series compared over a continuous axis.
+
+- Group: Charts
+- Import: `import { LineChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/line-chart/
+- Related: area-chart, composed-chart
+
+## When to reach for it
+
+The reader is comparing series against each other. When the area under one line is the point, fill it — that is an AreaChart.
+
+## Accessibility
+
+- title is required; the rows are also rendered as a visually hidden table.
+- A clickable line gets a 15px transparent line underneath it, because a 1.6px stroke is not a pointer target.
+- buffer draws the last segment dashed by measuring the real path length, so a projection is visibly a different kind of fact at any curve type.
+
+## LineChart
+
+Several series compared over a continuous axis — the shape for "which of these is going where". The difference from `<AreaChart>` is what the reader is asked to do: an area says "read the magnitude under this", a line says "compare these against each other". Filling four overlapping series makes the second question unanswerable, which is why a line chart has no fill variant to offer.
+
+### 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 RechartsLineChart>`. Escape hatch onto the raw Recharts chart element.
+- `curveType` — `ChartCurveType` default `'linear'`. How the line between two points is interpolated. Every mark inherits it unless it says otherwise.
+- `animationType` — `ChartRevealType` default `'forward'`.
+- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render. Selection dims every other series.
+- `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.
+- `loadingPoints` — `number`. How many points 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
+
+- `LineStrokeVariant` = `AreaStrokeVariant`
+
+## Examples
+
+```tsx
+<LineChart title="Visitors per month" config={config} data={data}>
+  <LineChart.Grid />
+  <LineChart.XAxis dataKey="month" />
+  <LineChart.Tooltip />
+  <LineChart.Line dataKey="desktop">
+    <LineChart.Dot variant="border" />
+  </LineChart.Line>
+</LineChart>
+```

package/dist/agent/LinkArrow.md

@@ -0,0 +1,29 @@
+# LinkArrow
+
+The mark on a link that leaves the page.
+
+- Group: Display
+- Import: `import { LinkArrow } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/link-arrow/
+
+## Accessibility
+
+- aria-hidden, so it is not read as “north east arrow” in the middle of a sentence.
+- Sized in em, so it tracks whatever type it sits beside instead of competing with it.
+
+## EXTERNAL_LINK_ARROW
+
+The glyph itself, exported so a non-React surface can use the same mark.
+
+## LinkArrow
+
+The mark on a link that leaves the page — outbound, or on to a full index. Call sites used to write a bare `↗` inside the link text, which inherited the link's own size (a 17px arrow beside a 17px word, competing with it) and was read aloud as "north east arrow" because nothing hid it. `inline-block` is load-bearing twice over: it stops an underlined parent drawing its rule through the glyph, and it is what `align` is measured against. Sized in `em`, so it tracks whatever type it sits beside; coloured against paper, so a call site on a reversed plate passes its own colour.
+
+Also accepts: `HTMLAttributes<HTMLSpanElement>`.
+
+## Examples
+
+```tsx
+<a href="https://example.com">Read the paper<LinkArrow /></a>
+```

package/dist/agent/NativeSelect.md

@@ -0,0 +1,40 @@
+# NativeSelect
+
+The platform’s own picker, restyled where it can be.
+
+- Group: Forms
+- Import: `import { NativeSelect } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/native-select/
+- Related: select, field
+
+## When to reach for it
+
+The escape hatch, not the default. Reach for it where the platform genuinely wins: a very long list on a phone, a form that must work without JavaScript, a page counting its last kilobyte.
+
+## Accessibility
+
+- Typeahead and the mobile wheel come free, from the browser.
+- What it cannot do is look like the rest of the system once open — the option list is drawn by the operating system and carries none of these tokens.
+
+## Keyboard
+
+- Space / ↓ — Opens the platform picker.
+- a–z — Typeahead, from the browser’s own implementation.
+
+## NativeSelect
+
+A native `<select>`, restyled. The escape hatch, not the default — `Select` is the styled one. Reach for this where the platform's own picker is genuinely better: a very long list on a phone, a form that must work without JavaScript, a page where the last kilobyte matters. The browser gives typeahead and the mobile wheel for free, and those are real. What it cannot do is look like the rest of the system once open. The option list is drawn by the operating system, so it carries none of these tokens — which is exactly why it stopped being the default.
+
+### Props
+
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `ref` — `Ref<HTMLSelectElement>`.
+
+Also accepts: `SelectHTMLAttributes<HTMLSelectElement>`.
+
+## Examples
+
+```tsx
+<NativeSelect defaultValue="au"><option value="au">Australia</option></NativeSelect>
+```

package/dist/agent/NavItem.md

@@ -0,0 +1,35 @@
+# NavItem
+
+A row in a sidebar.
+
+- Group: Navigation
+- Import: `import { NavItem } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/nav-item/
+- Related: app-shell
+
+## Accessibility
+
+- aria-current="page" and not only a colour: the active row is also carried by weight and a filled ground.
+
+## NavItem
+
+A row in a sidebar. `aria-current="page"` and not only a colour: the active row has to be identifiable to a reader who cannot see that it is darker. In this system it is also carried by weight and by a filled ground, so it survives monochrome printing and low contrast. Framework-agnostic. `asChild` is how a Next or React Router app gets client-side navigation without this package importing either.
+
+### Props
+
+- `href` (required) — `string`.
+- `icon` — `LucideIcon`. Optional leading icon (a lucide-react component, rendered at 18px).
+- `active` — `boolean` default `false`. Marks the current route. Also sets `aria-current="page"`.
+- `asChild` — `boolean` default `false`. Hand the styling to a router's own `Link` instead of a native `<a>`. The slotted child receives the classes and `aria-current`, and becomes the row — so `icon` is not rendered in this mode; put it inside the child.
+- `children` (required) — `ReactNode`.
+- `className` — `string`.
+
+Also accepts: `Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className' | 'children'>`.
+
+## Examples
+
+```tsx
+<NavItem href="/components/button" icon={Square} active>Button</NavItem>
+<NavItem asChild href="/work"><Link href="/work">Work</Link></NavItem>
+```

package/dist/agent/Pagination.md

@@ -0,0 +1,43 @@
+# Pagination
+
+Numbered pages, with the middle elided.
+
+- Group: Navigation
+- Import: `import { Pagination } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/pagination/
+- Related: breadcrumb
+
+## Accessibility
+
+- The current page is a button with aria-current, not a styled span — a reader jumping by control needs to find it.
+- Renders nothing at one page. A pager for a single page is furniture.
+
+## Keyboard
+
+- Tab — Reaches every control, including the current page.
+- Enter / Space — Goes to that page.
+
+## paginationRange
+
+Builds the visible page list: always the first and last page, a window around the current one, and an ellipsis wherever the sequence skips. Returned as numbers and a literal ellipsis rather than as pre-rendered nodes, so the shape is testable without a DOM — the off-by-one at the window edges is the whole difficulty of this component.
+
+## Pagination
+
+Numbered pagination. The current page is marked by one filled pill that TRAVELS between the numbers rather than by a background switching off on one and on on another. Two backgrounds cross-fading reads as two things changing; a shape moving reads as the one thing that actually did. A `<nav>` wrapping a list, and the current page is a `<button aria-current>` rather than a styled `<span>` — a reader jumping by landmark needs to find the control, and a reader on the current page needs to be told they are already there. Renders nothing at one page or fewer. A pager for a single page is furniture.
+
+### Props
+
+- `page` (required) — `number`. 1-based.
+- `pageCount` (required) — `number`. Total pages. A value of 1 or less renders nothing.
+- `onPageChange` (required) — `(page: number) => void`.
+- `siblings` — `number` default `1`. How many numbered pages sit either side of the current one.
+- `label` — `string` default `'Pagination'`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'onChange'>`.
+
+## Examples
+
+```tsx
+<Pagination page={page} pageCount={12} onPageChange={setPage} />
+```

package/dist/agent/PieChart.md

@@ -0,0 +1,55 @@
+# PieChart
+
+Parts of one whole.
+
+- Group: Charts
+- Import: `import { PieChart } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/pie-chart/
+- Related: radial-chart, bar-chart
+
+## When to reach for it
+
+Roughly what share, and nothing more precise. Ranking or comparing wedges — especially across two pies — is a BarChart’s job.
+
+## Accessibility
+
+- title is required; the rows are also rendered as a visually hidden table.
+- The legend sits under the pie by default, because a pie has no category axis naming its sectors.
+- Compose a Label to print the numbers on the wedges: a pie’s weakness is that an angle is hard to read, and a printed number removes the guess.
+- One fill variant, deliberately. A wedge is small and awkwardly shaped, and a texture inside one reads as noise.
+
+## PieChart
+
+Parts of one whole. Worth saying plainly: a pie answers "roughly what share" and nothing more precise. Comparing two adjacent wedges by eye is unreliable past about five of them, and comparing a wedge across two pies is worse. When the reader needs to rank or compare, a `<BarChart>` answers the same question better.
+
+### Props
+
+- `config` (required) — `ChartConfig`. Sector names → their label and paint. Keys must match the `nameKey` values.
+- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
+- `dataKey` (required) — `keyof TData & string`. The row field holding each sector's number.
+- `nameKey` (required) — `keyof TData & string`. The row field holding each sector's name.
+- `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 RechartsPieChart>`. Escape hatch onto the raw Recharts chart element.
+- `defaultSelectedSector` — `string | null` default `null`. The sector lit on first render.
+- `onSelectionChange` — `(selection: { name: string; value: number } | 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.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+
+## Types
+
+- `PieVariant` = `'gradient'`
+
+## Examples
+
+```tsx
+<PieChart title="Visitors by browser" config={config} data={data} dataKey="visitors" nameKey="browser">
+  <PieChart.Pie innerRadius="55%" />
+  <PieChart.Tooltip />
+  <PieChart.Legend />
+</PieChart>
+```