@misoto22/design 0.5.0 → 0.6.0

package/dist/agent/BarChart.md

@@ -0,0 +1,65 @@
+# BarChart
+
+Discrete categories compared by length.
+
+- Group: Charts
+- Import: `import { BarChart } from '@misoto22/design'`
+- Version: 0.6.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.
+
+## 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. 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.
+- `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,40 @@
+# BarList
+
+A ranked list, with the bar behind the name rather than beside it.
+
+- Group: Data
+- Import: `import { BarList } from '@misoto22/design'`
+- Version: 0.6.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.
+
+## 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`.
+
+## Examples
+
+```tsx
+<BarList label="Top referrers" items={referrers} limit={5} />
+```

package/dist/agent/BigNumber.md

@@ -0,0 +1,45 @@
+# BigNumber
+
+One number, at the size of a headline.
+
+- Group: Data
+- Import: `import { BigNumber } from '@misoto22/design'`
+- Version: 0.6.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.
+
+## 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.
+- `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,58 @@
+# BoxPlot
+
+The spread of a measurement, per category.
+
+- Group: Charts
+- Import: `import { BoxPlot } from '@misoto22/design'`
+- Version: 0.6.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.
+
+## 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,32 @@
+# Breadcrumb
+
+Where you are, as a path.
+
+- Group: Navigation
+- Import: `import { Breadcrumb } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/breadcrumb/
+- Related: pagination
+
+## 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”.
+
+## 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".
+
+### 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,48 @@
+# BulletChart
+
+A measure, its target, and the bands that say whether it is any good.
+
+- Group: Data
+- Import: `import { BulletChart } from '@misoto22/design'`
+- Version: 0.6.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.
+
+## 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,56 @@
+# Button
+
+The system’s action, on the same corner as the field beside it.
+
+- Group: Actions
+- Import: `import { Button } from '@misoto22/design'`
+- Version: 0.6.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.
+
+## 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>
+```

package/dist/agent/Calendar.md

@@ -0,0 +1,42 @@
+# Calendar
+
+A month, as a grid of days.
+
+- Group: Surfaces
+- Import: `import { Calendar } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/calendar/
+- Related: date-picker
+
+## When to reach for it
+
+On its own for a range view or an availability grid; inside a DatePicker for choosing one.
+
+## Accessibility
+
+- Arrows move a day, Page keys move a month, Home and End reach the week’s ends.
+- “Today” is an outline and “selected” is a fill — one is a fact about the calendar, the other a choice the reader made, and they must not look alike.
+- Month and year are the system’s own Select, not the platform’s: a native list of a hundred years is a scroll rather than a choice, and it arrives styled by the operating system.
+- The default span is ten years either side. A birth date needs a wider one, and asks for it with startMonth.
+
+## Keyboard
+
+- ← / → — Moves by a day.
+- ↑ / ↓ — Moves by a week.
+- Page Up / Page Down — Moves by a month.
+- Home / End — Jumps to the week's first or last day.
+- Enter / Space — Chooses the focused day.
+
+## Calendar
+
+A month, as a grid of days. Wraps react-day-picker rather than building a calendar, and the reason is the long tail: a month grid is easy, and everything around it is not — the keyboard contract (arrows move a day, Page moves a month, Home and End reach the week's ends), the `aria-live` announcement when the month changes, week numbering, the first day of the week varying by locale, and the fact that "today" and "selected" are different states a screen reader must hear apart. Every class is replaced rather than layered over the library's stylesheet, so nothing here depends on a CSS file this package does not control — but the library's OWN class is kept on each slot, because passing a class REPLACES it and every `.rdp-*` selector downstream depends on those.
+
+Also accepts: `DayPickerProps`.
+
+## Examples
+
+```tsx
+<Calendar mode="single" selected={date} onSelect={setDate} />
+// A birth date: widen the years, since the default span is deliberately short.
+<Calendar mode="single" startMonth={new Date(1920, 0)} endMonth={new Date()} />
+```

package/dist/agent/Card.md

@@ -0,0 +1,49 @@
+# Card
+
+A bounded surface, with no shadow under it.
+
+- Group: Surfaces
+- Import: `import { Card } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/card/
+- Related: table, figure-band
+
+## When to reach for it
+
+A card that needs to read as raised is a plate, which separates by reversal instead of by blur.
+
+## Card
+
+A bounded surface. No shadow, by law: depth in this system is a hairline and a change of ground, never a blur. A card that needs to read as raised is a `plate`, which separates by reversal instead. Compose with the named sub-parts, or drop children straight in when the card has no header or footer to speak of.
+
+### Props
+
+- `variant` — `'outline' | 'plate' | 'flat'` default `'outline'`. `outline` is a hairline box on the page ground — the default, and correct for a card sitting among other cards. `plate` fills with the one reversed surface and is for a card that IS the point of its band; use at most one per screen. `flat` drops the border entirely, for a card whose grid already draws the rules between cells.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## CardHeader
+
+Header row — title on the left, an action or marker on the right.
+
+## CardTitle
+
+The card's title, in the editorial serif. An `<h3>` by default, which is right inside a section with its own `<h2>` and wrong nearly everywhere else — pass `as` rather than leaving a page with a heading order that jumps.
+
+## CardBody
+
+The content well.
+
+## CardFooter
+
+A quiet strip for metadata or secondary actions.
+
+## Examples
+
+```tsx
+<Card>
+  <CardHeader><CardTitle>Recent deploys</CardTitle><Badge>12</Badge></CardHeader>
+  <CardBody>…</CardBody>
+  <CardFooter>Updated just now</CardFooter>
+</Card>
+```

package/dist/agent/Checkbox.md

@@ -0,0 +1,35 @@
+# Checkbox
+
+A choice that takes effect when the form is submitted.
+
+- Group: Forms
+- Import: `import { Checkbox } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/checkbox/
+- Related: switch, radio-group
+
+## When to reach for it
+
+A setting that applies immediately is a Switch.
+
+## Accessibility
+
+- Supports the indeterminate state, which is what a “select all” header needs when only some rows are selected.
+
+## Keyboard
+
+- Space — Toggles it.
+
+## Checkbox
+
+A choice that takes effect when the form is submitted. Supports the indeterminate state (`checked="indeterminate"`), which is what a "select all" header needs when only some rows are selected — a plain unchecked box there tells the reader the opposite of the truth. Pair with `Field`, or wrap it in a `<label>` at the call site so the words beside it are part of the click target.
+
+Also accepts: `ComponentProps<typeof CheckboxPrimitive.Root>`.
+
+## Examples
+
+```tsx
+<label className="flex items-center gap-2.5 text-sm">
+  <Checkbox defaultChecked /> Subscribe to updates
+</label>
+```

package/dist/agent/Collapsible.md

@@ -0,0 +1,46 @@
+# Collapsible
+
+One thing that opens, on its own.
+
+- Group: Navigation
+- Import: `import { Collapsible } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/collapsible/
+- Related: accordion
+
+## When to reach for it
+
+The difference from Accordion is arithmetic: an accordion is a SET and can coordinate. An accordion of one manages a value nobody reads.
+
+## Keyboard
+
+- Enter / Space — Opens or closes it.
+
+## Collapsible
+
+Radix Collapsible root, as a typed passthrough.
+
+## CollapsibleTrigger
+
+The trigger and the panel, unstyled, for a disclosure that needs its own layout — a sidebar group whose header carries a count and a chevron on opposite sides, say. `CollapsibleSection` is the composed version and is what most call sites want; these two exist so the ones that do not have to reach for Radix directly and re-derive the keyboard and `aria-expanded` wiring. The panel animates on `--radix-collapsible-content-height`, which Radix measures — so it opens to its real height rather than to a guessed `max-height`, which is what makes a long group and a short one take the same time instead of the long one appearing to stall.
+
+## CollapsibleContent
+
+## CollapsibleSection
+
+One thing that opens, on its own. The difference from `Accordion` is arithmetic: an accordion is a SET, and a set can coordinate — opening one closes another. A collapsible is one disclosure with nothing to coordinate with. Reaching for an accordion of one gets you a component managing a value you never read. The marker here is a chevron rather than the accordion's plus, and deliberately: this reveals more of the same thing, where an accordion row opens a distinct answer.
+
+### Props
+
+- `title` (required) — `ReactNode`. What the trigger says.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `Omit<ComponentProps<typeof CollapsiblePrimitive.Root>, 'children' | 'title'>`.
+
+## Examples
+
+```tsx
+<CollapsibleSection title="Advanced settings">
+  <Field label="Retries"><Input type="number" /></Field>
+</CollapsibleSection>
+```

package/dist/agent/Combobox.md

@@ -0,0 +1,50 @@
+# Combobox
+
+A select you can type into.
+
+- Group: Forms
+- Import: `import { Combobox } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/combobox/
+- Related: select, command
+
+## When to reach for it
+
+Past roughly a dozen options. Below that a native Select is better: the platform picker on a phone, typeahead for free, no JavaScript.
+
+## Accessibility
+
+- The highlight moves through aria-activedescendant while focus stays in the input — the ARIA combobox pattern. Hand-rolled comboboxes move focus into the list, and the typed text stops being editable.
+- label is required: the trigger prints a value, and a value is not a name.
+
+## Keyboard
+
+- Enter / Space / ↓ — Opens the list.
+- ↑ / ↓ — Moves the highlight while focus stays in the filter.
+- Enter — Chooses the highlighted option; choosing the current one clears it.
+- Escape — Closes without choosing.
+
+## Combobox
+
+A select you can type into, choosing one or several. The line against `Select` is length, and it is not a matter of taste: a styled select is better up to roughly a dozen options, because a list nobody can filter is faster to scan than one they have to think about. Past that, this is the right answer. Filtering, the highlighted row and the arrow keys come from cmdk, which implements the ARIA combobox pattern properly: the highlight moves through `aria-activedescendant` while focus stays in the input. Hand-rolled comboboxes move focus into the list instead, and the typed text stops being editable. Controlled or uncontrolled, like every other form control here.
+
+### Props
+
+- `multiple` — `false`.
+- `value` — `string`.
+- `defaultValue` — `string`.
+- `onValueChange` — `(value: string) => void`.
+- `options` (required) — `ComboboxOption[]`.
+- `label` (required) — `string`. Names the control. Required — the trigger's text is a value, not a label.
+- `placeholder` — `string` default `'Select…'`. Shown on the trigger when nothing is chosen.
+- `searchPlaceholder` — `string` default `'Search…'`. Placeholder inside the filter field.
+- `emptyMessage` — `string` default `'Nothing matches.'`. Shown when the filter matches nothing. Say what WOULD match.
+- `disabled` — `boolean` default `false`.
+- `className` — `string`.
+
+## Examples
+
+```tsx
+<Combobox label="Framework" options={FRAMEWORKS} placeholder="Pick one" />
+<Combobox multiple label="Tags" options={TAGS} />
+```