@misoto22/folio 0.0.0 → 0.16.0

package/dist/agent/Calendar.md

@@ -0,0 +1,77 @@
+# Calendar
+
+A month, as a grid of days.
+
+- Kind: component
+- Group: Surfaces
+- Import: `import { Calendar } from '@misoto22/folio'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Day grid** (required) — The month: a mono weekday row over one 36px pill-cornered button per day, five rows in most months and six in some. Days from the neighbouring months are shown and dimmed rather than left as holes.
+- **Caption** (required) — “September 2026” as ONE button carrying aria-expanded, not two dropdowns — that is how the date is said, and splitting it put four controls in a 250px row that also has to hold two arrows.
+- **Month arrows** (required) — The library’s nav, lifted out of the flow and laid across the caption at the same 36px height so the two sit at either end of the month name. Both step away while the picker is open: two ways to change the month, one of them behind a panel, is one too many.
+- **Month and year picker** — A role="dialog" drawn IN PLACE of the day grid rather than over it — twelve months in a 3×4 and up to twenty-four years in a 4×6, at exactly the size of the grid they replace. Focus moves in when it opens and Tab wraps inside it; Escape closes it and puts focus back on the caption.
+- **Day marks** (required) — Today is a ring and selected is a fill. In a range the wash lives on the CELL and the fill on the ends’ BUTTONS, which is what lets a range read as one band with round ends — and lets a one-day range, which is both ends at once, stay round.
+
+## Best practices
+
+### Do
+
+- Pass locale rather than trusting the page’s lang: the caption is formatted by Intl from locale.code and falls back to en-US, so a French calendar says “September” until the prop is set.
+- Re-add the library’s own class when you override a slot through classNames — yours REPLACES ours, and ours carries the .rdp-* hook every downstream selector depends on. Overriding root without rdp-root took that hook off the tree.
+- Mark availability through the classNames slots rather than by styling the day button: the wash belongs to the cell and the mark to the button, and a background put on the button flattens the round end of a range.
+- Know what widening the span costs: the year grid pages 24 at a time, so the default ten either side is one page and no paging, and a range wide enough for a birth date is a reader stepping through pages to reach 1974.
+- Translate the picker’s chrome alongside locale. locale reaches the month names and stops there, so a French calendar with the prop set still names its two panels and its four chevrons “Month and year”, “Previous year” and “Earlier years” until the CalendarLabels props are passed.
+
+### Don’t
+
+- Do not stretch it with a width class: it is w-fit and lays out fixed 36px columns, so w-full only replaces w-fit and leaves the same grid sitting at the start edge of a wider box.
+- Do not cut it to a fixed height. The grid is five weeks in most months and six in some, and the picker panel is sized against the grid rather than given a height of its own — a box measured on a five-week month clips the sixth.
+- Do not replace MonthCaption through components: the month-and-year picker lives inside ours, so a custom caption leaves the reader with two arrows and no way to move more than one month at a time.
+
+## 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 one panel of buttons, not a native select: a platform list of a hundred years is a scroll rather than a choice, and it arrives styled by the operating system.
+- Tab wraps inside the open panel. It is opaque and the day grid is still mounted under it, so a Tab that left would put the reader on a day they cannot see — and past the caption that owns the Escape handler.
+- 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. The month names follow `locale`. The picker's own chrome — the two panels and the four chevrons that browse them — follows `CalendarLabels`, because `locale` cannot supply strings this package invented.
+
+### Props
+
+- `monthPanelLabel` — `string`. Names the panel showing twelve months.
+- `yearPanelLabel` — `string`. Names the panel showing a page of years.
+- `previousYearLabel` — `string`. The two chevrons that browse a year at a time, inside the month panel.
+- `nextYearLabel` — `string`.
+- `earlierYearsLabel` — `string`. The two chevrons that page the year grid, twenty-four at a time.
+- `laterYearsLabel` — `string`.
+
+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/CalendarHeatmap.md

@@ -0,0 +1,75 @@
+# CalendarHeatmap
+
+A year of daily readings, as a week-by-week grid.
+
+- Kind: component
+- Group: Data
+- Import: `import { CalendarHeatmap } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/calendar-heatmap/
+- Related: heatmap, calendar, sparkline
+
+## When to reach for it
+
+The readings are dated and the question is about the calendar. Heatmap is the grid underneath and knows nothing about dates; this is the arrangement everybody writes on top of it and nobody writes the same way twice.
+
+## Anatomy
+
+- **Grid** (required) — A Heatmap: one column per week, one row per weekday, drawn from the dates rather than from the order of the array. Every date is arithmetic on UTC midnights, so the same window renders identically in every timezone.
+- **Window** (required) — from and to, or the earliest and latest date in values when they are left off. The grid runs back to the start of the first week and on to the end of the last, so a column is always a whole week.
+- **Weekday rows** (required) — Seven row headers from weekdayLabels, always Sunday-first in the ARRAY and rotated onto the grid by weekStartsOn — so a Monday-first calendar and a translation are two separate decisions.
+- **Month headers** — A name from monthLabels on the first column each month touches, blank on the rest. The blanks carry a run of zero-width spaces so the grid can still tell them apart, which is what a lookup by column NAME requires.
+- **Gaps** — A day inside the window with no entry, and every day in the leading and trailing partial weeks: a dashed outline with an announced “no data”, never the palest cell on the ramp.
+- **Cell reading** — What describe returns for that day, announced with the cell. Keyed by the cell rather than by the number, so two days with the same count are two different readings.
+
+## Best practices
+
+### Do
+
+- Pass from and to whenever the window is a fact about the question rather than about the data. Derived from the values, a quiet January does not exist — the grid silently becomes a different window from the one beside it, and the two are then compared anyway.
+- Write describe so it names the unit. The row and column a cell is announced with are a weekday and a month over a block of five weeks, so without it the reading a screen reader gets is a date and a bare number.
+- Pin domain to compare two calendars. A quiet year and a busy one drawn on their own domains look identical, and the comparison the reader came for is not merely lost but inverted.
+
+### Don’t
+
+- Do not send a zero for a day nothing was recorded. Null is drawn as a gap and zero as the palest cell, and a page that draws them alike invites the reader to explain an outage that was a hole in collection.
+- Do not hand it dates carrying a time or a zone. Every bound is parsed as a UTC midnight from YYYY-MM-DD, so a timestamp that is 23:00 somewhere lands on the day before it in the grid.
+- Do not reach for it where the rows are not weekdays. An hour-by-weekday load or a confusion matrix is a Heatmap, and going through this one means inventing dates for cells that do not have any.
+
+## Accessibility
+
+- The grid is a real <table>, so a screen reader walks the same structure the eye reads: a header row, a header column, and a cell that announces its own reading.
+- A day with no entry announces “no data” rather than a number, so a gap and a zero are different to a reader who cannot see the ramp.
+- The reading is keyed by the cell, so the date is announced with the count — the row and column headers alone name a weekday and a month, not a day.
+
+## CalendarHeatmap
+
+A year of daily readings, as a week-by-week grid. `Heatmap` draws a grid of named rows and columns and knows nothing about dates; this is the arrangement everybody writes on top of it and nobody writes the same way twice — a column per week, a row per weekday, a month name on the first column it touches, and the days either side of the window left as gaps rather than as zeroes. The grid is built from the DATES rather than from the order of the array, so a gap in the data is a gap on the calendar. That is the failure this exists to prevent: given a bare list of counts, a missing Tuesday shifts every reading after it by one cell, and the result is a plausible picture of a year that did not happen. Every date is arithmetic on UTC midnights. A local-time calendar drawn in two timezones is two different calendars, and the disagreement is exactly one day wide — small enough to survive review and large enough to move a reading into the wrong week.
+
+### Props
+
+- `title` (required) — `string`. What the calendar 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.
+- `values` (required) — `CalendarHeatmapValue[]`. One entry per day that has a reading. Order does not matter; the grid is built from the dates. A day inside the window with no entry is drawn as a gap rather than as a zero, which is the distinction a calendar most often loses: "nothing happened" and "nothing was recorded" are different readings, and a page that draws them alike invites the reader to explain an outage that was a gap in collection.
+- `from` — `string`. The first day the grid covers, as `YYYY-MM-DD`. Defaults to the earliest date in `values`. Give both ends whenever the window is a fact about the QUESTION rather than about the data — "the last year", "this quarter". Derived from the values, a quiet January simply does not exist, and the grid silently becomes a different window than the one beside it.
+- `to` — `string`. The last day the grid covers, as `YYYY-MM-DD`. Defaults to the latest date in `values`.
+- `describe` — `(value: number, date: string) => string`. What each cell announces, given its reading and its date. The default is the date and the number. Reach for this to name the unit — "3 commits on 2026-01-05" — because the row and column headers a cell is announced with are a weekday and a month over a block of five weeks, and neither says which day it was.
+- `weekdayLabels` — `string[]` default `WEEKDAYS`. The seven row headers, Sunday first, whatever `weekStartsOn` is. Sunday first in the ARRAY and not on the grid: the labels are a translation and the first column is a calendar convention, and tying the two together would make a Monday-first German calendar a different array from a Monday-first English one.
+- `monthLabels` — `string[]` default `MONTHS`. The twelve column headers, January first.
+- `weekStartsOn` — `0 | 1 | 2 | 3 | 4 | 5 | 6` default `0`. Which weekday the grid's first row is. `0` is Sunday, `1` Monday.
+- `domain` — `[number, number]`. The domain, as `[min, max]`. Derived from the readings when omitted. Pin it whenever two calendars are meant to be compared: a quiet year and a busy one drawn on their own domains look identical, and the comparison the reader came for is not merely lost but inverted.
+- `className` — `string`.
+- `empty` — `ChartEmptyProps`. What the grid shows when there is no window to draw.
+
+## Examples
+
+```tsx
+<CalendarHeatmap
+  title="Commits per day"
+  values={days}
+  from="2026-01-01"
+  to="2026-12-31"
+  describe={(value, date) => `${value} commits on ${date}`}
+/>
+```

package/dist/agent/Card.md

@@ -0,0 +1,72 @@
+# Card
+
+A bounded surface, with no shadow under it.
+
+- Kind: component
+- Group: Surfaces
+- Import: `import { Card } from '@misoto22/folio'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Box** (required) — A <div> with the --radius-lg corner and one of three grounds: outline, a hairline on the page ground and the default; plate, the one reversed feature surface; flat, no border at all, for a card whose grid already draws the rules between cells. It brings no padding, and it clips to its own corner.
+- **Header** — CardHeader — a space-between row above a hairline, px-5 py-4: title against the start edge, one marker or action against the end.
+- **Title** — CardTitle, in the editorial serif at --fs-item. An <h3> unless as says otherwise, and it reads --card-title rather than --ink directly, which is what keeps it legible when plate re-points that variable.
+- **Body** — CardBody — the content well at p-5, --ink-2, relaxed leading.
+- **Footer** — CardFooter — a quiet strip under a hairline, mono-meta at --ink-3-aa, for metadata or a secondary action.
+
+## Best practices
+
+### Do
+
+- Pass as on CardTitle: h3 is right inside a section that owns an h2 and wrong nearly everywhere else, and a grid of twelve cards is otherwise twelve h3s with no heading above them to belong to.
+- Use CardTitle inside a plate rather than your own heading — plate re-points --card-title to --on-feature, and a title that reads --ink directly came out at 1.25:1 on that ground: invisible, and invisible only on the one variant whose job is to look different.
+- Add the padding yourself when you skip the sub-parts: the box has none of its own, so children dropped straight in sit against the border.
+- Pass overflow-visible for the card that deliberately overhangs — a marker pinned to its edge, a control that breaks the outline. The box clips by default, because a card that rounds and does not clip lays a full-bleed image’s square corners over its round ones.
+
+### Don’t
+
+- A Card with an onClick is a div with an onClick — not focusable, not announced, unreachable by keyboard. Put a real control inside and let it stretch, so what is announced is a button and the whole card is still the target.
+- Do not spend plate more than once on a screen: it is the system’s single reversed surface, and a band of plates is a band with no ground left to reverse against.
+
+## 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. It clips to its own corner. A card that rounds and does not clip lays a full-bleed image's square corners over its round ones at all four corners, and the same goes for a filled first child — a defect that is invisible until the first card with an image at the top of it. Pass `overflow-visible` for the rarer card that deliberately overhangs. 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,57 @@
+# Checkbox
+
+A choice that takes effect when the form is submitted.
+
+- Kind: component
+- Group: Forms
+- Import: `import { Checkbox } from '@misoto22/folio'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Box** (required) — An 18px <button role="checkbox"> on --radius-xs. It fills with --accent for BOTH checked and indeterminate, so the fill says “not off” rather than “on”.
+- **Tick** — The check glyph, aria-hidden — Radix shows the indicator, the state is carried by the role.
+- **Dash** — The minus that replaces the tick, chosen from the state the box is actually in — controlled or not, so defaultChecked="indeterminate" draws the dash it promised rather than a tick.
+- **Label** — Not rendered here. Unlike RadioGroupItem, nothing wraps the box in a <label>, so the words beside it and the click target they give it are the call site’s job.
+
+## Best practices
+
+### Do
+
+- Wrap it and its words in a <label>, or put it in a Field: the control renders no label of its own, so a bare Checkbox has no accessible name and an 18px box is the entire click target.
+- Hold an indeterminate box on controlled state. It is a report about OTHER rows, and clicking it hands you true — a “select all” header that keeps its own answer stops describing the list underneath it on the first click.
+- Default the value on the server. An unticked box sends no entry at all in a form submission, so the field a reader deliberately cleared and a field that was never rendered arrive identically as undefined.
+
+### Don’t
+
+- checked without onCheckedChange gives a box that never moves: Radix treats the prop as the source of truth, so the reader clicks a control that is neither broken nor working and gets no feedback either way.
+- There is no readOnly on a Radix checkbox. disabled is the only lock and it drops the box out of the tab order and out of the form, so a value that must be shown but not changed is better drawn as text.
+- Do not put the indeterminate state on a leaf. It means “some of the things under this one”, so a box with nothing under it that draws a dash is reporting a state its own value cannot hold.
+
+## 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. Controlled or not: the glyph follows the state the box is actually in, so an uncontrolled `defaultChecked="indeterminate"` draws the dash rather than the tick that says the opposite. 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/Code.md

@@ -0,0 +1,51 @@
+# Code
+
+A function name or a flag, inside a sentence.
+
+- Kind: component
+- Group: Display
+- Import: `import { Code } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/code/
+- Related: code-block, kbd
+
+## When to reach for it
+
+Inline code within running text. A multi-line snippet is a CodeBlock.
+
+## Anatomy
+
+- **Chip** (required) — A real <code> on the --radius-sm corner, filled with --stone. Sized at 0.85em rather than in pixels, so the same token is proportionate in body copy, in a caption and in a table cell.
+
+## Best practices
+
+### Do
+
+- Use it for anything the reader would type or the machine would read: a flag, a path, a function, an env var name. The mono face is the signal that the string is literal.
+- Let it inherit its size. It is set in em on purpose — fixed at one pixel value, the identical token comes out three different sizes on one page depending on where it landed.
+
+### Don’t
+
+- Do not hand it a multi-line string. It keeps no whitespace and draws no plate, so the snippet collapses into one run — that is CodeBlock’s job.
+- Do not style a <span> to look like this instead. The element is the whole point: a mono span reads identically and tells a screen reader nothing, and "pass dash dash force" is not what the sentence said.
+
+## Accessibility
+
+- Renders <code>, which is what tells assistive tech the run is literal rather than prose.
+
+## Code
+
+A function name, a flag, a filename — inside a sentence. Renders a `<code>`, which is the element that means this. A `<span>` in a mono face looks identical and tells a screen reader nothing, and "pass dash dash force" is not what the sentence said. Sized in `em` rather than in pixels, so the chip tracks whatever type it sits beside — the same rule `Kbd` follows, and for the same reason: fixed at one value, the identical token came out three different sizes on one page depending on whether it landed in body copy, a caption or a table cell. The block form is `CodeBlock`. This one is inline by construction: it draws no plate, keeps no whitespace, and a multi-line string handed to it collapses into one run.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+Pass <Code>--force</Code> to overwrite the existing file.
+The helper lives in <Code>src/lib/cn.ts</Code>.
+```

package/dist/agent/CodeBlock.md

@@ -0,0 +1,77 @@
+# CodeBlock
+
+A multi-line snippet, on a plate, with a way to take it away.
+
+- Kind: component
+- Group: Display
+- Import: `import { CodeBlock } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/code-block/
+- Related: code, markdown, article
+
+## When to reach for it
+
+Any snippet longer than a word. Pass html when a build-time highlighter has already run; pass code alone when it has not.
+
+## Anatomy
+
+- **Plate** (required) — The --paper-2 box on the --radius-lg corner with a --rule hairline. One elevated step, not a second surface colour.
+- **Strip** — The bar along the top: title at the start, the language label at the end, the copy button after it. Present whenever there is anything to put in it, and never a hover-only affordance.
+- **Copy button** — A ghost iconOnly Button that puts code — the string, never the rendered markup — on the clipboard, and flips its own accessible name to “Copied” for 1.6 seconds.
+- **Body** (required) — A focusable, named role="group" that scrolls in both axes. Focusable because a scrollable box containing nothing focusable is unreachable by keyboard: there is nothing to Tab to, so the right-hand half of a long line does not exist without a mouse. A group and not a region, because a region is a landmark and a snippet is not one — three fenced blocks in an article would be three landmarks all called Code.
+- **Line row** — One <span data-line> per line on the plain path, carrying its own number and its own highlight band. The number is a child of the line it numbers, so the two cannot come apart.
+
+## Best practices
+
+### Do
+
+- Always pass code, even alongside html. It is what the copy button copies: a block that copies its rendered markup hands the reader a wall of spans, and one that scrapes textContent back out of the DOM is a non-breaking space away from pasting something that does not run.
+- Highlight at build time and pass html. A highlighter is a few hundred kilobytes of grammar shipped to re-derive spans that never change, which would be the largest thing on the page.
+- Give maxHeight to a long snippet rather than letting it run. The body scrolls and is focusable, so what is past the fold stays reachable by keyboard.
+
+### Don’t
+
+- lineNumbers and highlightLines are typed out of the html form and passing both is a compile error. They are a per-line structure, and html is one opaque string the component does not parse — which is why the type says so rather than the prop quietly rendering nothing.
+- html is dangerouslySetInnerHTML. It is for the output of your own highlighter over your own source; markdown a reader wrote goes to code as a string, where it renders as text and cannot be mis-executed.
+- Do not drop copyable to tidy the strip. The button is the reason a reader stops selecting a wrapped command by hand, and on a touch screen a manual selection is most of the interaction.
+
+## Accessibility
+
+- The scrolling body is tabbable and carries role="group" with a name, so its overflow is reachable with a keyboard and the tab stop announces what it is. Deliberately not role="region": that is a landmark, and a page with two code samples would put two of them in the landmark map under one name.
+- The copy button is an iconOnly Button with a required aria-label that becomes “Copied” on success — the state change is announced rather than only drawn.
+- The copy control clears the 44px pointer target on a coarse pointer, where the compact strip alone would not (WCAG 2.5.5).
+
+## CodeBlock
+
+A multi-line snippet, on a plate, with a way to take it away. A labelled block has a strip for its title, language and copy button. Without a label, copying sits beside the code in the same row. It is deliberately not a hover affordance: a control that appears on hover does not exist on a touch screen, which is where a reader is most likely to want the snippet and least able to select it by hand. Line numbers live INSIDE their own line's row rather than in a parallel gutter column. Two columns sharing a line-height align right up until one of them wraps, ships a different font, or scrolls on its own; a number that is a child of the line it numbers cannot come apart from it. The cost is that a number scrolls away with its line: it is inside the scrolling box, not in a gutter beside it. A gutter that stayed put would be a second column to keep in sync, which is the failure this avoids. The body is a focusable, named `role="group"`, and both halves of that are load-bearing. Focusable, because a scrollable box whose contents are not themselves focusable is unreachable by keyboard — there is nothing to Tab to and therefore no way to press an arrow key at it, so the right-hand half of a long line does not exist for anyone not using a mouse. Named, because a tab stop that announces nothing lands the reader in an anonymous box and leaves them to work out what they have arrived in. `group` rather than `region`, and that is the deliberate half. A region is a LANDMARK — one of the handful of major sections a reader navigates a whole page by — and a snippet is not one of those. Three fenced blocks in one article would put three landmarks called "Code" into that map, which is exactly the noise the `landmark-unique` rule exists to catch, and it would push the page's real landmarks down a list nobody can now skim. `group` carries the same accessible name to the same reader on the way in, and carries it nowhere else. For a function name inside a sentence, reach for `Code`.
+
+### Props
+
+- `code` (required) — `string`. The snippet, verbatim. Required even when `html` is supplied, and that is the point: this is what the copy button puts on the clipboard. A block that copies its own rendered markup hands the reader a wall of `<span>`s, and one that copies `textContent` scraped back out of the DOM is a single non-breaking space away from pasting something that does not run.
+- `title` — `string`. A filename or a caption, printed at the start of the strip.
+- `lang` — `string`. The language, printed at the end of the strip. Optional, and the omission is visible rather than silent: a block with no language gets no label instead of claiming a wrong one. A code block that does not say what it is written in makes the reader infer it from the syntax, which is the one thing they came to the block to learn.
+- `maxHeight` — `number | string`. Caps the block's height and scrolls past it. A number is pixels; a string is any CSS length (`'24rem'`, `'50vh'`). The body scrolls in both axes and is focusable, so what is past the fold stays reachable with a keyboard rather than merely present in the DOM.
+- `copyable` — `boolean` default `true`. Drops the copy button, for a block nobody is meant to run.
+- `copyLabel` — `string` default `'Copy the snippet'`. Accessible copy action, supplied by the host locale.
+- `copiedLabel` — `string` default `'Copied'`. Accessible confirmation after copying.
+- `label` — `string`. Names the scrollable body for a screen reader. Defaults to `title`, and to "Code" when there is not one.
+- `className` — `string`.
+- `html` — `undefined`. Absent on this form; `string` on the other. Pass pre-highlighted markup — Shiki's output, run at build time over this same `code` — and the block renders that instead of the plain text. Doing so takes `lineNumbers` and `highlightLines` away with it.
+- `lineNumbers` — `boolean` default `false`. Numbers every line, counting from one.
+- `highlightLines` — `number[]`. Lines to band, counting from one. A number past the end of the snippet is ignored rather than throwing — the usual cause is a snippet that got shorter while the annotation did not.
+
+## Examples
+
+```tsx
+<CodeBlock code="pnpm add
+<CodeBlock
+  title="cn.ts"
+  lang="ts"
+  lineNumbers
+  highlightLines={[2]}
+  maxHeight="24rem"
+  code={source}
+/>
+// Highlighted at build time by the site's own Shiki pass.
+<CodeBlock code={source} html={highlighted} lang="tsx" />
+```

package/dist/agent/Collapsible.md

@@ -0,0 +1,68 @@
+# Collapsible
+
+One thing that opens, on its own.
+
+- Kind: component
+- Group: Navigation
+- Import: `import { Collapsible } from '@misoto22/folio'`
+- Version: 0.16.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.
+
+## Anatomy
+
+- **Root** (required) — Collapsible — Radix’s root, holding open or defaultOpen and drawing nothing. CollapsibleSection is the same root with the trigger and panel already composed, and is what most call sites want.
+- **Trigger** (required) — A plain <button> carrying aria-expanded and aria-controls — and, unlike an accordion row, wrapped in no heading at all. Nothing here appears in a document outline.
+- **Marker** (required) — A chevron rotating 180°, chosen against the accordion’s plus on purpose: this reveals more of the same thing, where an accordion row opens a distinct answer.
+- **Panel** — Radix’s Content, unmounted while closed and animating on the measured --radix-collapsible-content-height, so a long group and a short one take the same time. A bare div: no region role and no name of its own, again unlike an accordion’s. Both this and the loose CollapsibleContent carry data-folio-animated, so the two agree under prefers-reduced-motion rather than only one of them honouring it.
+
+## Best practices
+
+### Do
+
+- Give the trigger a heading of your own when the section is a section: Accordion wraps every trigger in an <h3> and this deliberately wraps none, so a page built from CollapsibleSections has nothing for heading navigation to stop at.
+- Reach for the loose CollapsibleTrigger and CollapsibleContent only when the header has to hold more than a title — a count on one side, a switch on the other. They exist so that call site does not go to Radix and re-derive aria-expanded by hand.
+- Set defaultOpen when what it hides is why the reader came: the closed panel is unmounted rather than hidden, so its text is not in the page for find-in-page, for a print, or for anything reading the rendered DOM.
+- Control it with open and onOpenChange when something outside has to open it — a sidebar group that must expand for the route living inside it cannot be told to from a component that owns its own state.
+
+### Don’t
+
+- Do not build a set out of these: two sections cannot close each other, so the reader ends with every one open and a column to scroll past. That coordination is the whole of what Accordion’s single value buys.
+- Do not flip the title between “Show more” and “Show less”: aria-expanded on the trigger already carries the state, so the row is announced with its state twice and with a new name each time it is pressed.
+
+## 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/Collection.md

@@ -0,0 +1,169 @@
+# Collection
+
+Collection headings, search controls, featured records and empty states.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { ContentBand } from '@misoto22/folio/website'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/collection/
+
+## When to reach for it
+
+Display a searchable archive without moving filtering or data access into the package.
+
+## Best practices
+
+### Do
+
+- Supply localized labels, descriptive links and meaningful image alternatives.
+
+### Don’t
+
+- Do not put service credentials, routing logic or backend models inside presentation components.
+
+## ContentBand
+
+### Props
+
+- `as` — `ElementType`.
+- `tone` — `'base' | 'muted' | 'feature'` default `'base'`.
+- `bleed` — `boolean` default `false`.
+- `spacing` — `'none' | 'content' | 'section'` default `'none'`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## CollectionIntro
+
+### Props
+
+- `title` (required) — `ReactNode`.
+- `description` — `ReactNode`.
+- `context` — `ReactNode`.
+- `media` — `ReactNode`.
+- `actions` — `ReactNode`.
+- `compact` — `boolean` default `false`.
+
+## CollectionMetadata
+
+### Props
+
+- `items` (required) — `CollectionMetadataItem[]`.
+
+## CollectionGroup
+
+### Props
+
+- `title` — `ReactNode`.
+- `caption` — `ReactNode`.
+- `headingId` — `string`.
+- `compact` — `boolean`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.
+
+## CollectionSearch
+
+### Props
+
+- `value` (required) — `string`.
+- `onChange` (required) — `(value: string) => void`.
+- `label` (required) — `string`.
+- `placeholder` — `string`.
+- `clearLabel` (required) — `string`.
+- `focusShortcut` — `boolean` default `false`.
+
+## CollectionControls
+
+### Props
+
+- `items` (required) — `CollectionFilter[]`.
+- `selected` (required) — `string | null`.
+- `onSelect` (required) — `(value: string | null) => void`.
+- `filterLabel` — `string`.
+- `search` — `CollectionSearchProps`.
+- `quiet` — `boolean`.
+- `showCounts` — `boolean` default `true`.
+
+## HighlightedText
+
+### Props
+
+- `text` (required) — `string`.
+- `query` (required) — `string`.
+- `className` — `string`.
+
+## RecordRow
+
+### Props
+
+- `link` — `CollectionLink`.
+- `title` (required) — `ReactNode`.
+- `summary` — `ReactNode`.
+- `context` — `ReactNode`.
+- `media` — `ReactNode`.
+- `index` — `ReactNode`.
+- `metadata` — `ReactNode`.
+- `trailing` — `ReactNode`.
+- `subtitle` — `ReactNode`.
+- `headingLevel` — `2 | 3` default `2`.
+- `variant` — `'editorial' | 'media' | 'compact'` default `'editorial'`.
+
+## FeaturedRecord
+
+### Props
+
+- `media` (required) — `ReactNode`.
+- `title` (required) — `ReactNode`.
+- `context` — `ReactNode`.
+- `summary` — `ReactNode`.
+- `action` — `ReactNode`.
+
+## CollectionEmpty
+
+### Props
+
+- `message` (required) — `string`.
+- `hint` — `string`.
+- `action` — `ReactNode`.
+
+## CollectionFooter
+
+### Props
+
+- `children` — `ReactNode`.
+- `feedback` — `ReactNode`.
+
+## TaxonomyLinks
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `label` — `string`.
+
+## ReferenceLink
+
+A quiet resource link for references, separate from action buttons.
+
+## ReferenceRows
+
+### Props
+
+- `items` (required) — `{ id?: string; label: ReactNode; hint?: ReactNode; content: ReactNode }[]`.
+
+## CollectionTally
+
+### Props
+
+- `children` (required) — `ReactNode`.
+
+## CollectionList
+
+### Props
+
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLUListElement>`.
+
+## Types
+
+- `CollectionLink` = `ReactElement<{ children?: ReactNode }>`