@misoto22/folio 0.0.0 → 0.17.0

package/dist/agent/NumberField.md

@@ -0,0 +1,73 @@
+# NumberField
+
+A number, typed or swept to.
+
+- Kind: component
+- Group: Forms
+- Import: `import { NumberField } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/number-field/
+- Related: input, slider, field
+
+## When to reach for it
+
+The number has a range and a sensible increment. A bare quantity is an Input with type="number"; a value judged by WHERE it sits on a track is a Slider.
+
+## Anatomy
+
+- **Field** (required) — A native number input wearing CONTROL_BASE, so it is the same box as Input, Textarea and Select — same padding, same focus, same disabled opacity. The native spinner buttons are hidden: they are three different controls in three browsers and none of them is this system’s.
+- **Scrub grip** — A horizontal-arrows glyph at the inline start, on unless scrub is false. Dragging it changes the value by one step every 4px, ten steps with Shift held, and it follows the reading direction — in an RTL page, more is to the left. Pointer only and aria-hidden, because the keyboard already has the arrow keys.
+- **Unit** — unit, drawn inside the end of the box and announced through aria-describedby. The slot is a fixed 3rem, so a unit longer than about four characters runs under a long number.
+
+## Best practices
+
+### Do
+
+- Reach for it when a value is TUNED rather than entered — a duration, a line height, an offset. The grip is the whole argument for this over an Input: a reader finds those by sweeping past the neighbouring values, not by typing candidates one at a time.
+- Wrap it in a Field. The root is a div and the id lands on the input inside it, so the label binds and clicks through exactly as it does for an Input — but only if there is a Field to do it.
+- Pass min, max and step. They are what the arrows step by, what one notch of a scrub is worth, and what the value is reconciled with when the field is left; without them the control is an Input with a grip on it.
+
+### Don’t
+
+- Do not expect the range to hold mid-keystroke. Clamping happens on blur, not on every character, because a minimum of 10 otherwise makes 50 unreachable — the 5 is clamped up before the 0 arrives. onValueChange can report a number outside the range; the value that SETTLES is always inside it.
+- Do not turn the grip off and expect a pointer to have another way through. There are no spinner buttons behind it — hiding those is the point — so scrub={false} leaves a mouse with typing and nothing else. Turn it off for a quantity that is chosen rather than swept to, and accept that trade knowingly.
+- Do not put the unit in the box and nowhere else past about four characters. The slot is fixed, so “requests” runs under the number; a long unit belongs in the Field’s label, where it is read rather than clipped.
+
+## Accessibility
+
+- It is a real <input type="number">, so the platform supplies the spinbutton role, the value, and the range it is announced against.
+- unit reaches assistive tech through aria-describedby, so “300” is not announced as a number with no dimension.
+- The grip is aria-hidden and not focusable: it commits nothing a keyboard cannot already reach, and announcing it would offer a reader a control that does nothing when they press it.
+- invalid and aria-invalid are read together, so a form library setting either one paints the same border.
+
+## Keyboard
+
+- ↑ / ↓ — Steps by one step, honouring min and max.
+- Enter — Reconciles what has been typed with the range and the step.
+- Escape — Abandons the edit and restores the last settled value.
+
+## NumberField
+
+A number, typed or swept to. `Input` with `type="number"` is a box that happens to reject letters. This is the control for a number that has a RANGE and a sensible increment: the arrows step it, the grip sweeps it, and `min`, `max` and `step` are honoured on the way out rather than merely announced. Reach for `Slider` instead when the position along the range is the information — a volume, a confidence, anything a reader judges by where the thumb sits. Reach for this when the digits are. A slider that also has to be exact is a `Slider` with `editable`, not one of these beside it. **Clamping happens when the field is left, not while it is being typed.** A minimum of 10 would otherwise make 50 unreachable: the `5` is clamped up to 10 before the `0` arrives. So `onValueChange` can report a number outside the range mid-keystroke, and the value that settles is always inside it. The native spinner buttons are hidden — they are three different controls in three browsers, and none of them is this system's. The grip replaces them for a pointer; the arrow keys were always the keyboard's answer.
+
+### Props
+
+- `value` — `number`.
+- `defaultValue` — `number`.
+- `onValueChange` — `(value: number) => void`. Fires with the parsed number. Raw `onChange` still fires with the event.
+- `min` — `number` default `Number.NEGATIVE_INFINITY`.
+- `max` — `number` default `Number.POSITIVE_INFINITY`.
+- `step` — `number` default `1`. The increment for the arrows and for one notch of a scrub.
+- `unit` — `string`. A unit drawn inside the end of the field — `%`, `px`, `ms`. The field reserves a fixed slot for it, so keep it to about four characters; a longer one runs under a long number. It is announced through `aria-describedby` as well as drawn, because a unit nobody hears turns "300" into a number with no dimension.
+- `scrub` — `boolean` default `true`. A grip at the start of the field that changes the value as it is dragged. On by default, and the reason to reach for this over `<Input type="number">`: a value that is being TUNED — a duration, a weight, an offset — is found by sweeping through neighbouring values, not by typing candidates one at a time. Shift multiplies the travel by ten. Pointer only, and `aria-hidden` for that reason: the same journey on a keyboard is the arrow keys on the field itself, which the platform already provides. Turn it off where the number is a quantity rather than a setting — a line item's quantity is chosen, not swept to.
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `ref` — `Ref<HTMLInputElement>`.
+
+Also accepts: `Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'min' | 'max' | 'step' | 'type'>`.
+
+## Examples
+
+```tsx
+<Field label="Line height"><NumberField defaultValue={1.5} min={1} max={3} step={0.1} /></Field>
+<Field label="Timeout"><NumberField defaultValue={30} min={0} max={600} unit="s" /></Field>
+```

package/dist/agent/PageHeader.md

@@ -0,0 +1,69 @@
+# PageHeader
+
+A page opening: what this page is, and what qualifies it.
+
+- Kind: component
+- Group: Surfaces
+- Import: `import { PageHeader } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/page-header/
+- Related: heading, breadcrumb, app-shell
+
+## When to reach for it
+
+The top of a route’s own column. AppShell is the frame AROUND a page; this is the first thing inside one.
+
+## Anatomy
+
+- **Header** (required) — A <header>, and therefore the page’s banner landmark. A column with a hairline under it and 24px of clearance below the rule — no top padding, so the shell decides where the page starts.
+- **Trail** — breadcrumb, above everything, as a rendered Breadcrumb rather than its items — the crumbs stay the caller’s to wire to a router. Left off inside a frame that already pins one.
+- **Eyebrow** — eyebrow in the mono kicker at --ink-3-aa, above the title and never below it. A page numeral, or the section the page belongs to.
+- **Title** (required) — title through Heading at --fs-heading, as an h1 unless level says otherwise. The size never follows the level: a page opening stands over a working screen rather than over a document whose subject is its own title, at every step of the outline.
+- **Actions** — actions, on the title’s baseline at the inline end. Controls that say which slice the title refers to — a range picker, a scope switch — not controls that act on the records.
+- **Description** — description under the title, capped at --measure-record so it stays a readable measure while the row above it runs the full width.
+
+## Best practices
+
+### Do
+
+- Put the range picker here rather than above the table. It qualifies the title — it says which slice of the archive the page is about — and below the rule it becomes a toolbar arguing with whatever strip the page starts with.
+- Leave breadcrumb off inside a shell that already pins a trail. Two trails on one screen are two answers to “where am I”, and a reader checks both.
+
+### Don’t
+
+- Do not render two openings on one page at level 1. Each is an h1, so the second is a second document as far as heading navigation is concerned; a preview or a template inside a page that has its own h1 is what level is for.
+- Do not put a second finding in description. One sentence saying what the page is for; a number that changes belongs under the rule, beside the figures it is comparable with.
+
+## Accessibility
+
+- The title is an h1 by default, so the page has a name in the heading list whatever the shell around it is doing, and level moves it where the opening is not the document’s.
+- The <header> is the page’s banner landmark, which is what a landmark-based reader jumps to first.
+
+## PageHeader
+
+A page opening: what this page is, and what qualifies it. The system has `Heading` for a heading and `Breadcrumb` for a trail, and nothing that said how a page STARTS — so every application invented the arrangement, and the eyebrow landed above the title on one screen and below it on the next. This fixes the order, the rule under it, and where the controls sit. Distinct from `AppShell`, which is the frame around a page rather than the top of one: a shell holds the rail and the bar for every route, and this is the first thing inside the route's own column. The title renders as an `h1` unless `level` says otherwise, and it is worth saying why the default is the whole answer nearly always: a page has one name, and a shell that owns the document's heading has taken the page's own name away from it. A second opening on one screen is two pages. The SIZE is not a prop at all. `Heading` at level 1 defaults to `--fs-title`, which is the editorial step for a document whose subject IS its title; a page opening stands over a working screen, where the title is the label for what follows and the records under it are what the reader came for. `--fs-heading` is that step at every level, and `Heading` is what draws it, so the ladder stays one ladder and moving an opening down the outline never resizes it.
+
+### Props
+
+- `title` (required) — `ReactNode`. What this page is. One line, and the only thing at this weight.
+- `eyebrow` — `ReactNode`. The kicker above the title. A wayfinding aid rather than decoration: in a console whose pages are referred to by a numeral, this is that numeral, and elsewhere it is the section the page belongs to.
+- `description` — `ReactNode`. One sentence saying what the page is for. Never a second finding.
+- `breadcrumb` — `ReactNode`. The trail above the opening, for a shell that does not already pin one. A page rendered inside an application frame usually leaves this off — two trails on one screen are two answers to "where am I". Takes the rendered `Breadcrumb` rather than its items, so the crumbs stay the caller's to wire to a router.
+- `actions` — `ReactNode`. Controls that qualify what the page IS, set inside the opening rather than above the content. The distinction is worth holding: a range picker does not act on the records, it says which slice of them the title refers to. Below the rule it becomes a toolbar competing with whatever strip follows; beside the title it reads as part of the heading, which is what it is.
+- `level` — `HeadingLevel` default `1`. The heading level `title` opens, in the document the opening lands in. Defaults to `1`, which is what a page opening IS: a page has one name, and a shell that owns the document's heading has taken the page's own name away from it. Move it only where the opening is not the document's — a preview canvas, a template shown inside a documentation page, a composition embedded under a host's own `h1`. The size does not follow the level. `title` renders at `--fs-heading` at every level, because moving an opening down the outline is a fact about the document and not a request for smaller type.
+- `className` — `string`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.
+
+## Examples
+
+```tsx
+<PageHeader eyebrow="04" title="Money" description="Balances and flows." />
+<PageHeader
+  title="Jobs"
+  breadcrumb={<Breadcrumb items={crumbs} />}
+  actions={<Button size="sm">Run now</Button>}
+/>
+// Inside a page that already has its own h1 — a preview, a template.
+<PageHeader level={2} title="Money" />
+```

package/dist/agent/Pagination.md

@@ -0,0 +1,70 @@
+# Pagination
+
+Numbered pages, with the middle elided.
+
+- Kind: component
+- Group: Navigation
+- Import: `import { Pagination } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/pagination/
+- Related: breadcrumb
+
+## Anatomy
+
+- **Nav** (required) — A <nav> named by label, “Pagination” by default. Nothing else here is a landmark, so this is how a reader jumps to the pager rather than scrolling to it.
+- **Step buttons** (required) — Previous and Next, pill-cornered at --control-h-sm, named by previousLabel and nextLabel — “Previous page” and “Next page” until a call site says otherwise. Each is disabled at its end of the range, which takes it out of the tab order rather than leaving a control that does nothing.
+- **Page list** (required) — An <ol> of numbers, each a <button> named by pageLabel — “Page N” by default — and carrying aria-current on the one you are on.
+- **Travelling pill** — One aria-hidden fill, measured from the selected button and moved with a transform rather than two grounds cross-fading. It is absent until the first measurement lands, and holds still under prefers-reduced-motion.
+- **Ellipsis** — An aria-hidden <li> wherever the sequence skips more than one page. A single skipped page is printed instead — “1 … 3” is longer than “1 2 3” and says less.
+
+## Best practices
+
+### Do
+
+- Move page in the same state update that fetches: it is fully controlled, so a handler that loads the next page without setting page leaves the pager marking the page the reader just left.
+- Raise siblings rather than lowering it — below 2 × siblings + 5 pages every page is printed anyway, so the prop does nothing on a short list and is the only lever you have on a long one.
+- Import paginationRange when something else has to agree with the pager: it is exported and pure, which is how a server-rendered summary and this component end up describing one window instead of two.
+- Let the surrounding row collapse: the component returns null at one page or fewer, so a footer built to a fixed height shows an empty strip on the day the list gets short.
+
+### Don’t
+
+- Do not put it in a compact region and call it a touch target: the pills are --control-h-sm, 36px comfortable and 30px under data-density="compact", set 4px apart — well under the 44px WCAG 2.5.5 asks of a pointer target.
+- Do not expect pageLabel to change what is printed. It names the control for a screen reader and nothing else; the button still shows the Western digit it was handed, so a locale that writes its numerals differently has to format them at the call site as well.
+
+## 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.
+- Every string a reader hears is a prop: the two chevrons by name, each numbered page through pageLabel — a function rather than a template, because “Page 3” is a phrase whose parts move around between languages.
+
+## 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. Every string a reader hears is a prop. The chevrons carry no text, so `previousLabel` and `nextLabel` are the whole of those two controls' names, and `pageLabel` is a function because "Page 3" is a phrase whose parts move around between languages.
+
+### 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'`.
+- `previousLabel` — `string` default `'Previous page'`. Names the two step controls. Each is a chevron and nothing else, so these strings are its entire accessible name — the same reason `AppShell` exposes `openLabel` and `closeLabel` rather than baking them in.
+- `nextLabel` — `string` default `'Next page'`.
+- `pageLabel` — `(page: number) => string` default `(page) => `Page ${page}``. Names one numbered page. A function rather than a template, because the number does not sit in the same place in every language and neither does the noun around it — `"Page 3"`, `"第 3 页"`, `"Seite 3"`. The visible digit is the same either way; this is what a screen reader hears instead of a bare number.
+
+Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'onChange'>`.
+
+## Examples
+
+```tsx
+<Pagination page={page} pageCount={12} onPageChange={setPage} />
+```

package/dist/agent/PieChart.md

@@ -0,0 +1,80 @@
+# PieChart
+
+Parts of one whole.
+
+- Kind: component
+- Group: Charts
+- Import: `import { PieChart } from '@misoto22/folio/charts'`
+- Version: 0.17.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.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero rows. There are no axes here, so without one a pie at zero rows was a name over a blank box with the hidden table returning null — the picture and its text equivalent silent together. empty={false} restores that, for a chart whose emptiness is the reading.
+- **Wedges** (required) — <PieChart.Pie>. Each sector is painted from a diagonal gradient keyed on the row’s nameKey value, so config keys must match those values exactly — a row whose name is absent from config points at a gradient that was never defined and comes out unpainted.
+- **Legend** — <PieChart.Legend>, under the pie and centred by default. A pie has no category axis naming its sectors, so this is where the names live.
+- **Wedge labels** — <PieChart.Label>, a LabelList reversed out in --chart-surface. Its dataKey defaults to the pie’s VALUE key, so composing it prints the numbers.
+- **Tooltip** — <PieChart.Tooltip>, with the heading suppressed: the wedge’s own name is the row label, so a heading would print it twice.
+
+## Best practices
+
+### Do
+
+- Keep it under about five wedges. Past that the reader is ranking angles, which is the comparison a pie is worst at — a BarChart puts the same shares on a length scale and the ranking falls out of the picture for free.
+- Compose <PieChart.Label> whenever the exact share matters. It defaults to the value key, and a printed number removes the angle estimate entirely, which is this form’s only real weakness and its cheapest fix.
+- Give it an innerRadius. A donut is read by arc LENGTH rather than by wedge area, which the eye does better, and the hole is somewhere to put the total.
+
+### Don’t
+
+- A negative value has no wedge. Parts of one whole cannot include a negative part, so a breakdown carrying a refund or churn against expansion is a WaterfallChart, which is built for signed contributions.
+- Two pies side by side is not a comparison. Reading a wedge across two circles is harder than reading two wedges inside one, and the reader will try anyway — put the two periods in one grouped BarChart.
+- Pass a POSITIVE paddingAngle if the chart has to survive forced colours. There is one fill variant here, so all eight --series-* tokens collapse to CanvasText and every wedge is the same solid shape; what separates them is geometry, and a gap of a degree or two is it. The stroke is not the mechanism — it is drawn only when paddingAngle is NEGATIVE, where the wedges overlap and the surface-coloured stroke re-separates them into stacked cards. 0 is the one value with neither, and a default pie in forced colours is one uniform disc with the legend and the labels carrying the whole reading.
+
+## 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, when the chart keeps its own selection.
+- `selectedSector` — `string | null`. The selected sector, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedSector`.
+- `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.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `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>
+```

package/dist/agent/Popover.md

@@ -0,0 +1,80 @@
+# Popover
+
+A panel anchored to a control, holding content you can interact with.
+
+- Kind: component
+- Group: Overlays
+- Import: `import { Popover } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/popover/
+- Related: tooltip, dropdown-menu
+
+## When to reach for it
+
+Anything with a link, a field or a button in it. A tooltip describes and cannot be entered — put a control inside one and it becomes unreachable.
+
+## Anatomy
+
+- **Trigger** (required) — PopoverTrigger, a passthrough. Pass asChild to keep your own control; Radix returns focus here when the panel closes on Escape.
+- **Panel** (required) — The anchored dialog: a flat 18rem wide with 1rem of padding, 8px off the trigger, named by label. Focus moves into it on open, but it is not trapped there.
+- **Anchor** — PopoverAnchor, for when the panel should be positioned against something other than the control that opened it — the row an overflow button acts on, a selection in text.
+- **Close** — PopoverClose, and the 32px X that showClose renders in the top-end corner. Off by default, unlike Dialog’s.
+
+## Best practices
+
+### Do
+
+- Make label say what the panel holds rather than echoing the trigger: it is announced on entry, so “Filter options” tells a reader where they have landed where a repeat of the button text tells them nothing new.
+- Use PopoverAnchor when the visual anchor is not the trigger — a toolbar button acting on a selected row — otherwise the panel tracks the button and drifts away from the thing it is editing.
+- Wrap the dismissing control in PopoverClose rather than flipping your own state, so the close runs through Radix and focus goes back to the trigger instead of to the top of the document.
+- Turn showClose on when the panel holds a form. It is off by default, and a non-modal panel whose only exit is clicking away gives an in-progress edit no deliberate end.
+
+### Don’t
+
+- It is not modal — Radix defaults modal to false and nothing here changes that, so there is no focus trap and no scroll lock: tabbing past the last control inside moves focus into the page, which Radix reads as a focus-outside and closes the panel mid-task.
+- A list of actions belongs in a DropdownMenu. A popover’s contents are ordinary tab stops, so ten actions is ten stops with no type-ahead, where a menu is one stop with arrow keys and a letter jump inside it.
+- The panel sits at --z-dropdown, which resolves to 220 — above a Dialog’s 210, so that a popover opened FROM a dialog is reachable. A popover the page opened and your own state holds open therefore paints over a modal that arrives afterwards; Radix closes it on the interaction outside, and a controlled open that ignores that is the one way to see it.
+
+## Accessibility
+
+- Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.
+- label is required: a popover is a dialog, and an unnamed one announces nothing.
+- Its contents Tab like the rest of the page, unlike a menu’s arrow-key list.
+
+## Keyboard
+
+- Enter / Space — Opens it.
+- Tab — Moves through its contents like the rest of the page.
+- Escape — Closes it and returns focus to the trigger.
+
+## Popover
+
+Radix Popover root, trigger, anchor and close, as typed passthroughs.
+
+## PopoverTrigger
+
+## PopoverAnchor
+
+## PopoverClose
+
+## PopoverContent
+
+A panel anchored to a control, holding content the reader can interact with. The line against `Tooltip` is not visual, it is behavioural: a tooltip describes and cannot be entered; a popover holds things you tab to. Anything with a link, a field or a button in it is a popover, and putting that inside a tooltip makes it unreachable — the tooltip closes as soon as focus tries to move into it. Against `DropdownMenu`: a menu is a list of actions with menu semantics and arrow-key navigation. A popover is free-form, and its contents Tab like the rest of the page.
+
+### Props
+
+- `label` (required) — `string`. Names the panel for assistive tech. Required — a popover is a dialog.
+- `showClose` — `boolean` default `false`. Show the top-end close control.
+
+Also accepts: `ComponentProps<typeof PopoverPrimitive.Content>`.
+
+## Examples
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild><Button variant="secondary">Filters</Button></PopoverTrigger>
+  <PopoverContent label="Filters">
+    <Field label="Status"><Select>…</Select></Field>
+  </PopoverContent>
+</Popover>
+```

package/dist/agent/Portfolio.md

@@ -0,0 +1,93 @@
+# Portfolio
+
+An editorial introduction, featured images, records and a question card.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { Portfolio } from '@misoto22/folio/website'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/portfolio/
+
+## When to reach for it
+
+Build a personal or studio index from supplied text, images and actions.
+
+## 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.
+
+## Portfolio
+
+An introduction and a chosen photograph, with content supplied by the host.
+
+### Props
+
+- `name` (required) — `string`.
+- `monogram` — `string`.
+- `biography` (required) — `ReactNode`.
+- `facts` — `ReactNode[]` default `[]`.
+- `quotation` — `ReactNode`.
+- `feature` — `ReactNode`.
+
+## PortfolioImage
+
+### Props
+
+- `children` (required) — `ReactElement`.
+- `title` — `ReactNode`.
+- `metadata` — `ReactNode`.
+- `index` — `string`.
+- `size` — `'feature' | 'tile' | 'thumbnail'` default `'tile'`.
+- `natural` — `boolean` default `false`. Preserve the supplied image's intrinsic dimensions instead of cropping.
+
+## PortfolioRecord
+
+### Props
+
+- `title` (required) — `ReactNode`.
+- `description` — `ReactNode`.
+- `context` — `ReactNode`.
+- `image` — `ReactNode`.
+- `action` — `ReactNode`.
+- `metadata` — `ReactNode`.
+
+## PortfolioList
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `variant` — `'records' | 'frames' | 'thumbnails'` default `'records'`.
+- `label` — `string`.
+
+## PortfolioCategories
+
+### Props
+
+- `label` (required) — `string`.
+- `items` (required) — `{ id: string; label: ReactNode; count: number }[]`.
+
+## QuestionCard
+
+A compact invitation to an application-owned conversation.
+
+### Props
+
+- `title` (required) — `ReactNode`.
+- `description` (required) — `string`.
+- `label` (required) — `string`.
+- `placeholder` (required) — `string`.
+- `value` (required) — `string`.
+- `onChange` (required) — `(value: string) => void`.
+- `onSubmit` (required) — `(value: string) => void`.
+- `submitLabel` (required) — `string`.
+- `examplesLabel` (required) — `string`.
+- `examples` (required) — `string[]`.
+- `disabled` — `boolean`.
+- `maxLength` — `number`.
+- `inputId` — `string`.

package/dist/agent/PortfolioIndex.md

@@ -0,0 +1,34 @@
+# PortfolioIndex
+
+Tabbed collections with a supporting editorial column.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { PortfolioIndex } from '@misoto22/folio/website'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/portfolio-index/
+
+## When to reach for it
+
+Group related collections under a named tab strip with keyboard selection.
+
+## 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.
+
+## PortfolioIndex
+
+A portfolio index whose categories and context follow the selected tab.
+
+### Props
+
+- `label` (required) — `string`.
+- `items` (required) — `PortfolioIndexItem[]`.
+- `aside` — `ReactNode`.
+- `defaultValue` — `string`.

package/dist/agent/Progress.md

@@ -0,0 +1,58 @@
+# Progress
+
+A bar that fills, or sweeps when the end is unknown.
+
+- Kind: component
+- Group: Feedback
+- Import: `import { Progress } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/progress/
+- Related: spinner
+
+## Anatomy
+
+- **Track** (required) — The Radix root: 4px of --stone at the pill radius, carrying role="progressbar" and aria-label from label. It is full width by default, so it takes the measure of whatever column it is dropped into.
+- **Fill** — The indicator, in --accent, sized by width rather than a translate so it grows from the inline start in a right-to-left document too. Present only when value is a number.
+- **Sweep** — What replaces the fill when value is null: a quarter-width --accent bar travelling the track on transform alone, mirrored under rtl so it never reads as progress running backwards. Under prefers-reduced-motion it stops where it is drawn rather than filling the track.
+- **Value row** — label on the left, a tabular-nums percentage on the right, above the track. It renders only when showValue is set and value is a number, which makes it the only place label is ever visible.
+- **Column** — The flex wrapper holding the row and the track. className lands here; every other prop is forwarded to the Radix root instead.
+
+## Best practices
+
+### Do
+
+- Pass showValue on any determinate bar. It is the only thing that puts label on screen — without it the name exists solely as aria-label, and a sighted reader is left with an unlabelled 4px rule and no number.
+- Switch value back to null the moment the estimate stops being real. The fill transitions its width over --duration-slow, so a number that revises downward animates backwards and the reader watches progress undo itself.
+- Set max to the real total rather than converting to a percentage yourself. The width and aria-valuemax come off the same number, so the picture and the announcement cannot drift — but a value past the ceiling still clamps, and an underestimated total parks the bar at full for the rest of the operation rather than admitting the estimate was wrong.
+
+### Don’t
+
+- Do not pass a max that is not a positive number. Radix refuses it, prints its own warning and falls back to 100, and the width falls back with it — so value={40} paints and announces forty per cent of a ceiling nobody chose.
+- Do not read the resting sweep as a position. Under prefers-reduced-motion it stops at a quarter of the track, which is what a determinate bar at 25% looks like — the announcement is the only thing that tells the two apart, and it is the reason omitting value matters.
+- className styles the column, not the track, so a height utility passed that way stretches the wrapper and leaves the 4px bar exactly where it was.
+
+## Accessibility
+
+- Omitting value drops aria-valuenow, so a screen reader hears “indeterminate” rather than a number that is a guess.
+- label is required — a bare bar announces nothing.
+- The width is computed from value and max, the same pair Radix announces as aria-valuenow and aria-valuemax, so what is drawn and what is said cannot disagree.
+
+## Progress
+
+A bar that fills, or sweeps when the end is unknown. Flat: a track in `--stone`, a fill in `--ink`. The White Reset has no gradient and no glow, so the only thing carrying the reading is the boundary between the two.
+
+### Props
+
+- `value` — `number | null` default `null`. 0 to `max`, which is 100 unless you say otherwise. Omit (or pass `null`) when the duration is genuinely unknown — the bar then sweeps instead of filling, and Radix drops `aria-valuenow` so a screen reader is told "indeterminate" rather than a number that is a guess.
+- `max` — `number`. What `value` is measured against. 100 by default. The width is computed from it as well as announced from it. It used to be only announced: `max` reached Radix through `...rest` while the width was `value` clamped to 100, so `max={500}` with `value={100}` painted a full bar and told a screen reader "100 of 500". A max that is not a positive number is refused the way Radix refuses it — Radix warns, and both fall back to 100 rather than drawing one picture and announcing another.
+- `label` (required) — `string`. Names what is progressing. Required: a bare bar announces nothing.
+- `showValue` — `boolean` default `false`. Prints the percentage above the bar. Only meaningful when `value` is set.
+
+Also accepts: `Omit<ComponentProps<typeof ProgressPrimitive.Root>, 'value' | 'max'>`.
+
+## Examples
+
+```tsx
+<Progress value={62} label="Uploading photos" showValue />
+<Progress label="Indexing" />
+```