@misoto22/folio 0.0.0 → 0.17.0

package/dist/agent/ColorPicker.md

@@ -0,0 +1,76 @@
+# ColorPicker
+
+A colour, chosen or typed.
+
+- Kind: component
+- Group: Forms
+- Import: `import { ColorPicker } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/color-picker/
+- Related: field, input, popover
+
+## When to reach for it
+
+A person is choosing the colour. A colour that is merely being SHOWN is a swatch, and a set of fixed brand colours is a RadioGroup — a picker offers sixteen million answers to a question with six.
+
+## Anatomy
+
+- **Trigger** (required) — The closed control: a swatch, then the value as text, in the same box as Input and Select. Named by its label AND by its own value, so a reader hears “Brand colour, #a78bfa” rather than either half.
+- **Swatch** — The colour over a checkerboard, so a half-transparent value reads as transparent rather than as a paler colour.
+- **Notation strip** — Hex, OKLCH and Display P3, as a single-value ToggleGroup. It changes what onValueChange emits, not what the colour is — and hex and P3 are bounded, so switching to one of them fits the colour to that gamut on the way out.
+- **Field** (required) — The plane: chroma across, lightness up. Each ROW is normalised to the most chroma that exists at that lightness and hue, so the whole surface is reachable instead of a lens of colour inside bands of clipped duplicates. Underneath it are two real sliders rather than key handlers on a canvas, which is what gives it arrows, Home, End and an announced position.
+- **Hue track** — A ramp taken at the lightness and chroma already chosen, not a generic rainbow — so the strip shows the hues of THIS colour rather than of some other one.
+- **Opacity track** — Transparent to the current colour, over the same checkerboard as the swatch.
+- **CSS box** — The value as text. Accepts hex, rgb(), hsl(), oklch() and color(display-p3 …) in both syntaxes, and paints itself invalid on anything else.
+
+## Best practices
+
+### Do
+
+- Wrap it in a Field. The trigger is a button, which a label binds to and clicks through — one of the few composites where that works without help.
+- Pass the notation you want back. The panel emits in whatever notation the value arrived in until somebody changes it in the strip, so a defaultValue of "#a78bfa" keeps a consumer in hex.
+- Reach for this over <input type="color"> when the colours are being TUNED. The native picker works in HSV, where a row of constant lightness visibly darkens as it saturates — so a reader building a palette is fighting the instrument. OKLCH is the space where two colours at the same height genuinely match.
+
+### Don’t
+
+- Do not pass a named colour. Hex, rgb(), hsl(), oklch() and color(display-p3 …) parse; "rebeccapurple" does not, and the box will show it as invalid. Resolving names needs a table of every CSS keyword or a live DOM, and a picker that takes some names and not others is worse than one that takes none.
+- Do not read the emitted string as a fixed notation. It is whatever the strip is set to, so a consumer that slices a "#" off the front breaks the first time a reader picks OKLCH.
+- Do not use it to pick text or background colour and call the result accessible. Nothing here measures contrast; a picker that lets a reader choose #eeeeee for body copy is doing exactly what it was asked.
+
+## Accessibility
+
+- label is required. The trigger shows a value, and a value is not a name.
+- The plane is a group of two real sliders — Chroma and Lightness — each announced with a percentage, so the 2D surface is operable and reported rather than merely clickable.
+- The focus ring is drawn on the plane, because the sliders that take the focus are visually hidden and the browser’s own ring is clipped away with them.
+- Alpha is doubled by a checkerboard everywhere it is shown, so transparency is not carried by lightness alone.
+
+## Keyboard
+
+- Enter / Space — Opens the panel.
+- ← / → — Moves the focused axis or track by one step.
+- Home / End — Jumps that axis or track to its ends.
+- Escape — Closes the panel; focus returns to the trigger.
+
+## ColorPicker
+
+A colour, chosen or typed. The panel works in OKLCH, and that is the reason to reach for this rather than `<input type="color">`. In HSV — which is what the native picker and most libraries use — dragging along a row of constant "lightness" walks through colours the eye reads as getting darker, so a reader tuning a palette is fighting the instrument. OKLCH's lightness is the one a person sees, so two colours at the same height on the plane genuinely match, and the hue strip stays at the lightness already chosen instead of showing a rainbow that belongs to some other colour. The plane is normalised to the gamut ROW BY ROW: its right edge is the most chroma that exists at that lightness and hue, so the whole surface is reachable rather than a lens of colour inside a field of clipped duplicates. **What it accepts.** Hex, `rgb()`, `hsl()`, `oklch()` and `color(display-p3 …)`, in both syntaxes. Named colours are not accepted: resolving them needs a table of every CSS name or a live DOM, and a box that takes "rebeccapurple" but not "papayawhip" is worse than one that takes neither. **Keyboard.** The plane is a group of two real sliders — chroma across, lightness up — so the arrows move it and a screen reader announces where it is. That is the part a 2D canvas usually leaves out, and leaving it out makes the control unusable rather than merely awkward.
+
+### Props
+
+- `label` (required) — `string`. Names the control. Required — the trigger shows a colour, and a colour is not a name. Announced together with the value, the way `Select`'s is: a reader hears "Brand colour, #a78bfa". Inside a `Field` with a label, that label is used and this one is not repeated.
+- `value` — `string`. The colour, as any absolute CSS colour string.
+- `defaultValue` — `string` default `'#000000'`.
+- `onValueChange` — `(value: string) => void`. Fires with a CSS colour string in whichever notation the panel is set to — so the notation a caller passes in is the notation they get back until somebody changes it in the panel.
+- `disabled` — `boolean`.
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `className` — `string`.
+- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
+- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
+- `aria-invalid` — `boolean | 'true' | 'false'`. The spelling a form library sets; read together with `invalid`.
+- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.
+
+## Examples
+
+```tsx
+<Field label="Brand colour"><ColorPicker label="Brand colour" defaultValue="#a78bfa" /></Field>
+```

package/dist/agent/Combobox.md

@@ -0,0 +1,77 @@
+# Combobox
+
+A select you can type into.
+
+- Kind: component
+- Group: Forms
+- Import: `import { Combobox } from '@misoto22/folio'`
+- Version: 0.17.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.
+
+## Anatomy
+
+- **Trigger** (required) — A <button role="combobox"> named by the label and its own summary together, carrying aria-expanded. Its text truncates rather than wrapping, so the field keeps its height whatever is chosen.
+- **Summary** — The trigger’s text: the placeholder, or up to two chosen labels joined by commas, then “n selected”. Counting past two is what stops a multiple picker reflowing the form on every choice.
+- **Clear** — A <span role="button"> beside the chevron, on multiple with something chosen. A span rather than a nested <button>, which is invalid inside the trigger and which browsers reparent out of the field.
+- **Filter field** — cmdk’s input inside the panel. It is named through the Command wrapper as “label: searchPlaceholder”, because aria-labelledby beats aria-label and naming the input directly did nothing.
+- **Option row** — A tick for single, a fillable box for multiple, then the label. emptyMessage takes the list’s place when the filter matches nothing.
+
+## Best practices
+
+### Do
+
+- Spell “nothing chosen” as an empty string when the value is controlled. value={undefined} is precisely how this component decides it is UNCONTROLLED, so clearing that way hands it back its own state and it stops following the parent.
+- Put readable text in label and anything else worth matching in keywords: cmdk scores against the option’s value too, so a list keyed by UUID is being ranked on a string no reader will ever type.
+- Say what WOULD match in emptyMessage. The default tells a reader the filter ran and nothing about which of the four hundred options they should have typed instead.
+
+### Don’t
+
+- Past two choices the trigger stops naming them — it announces “Tags, 3 selected”, and WHICH three is only in the panel. Print them beside the field when the choice has to be checkable without opening it.
+- Do not hand it thousands of options. Nothing here virtualises: every option in the array renders into the panel on open and stays there behind the filter, so the list length is a DOM cost, not a search cost.
+- A disabled option is not a hidden one — it still renders and still matches the filter, so a reader can type its exact name, watch it come up, and be unable to pick it with no reason offered.
+
+## 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, and it is announced with the summary rather than instead of it: the trigger reads “Tags, 3 selected”. Inside a Field the FIELD’s label supplies the name half and the label prop is neither rendered nor announced on the trigger — it still names the clear control, as “Clear Tags”, so it has to stay truthful even where the trigger no longer says it.
+
+## 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. Announced together with the summary rather than instead of it, so a reader hears "Tags, 3 selected". Inside a `Field` with a label, that label names the trigger and this one is not repeated.
+- `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`.
+- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
+- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
+- `aria-invalid` — `boolean | 'true' | 'false'`. Paints the resting border with `--danger` and is announced. A `Field` sets it from `error`.
+- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.
+
+## Examples
+
+```tsx
+<Combobox label="Framework" options={FRAMEWORKS} placeholder="Pick one" />
+<Combobox multiple label="Tags" options={TAGS} />
+```

package/dist/agent/Command.md

@@ -0,0 +1,122 @@
+# Command
+
+A filterable list of actions — the ⌘K surface.
+
+- Kind: component
+- Group: Overlays
+- Import: `import { Command } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/command/
+- Related: combobox, dialog
+
+## Anatomy
+
+- **Input** (required) — CommandInput, the combobox, with the search glyph and a hairline under it. A hard 52px tall rather than a --control-h token, so it does not move with data-density.
+- **List** (required) — CommandList, capped at 18rem inline and raised to 26rem inside CommandDialog, scrolling on its own six-pixel hairline bar.
+- **Item** — A row: an icon ELEMENT, the label, an optional meta note and a shortcut printed as a Kbd. The highlighted row takes --accent-muted and a leading accent rule, because a fill alone is hard to catch while scrolling.
+- **Empty** — CommandEmpty. cmdk renders an empty state only if one exists in the tree, so without it an unmatched filter leaves the input over a blank strip.
+- **Footer** — CommandFooter and its CommandHint rows. A palette is a keyboard surface whose keys are invisible; this is the only place they get printed.
+
+## Best practices
+
+### Do
+
+- Reach for CommandDialog, not the bare Command. The root is an inline bordered box with no scrim, no focus trap and no Escape handling of its own, so a palette built from it alone stays open until something else closes it.
+- Always render CommandEmpty. cmdk shows an empty state only when one is present, so the palette that omits it answers a filter matching nothing with an input above a blank strip and no explanation.
+- Pass CommandItem an icon element — icon={<Search size={16} />} — when the glyph needs its own size or colour, and the component — icon={Search} — when it does not. Both spellings work here and in DropdownMenuItem; they used to be the reverse of each other one import apart.
+- Bind ⌘K yourself and then print it: nothing in this component listens for a key, so the palette has no shortcut until the app adds a keydown handler, and a CommandFooter is where the reader finds out it exists.
+
+### Don’t
+
+- Do not pass value to CommandItem unless the value is what a reader would type — cmdk filters on value first and only falls back to the row’s own text when there is none, so an id passed as the value makes the visible label unsearchable. Pass the label’s words as keywords when the id has to stay the value, which is what SearchableMenu does.
+- CommandDialog renders with hideTitle and showClose={false}, so the palette has no visible heading and no visible close: Escape and the scrim are the only exits and neither announces itself. Print Escape in a CommandFooter rather than assuming it is known.
+- Do not expect the palette to follow data-density — CommandInput is a hard 52px, not a --control-h token, so its field stays put while every other control in the app shrinks under compact.
+
+## Accessibility
+
+- The list filters as you type, the highlight moves with the arrow keys, and focus stays in the input. That last part is the ARIA combobox pattern and the part a home-made palette gets wrong.
+
+## Keyboard
+
+- ↑ / ↓ — Moves the highlight. Focus stays in the input, so what you typed stays editable.
+- Enter — Runs the highlighted item.
+- Escape — Closes the palette.
+
+## Command
+
+A filterable list of actions — the ⌘K surface. Built on cmdk rather than on a `Select` or a menu, because the interaction is neither: the list is filtered as you type, the highlighted row moves with the arrow keys while focus STAYS in the input, and Enter runs the highlighted row. That is the ARIA combobox pattern, and it is the part nobody should hand-roll — `aria-activedescendant` moving without focus moving is precisely where a home-made palette stops working with a screen reader.
+
+## CommandInput
+
+The filter field. Carries the search icon and the combobox semantics.
+
+## CommandList
+
+## CommandEmpty
+
+Shown when the filter matches nothing. Say what would match, not "no results".
+
+## CommandFooter
+
+The key-hint strip along the bottom. A palette is a keyboard surface whose keys are invisible: nothing on screen says the arrows move the row or that Enter runs it, and a reader who reaches for the mouse has been failed by the design rather than by themselves.
+
+## CommandHint
+
+One key-and-verb pair inside a `CommandFooter`.
+
+### Props
+
+- `keys` (required) — `string[]`. The keys this hint describes, printed as `Kbd` chips.
+- `children` (required) — `ReactNode`. What they do — a verb, lowercase, no sentence.
+
+Also accepts: `Omit<ComponentProps<'span'>, 'children'>`.
+
+## CommandGroup
+
+## CommandSeparator
+
+A divider between groups. Marked presentational, because ARIA permits a `listbox` to contain only `option` and `group` — and the library renders this as `role="separator"`, which puts a critical `aria-required-children` violation inside every palette that uses one. The grouping is already announced by the groups themselves, so removing the divider from the accessibility tree loses nothing.
+
+## CommandItem
+
+### Props
+
+- `shortcut` — `string`. A shortcut printed at the end of the row.
+- `icon` — `RemixiconComponentType | ReactNode`. A leading glyph. Either spelling — `icon={<Settings size={16} />}` passes the element, `icon={Settings}` passes the component and this sizes it. It is what makes a long list scannable — the eye sorts by shape before it reads, and forty identical rows of text defeat that.
+- `meta` — `ReactNode`. A quiet note at the end of the row — what kind of thing this is, or its current state. Not a description: a palette that prints a sentence per row stops being scannable at about six of them.
+
+Also accepts: `ComponentProps<typeof CommandPrimitive.Item>`.
+
+## CommandDialog
+
+The palette in a modal, which is how it is nearly always used. The dialog's own padding is removed: a palette is edge-to-edge, and its input is the first thing focus lands on.
+
+### Props
+
+- `open` (required) — `boolean`.
+- `onOpenChange` (required) — `(open: boolean) => void`.
+- `label` (required) — `string`. Names the palette for assistive tech.
+- `inputLabel` — `string`. Names the search field when it should read differently from the dialog — a "Search records" field inside a "Library search" palette. Defaults to `label`. An `aria-label` on `CommandInput` cannot do this: the field is labelled by reference, and a reference outranks an `aria-label`.
+- `children` (required) — `ReactNode`.
+- `shouldFilter` — `boolean`. Pass `false` when the host has already filtered the rows — a server search or an index of its own. The palette would otherwise filter them a second time against the input and hide results the host meant to show.
+- `onOpenAutoFocus` — `DialogContentProps['onOpenAutoFocus']`. Runs as the dialog moves focus in. Prevent the default to place focus yourself.
+- `onCloseAutoFocus` — `DialogContentProps['onCloseAutoFocus']`. Runs as the dialog hands focus back on close. The default returns it to a `DialogTrigger`, and a palette opened by a shortcut has none, so focus falls to the page. Prevent the default and focus what opened it.
+- `onEscapeKeyDown` — `DialogContentProps['onEscapeKeyDown']`. Runs before Escape closes the dialog. Prevent the default to keep it open, as a nested view stepping back does.
+
+## Examples
+
+```tsx
+<Command label="Command palette">
+  <CommandInput placeholder="Type a command…" />
+  <CommandList>
+    <CommandEmpty>Nothing matches.</CommandEmpty>
+    <CommandGroup heading="Navigate">
+      <CommandItem onSelect={go}>Components</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+<CommandFooter>
+  <CommandHint keys={['↑', '↓']}>navigate</CommandHint>
+  <CommandHint keys={['↵']}>open</CommandHint>
+</CommandFooter>
+```

package/dist/agent/ComposedChart.md

@@ -0,0 +1,82 @@
+# ComposedChart
+
+Bars and lines over one axis — the volume, and the rate it moved at.
+
+- Kind: component
+- Group: Charts
+- Import: `import { ComposedChart } from '@misoto22/folio/charts'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/composed-chart/
+- Related: bar-chart, line-chart
+
+## When to reach for it
+
+Two measures that share a scale. Two that do NOT share one belong in two charts or indexed to a common base: there is no second y-axis here, on purpose.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, named by title, with the composed marks inside one measured ChartContainer.
+- **The single value axis** (required) — <ComposedChart.YAxis>. One of them is the entire design: there is no dual-axis affordance and no second scale to configure, so the two measures are read against the same numbers.
+- **Bars** — <ComposedChart.Bar>, the volume. Custom-shaped like BarChart’s, with the same transparent hit rectangle and the same grow-in anchored to the chart’s start rather than to each bar’s mount, so a hover cannot replay it.
+- **Lines** — <ComposedChart.Line>, the rate. It inherits the chart’s curveType and reveal, so bars and line arrive as one figure rather than as two animations on two clocks.
+- **Column highlight** — enableHoverHighlight dims every mark outside the hovered column, driven by the chart’s own onMouseMove index rather than by each mark’s hover — which is what makes a bar and a line in the same column light together.
+- **Brush and toolbar** — <ComposedChart.Brush> in the container footer and <ComposedChart.Toolbar> above the plot. They drive one window, so a brushed range and a zoomed range cannot disagree about what is on screen.
+- **Hidden data table** — The sr-only table of the FULL data rather than of the brushed window, so a reader on the table is never shown less than the CSV export holds. hideDataTable removes it, and zero rows render nothing.
+
+## Best practices
+
+### Do
+
+- Index two measures to a common base — both as a percentage of January, say — when they do not share a scale. That is the substitute for the second axis this component deliberately does not have.
+- Compose <ComposedChart.Legend> above two marks. A bar and a line at --series-1 and --series-2 differ by one step of grey and a shape, and only the shape is self-describing.
+- Set enableHoverHighlight on every mark or on none. Set on one, the hovered column dims half of itself, which reads as a rendering fault rather than as emphasis.
+
+### Don’t
+
+- Do not smuggle a second y-axis in through chartProps or a yAxisId on <ComposedChart.YAxis>. Recharts allows it; the component’s claim is that it does not. Two scales chosen independently let the author decide where the lines cross, which is the single most misleading thing a chart can do — and it always works, on any two series.
+- Do not assume the audio reading is here. AreaChart, BarChart and LineChart each carry a Sonify slot and this one does not, so a reader who has been listening across a dashboard falls back to the sr-only table — which is why hideDataTable is the prop not to set on this chart.
+
+## Accessibility
+
+- title is required; the rows are also rendered as a visually hidden table.
+- One value axis only. A dual-axis chart lets its author choose where the lines cross, which is the single most misleading thing a chart can do.
+- enableHoverHighlight dims every bar outside the hovered column, driven by the chart’s own tooltip index.
+
+## ComposedChart
+
+Bars and lines over one axis — the shape for "the volume, and the rate it moved at". One axis, always. Two measures at different scales belong in two charts or indexed to a common base; a second y-scale lets the author choose where the lines cross, which is the single most misleading thing a chart can do.
+
+### 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 RechartsComposedChart>`. Escape hatch onto the raw Recharts chart element.
+- `curveType` — `ChartCurveType` default `'linear'`. How the line between two points is interpolated. Every mark inherits it unless it says otherwise.
+- `animationType` — `ChartRevealType` default `'forward'`.
+- `barGap` — `number`.
+- `barCategoryGap` — `number`.
+- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
+- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
+- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
+- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
+- `loadingBars` — `number`. How many bars the skeleton draws.
+- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.
+
+## Examples
+
+```tsx
+<ComposedChart title="Revenue and profit" config={config} data={data}>
+  <ComposedChart.Grid />
+  <ComposedChart.XAxis dataKey="month" />
+  <ComposedChart.Tooltip />
+  <ComposedChart.Bar dataKey="revenue" variant="duotone" />
+  <ComposedChart.Line dataKey="profit" />
+</ComposedChart>
+```

package/dist/agent/Contact.md

@@ -0,0 +1,90 @@
+# Contact
+
+A correspondence form, contact facts, questions and location imagery.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { CorrespondenceSection } from '@misoto22/folio/website'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/contact/
+
+## When to reach for it
+
+Provide localized field labels and host-owned submission state to a complete form.
+
+## 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.
+
+## CorrespondenceSection
+
+A correspondence page's primary content and supporting facts.
+
+### Props
+
+- `aside` (required) — `ReactNode`.
+- `children` (required) — `ReactNode`.
+- `asidePosition` — `'start' | 'end'` default `'start'`. The secondary column can precede or follow the main content.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ContactFormView
+
+Controlled contact form. Validation, submission and delivery remain host responsibilities.
+
+### Props
+
+- `labels` (required) — `ContactFormLabels`.
+- `values` (required) — `ContactFormValues`.
+- `topics` (required) — `{ value: string; label: string }[]`.
+- `topic` (required) — `string`.
+- `onTopicChange` (required) — `(value: string) => void`.
+- `onFieldChange` (required) — `(field: keyof ContactFormValues, value: string) => void`.
+- `onSubmit` (required) — `FormEventHandler<HTMLFormElement>`.
+- `limits` (required) — `Record<keyof ContactFormValues, number>`.
+- `pending` — `boolean` default `false`.
+- `error` — `string`.
+- `success` — `{ title: string; description: string }`. A server-confirmed success. The host decides when the form can disappear.
+- `idPrefix` — `string`. Optional stable prefix for links to a specific form.
+
+## ContactFacts
+
+Contact facts retain their definition-list semantics and optional navigation.
+
+### Props
+
+- `label` (required) — `string`.
+- `items` (required) — `DescriptionListItem[]`.
+- `links` — `ReactNode`.
+- `linksLabel` — `string`.
+
+## QuestionList
+
+Visible questions and answers, useful when the complete answer set is short.
+
+### Props
+
+- `title` (required) — `string`.
+- `description` — `string`.
+- `items` (required) — `{ id: string; question: string; answer: string }[]`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## LocationFigure
+
+Static map presentation; provider URLs, credentials and theme selection stay in the host.
+
+### Props
+
+- `label` (required) — `string`.
+- `coordinates` (required) — `string`.
+- `image` — `ReactNode`.
+- `credit` — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.

package/dist/agent/Content.md

@@ -0,0 +1,70 @@
+# Content
+
+Formatted code, clipboard actions, step sequences and rich-content elements.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { StepSequence } from '@misoto22/folio/website'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/content/
+
+## When to reach for it
+
+Render supplied text and highlighted code with consistent reading and copy affordances.
+
+## 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.
+
+## StepSequence
+
+A process rail whose source order, counters and annotations belong to the host.
+
+### Props
+
+- `spec` (required) — `StepSequenceSpec`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## ContentTable
+
+Keeps a rendered article table intact inside a keyboard-scrollable region.
+
+Also accepts: `TableHTMLAttributes<HTMLTableElement>`.
+
+## ExternalLinkMark
+
+### Props
+
+- `children` — `ReactNode` default `'↗'`.
+
+## ClipboardButton
+
+Confirms copying only after the browser accepts the clipboard write.
+
+### Props
+
+- `text` — `string`.
+- `getText` — `() => string`. Read the current rendered code at activation, when the host owns highlighting.
+- `copyLabel` (required) — `string`.
+- `copiedLabel` (required) — `string`.
+- `className` — `string`.
+
+## CodePanel
+
+A rendered-code panel for Markdown and MDX, preserving the host's highlighted nodes.
+
+### Props
+
+- `languageLabel` — `ReactNode`. A display label, already mapped from the host highlighter's language id.
+- `preProps` — `HTMLAttributes<HTMLPreElement>`.
+- `framed` — `boolean` default `true`. False when the host renderer has already supplied an enclosing figure.
+- `copyLabel` (required) — `string`.
+- `copiedLabel` (required) — `string`.
+- `children` (required) — `ReactNode`.

package/dist/agent/ContextMenu.md

@@ -0,0 +1,93 @@
+# ContextMenu
+
+The menu a right-click opens.
+
+- Kind: component
+- Group: Overlays
+- Import: `import { ContextMenu } from '@misoto22/folio'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/context-menu/
+- Related: dropdown-menu
+
+## When to reach for it
+
+Never as the only way to reach an action. Touch users, trackpad users and keyboard users may have no way to open it.
+
+## Anatomy
+
+- **Trigger** (required) — The region a secondary click opens the menu over. Radix wraps children in its own inline span unless you pass asChild, and sets -webkit-touch-callout: none on it so the OS text callout does not fire first.
+- **Panel** (required) — The portalled menu, placed at the POINTER rather than against the trigger — there is no side or align to set here, only the 8px collision padding that keeps it inside the viewport or the OverlayContainer frame.
+- **Item** — A row, taking the same icon, destructive and disabled props as DropdownMenuItem — icon in either spelling — and highlighting on the same data-highlighted.
+- **Label** — A mono eyebrow, on its own, and visual only. ContextMenuGroup is the one that heads rows: it renders role="group" and points its aria-labelledby at this.
+- **Group** — A named section: role="group" around the rows, with label rendered inside it as the Label and named through aria-labelledby.
+- **Separator** — A hairline between groups, as a real role="separator".
+
+## Best practices
+
+### Do
+
+- Pass asChild and hand it the element itself: without it Radix inserts a span between you and your child, and that span becomes the flex or grid item while your card is laid out inside it as inline content.
+- Build the same array of actions into a DropdownMenu behind an overflow button — the two take identical icon, destructive and disabled props, so one list feeds both and the right-click becomes the shortcut rather than the only door.
+- Wrap the subtree in OverlayContainer when the right-clickable region lives in a scrolling or bounded frame: this is the one panel whose position the reader personally chose, and a flip against a viewport edge they cannot see lands it somewhere they did not point.
+
+### Don’t
+
+- Do not read “no touch support” as the whole story: Radix opens the menu on a 700ms long press for touch and pen, but cancels the moment the pointer moves — so on a scrollable list the long press and the scroll gesture compete and the scroll usually wins.
+- A bare ContextMenuLabel over rows is a picture of a heading: Radix’s MenuLabel is a plain div with no role and nothing tying it to what follows, so the sections a sighted reader sees arrive as one undivided list. ContextMenuGroup renders both halves and wires them together.
+- Radix defaults modal to true here too, so the page behind is scroll-locked and pointer-inert while the menu is open — a right-click menu over a long list stops the list moving under it, which is right for a short action list and wrong for anything the reader must scroll to answer.
+
+## Keyboard
+
+- Shift / F10 — Opens the menu from the keyboard, where the platform supports it.
+- ↑ / ↓ — Moves between items.
+- Escape — Closes it.
+
+## ContextMenu
+
+Radix ContextMenu root and trigger, as typed passthroughs.
+
+## ContextMenuTrigger
+
+## ContextMenuContent
+
+The menu a right-click opens. Never the only way to reach an action. A context menu is opened by a secondary pointer button or a keyboard's own menu key, and a meaningful share of readers have neither — a touch user, someone on a trackpad they have not configured, anyone driving the page by keyboard alone. Whatever is in here belongs somewhere reachable too: a row's overflow button, a toolbar.
+
+## ContextMenuItem
+
+A row. Highlight follows `data-highlighted`, which covers hover and keyboard.
+
+### Props
+
+- `icon` — `RemixiconComponentType | ReactNode`. Optional leading icon. Either spelling — `icon={Copy}` passes the component and this sizes it, `icon={<Copy size={16} />}` passes the element and this places it.
+- `destructive` — `boolean` default `false`. Paints the row as destructive. Use for delete, revoke, disconnect.
+
+Also accepts: `ComponentProps<typeof ContextMenuPrimitive.Item>`.
+
+## ContextMenuSeparator
+
+Hairline divider between groups.
+
+## ContextMenuLabel
+
+Mono eyebrow heading, on its own. Visual only: Radix renders it as a bare `<div>` with no role. Reach for `ContextMenuGroup` when the eyebrow is a HEADING over rows; this is right for a line that heads nothing.
+
+## ContextMenuGroup
+
+A named section of a menu. The eyebrow alone was a picture of a heading: Radix's `MenuLabel` carries no role and no `aria-labelledby` wiring, so a sighted reader saw sections and a screen-reader user got one undifferentiated list. This renders the group, renders the label inside it, and points the one at the other.
+
+### Props
+
+- `label` — `ReactNode`. The eyebrow over the rows, and the group's accessible name.
+
+Also accepts: `ComponentProps<typeof ContextMenuPrimitive.Group>`.
+
+## Examples
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger asChild><Card>Right-click me</Card></ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem icon={Copy}>Copy</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```