@misoto22/folio 0.0.0 → 0.16.0

package/dist/agent/RadarChart.md

@@ -0,0 +1,79 @@
+# RadarChart
+
+A profile across several named dimensions.
+
+- Kind: component
+- Group: Charts
+- Import: `import { RadarChart } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/radar-chart/
+- Related: line-chart, pie-chart
+
+## When to reach for it
+
+Recognising a silhouette. The area a radar encloses depends on the order its spokes happen to be in, so it is the wrong chart for comparing magnitudes.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with the polar plot inside one ChartContainer.
+- **Polygons** (required) — <RadarChart.Radar>. variant="filled" is the default and paints at 2.2 times --chart-fill, because a radar’s fill IS the mark rather than a wash under a line and has to hold its shape where two of them overlap.
+- **Spoke labels** — <RadarChart.PolarAngleAxis>, the names around the perimeter. They are the only thing that says what a corner of the silhouette measures.
+- **Radial scale** — <RadarChart.PolarRadiusAxis>, and it is opt-in. Leave it out and the rings carry no numbers at all: the reader has a shape and no idea what one ring is worth.
+- **Grid** — <RadarChart.PolarGrid>, polygonal rather than circular by default, so the rings line up with the polygon the data draws over them.
+- **Legend** — <RadarChart.Legend>. Two overlapping outlines two steps apart on the grey ramp name nothing, and there is no axis here to name them instead.
+
+## Best practices
+
+### Do
+
+- Fix the spoke ORDER and keep it fixed across every radar on the page. The area a polygon encloses is a function of the order the dimensions happen to sit in, so re-ordering the spokes changes the silhouette without changing one number.
+- Put every dimension on a comparable scale first — a percentile, a score out of ten, an index. One radius serves all the spokes, so a spoke in milliseconds beside one in percent draws a spike that means nothing.
+- Switch to variant="lines" past two series. Filled polygons overlap, and judging areas through two layers of translucency is precisely what this form is worst at.
+
+### Don’t
+
+- Do not read magnitude off it. A radar is for recognising a silhouette — the same profile before and after — and which of two is bigger is a question a BarChart answers and this one only appears to.
+- Do not skip <RadarChart.PolarRadiusAxis> and call the chart finished. It renders, the rings render, and nothing on screen says whether the outer ring is 100 or 1,000; the sr-only table still has the figures, the sighted reader does not.
+
+## Accessibility
+
+- title is required; the rows are also rendered as a visually hidden table.
+- Two or three series at most: filled polygons overlap, and judging areas through two layers of translucency is what a radar is worst at. Past that, variant="lines".
+
+## RadarChart
+
+A profile across several named dimensions — the shape for "what is this thing strong and weak at". It reads a SHAPE, not a set of values: the area a radar encloses depends on the order the spokes happen to be in, so it is the wrong chart for comparing magnitudes and the right one for recognising a silhouette. Two or three series at most.
+
+### 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 RechartsRadarChart>`. Escape hatch onto the raw Recharts chart element.
+- `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.
+- `loadingPoints` — `number`. How many points the skeleton draws.
+- `angleDataKey` — `keyof TData & string`. The row field naming each spoke. Used 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. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `RadarVariant` = `'filled' | 'lines'`
+
+## Examples
+
+```tsx
+<RadarChart title="Team skills" config={config} data={data} angleDataKey="skill">
+  <RadarChart.PolarGrid />
+  <RadarChart.PolarAngleAxis dataKey="skill" />
+  <RadarChart.Tooltip />
+  <RadarChart.Radar dataKey="current" />
+</RadarChart>
+```

package/dist/agent/RadialChart.md

@@ -0,0 +1,81 @@
+# RadialChart
+
+Values on an arc — a gauge, or a few totals against one scale.
+
+- Kind: component
+- Group: Charts
+- Import: `import { RadialChart } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/radial-chart/
+- Related: pie-chart, bar-chart
+
+## When to reach for it
+
+A single value against a fixed total. Past about four bars a BarChart is the honest choice, because a radial bar’s radius is not its value.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero rows. Its hidden table needs a value field, which it takes from valueKey or, failing that, from the dataKey of the composed <RadialChart.RadialBar> — so a chart that names neither still has no table.
+- **Arcs** (required) — <RadialChart.RadialBar>, one per row, 14px thick with a 5px cap. variant="semi" drops the centre to 70% so a half arc sits in the middle of its own box rather than at the top of it.
+- **Track** — showTrack, on by default, painting the unfilled remainder behind each arc in --chart-track. It is what makes a gauge a gauge: without it there is no visible whole for the fill to be a part of.
+- **Scale** — The PolarAngleAxis the root inserts when max is set, with domain [0, max] and its ticks off. Leave max unset and the domain is taken from the data instead.
+- **Legend** — <RadialChart.Legend>. An arc has no category axis, so above one bar this is the only thing naming them.
+
+## Best practices
+
+### Do
+
+- Set max on anything that is a gauge. Without it the scale comes from the data, so the largest bar always fills the arc and 62% and 98% are drawn identically.
+- Pass valueKey when the arc is not the only mark. It names the field the hidden table prints and the field the LEGEND reports a selection from; without either it or a composed <RadialChart.RadialBar> there is no value field, and the table is not empty but absent.
+- Use variant="semi" for a single value. A half arc reads as a dial with a floor and a ceiling, where a full ring asks the reader to work out what a whole circle was worth.
+
+### Don’t
+
+- Do not compare bars across radii. A radial bar’s LENGTH is its value but its RADIUS is not, so an inner arc and an outer arc holding the same number are drawn different lengths — past about four bars a BarChart is the honest form.
+- Do not let a reader take an arc as a share of the ring when max is unset. A full sweep then means the biggest thing here, which is a different sentence from all of it.
+
+## Accessibility
+
+- title is required; pass valueKey and the rows are also rendered as a visually hidden table.
+- Set max or the scale comes from the data and the largest bar always fills the arc — which makes 62% and 98% look identical.
+- showTrack draws the unfilled remainder, which is what makes a gauge readable at all.
+
+## RadialChart
+
+Values on an arc — a gauge, or a small set of totals against one scale. The caveat worth knowing before reaching for it: a radial bar's LENGTH is its value, but its RADIUS is not, so an inner bar and an outer bar of the same value are drawn different lengths. That makes it a poor comparison and a good single-value gauge; past about four bars, a `<BarChart>` is the honest choice.
+
+### Props
+
+- `config` (required) — `ChartConfig`. Bar 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.
+- `nameKey` (required) — `keyof TData & string`. The row field naming each bar.
+- `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 RechartsRadialBarChart>`. Escape hatch onto the raw Recharts chart element.
+- `variant` — `RadialVariant` default `'full'`. The arc shape — a full ring, or the half circle a gauge wants.
+- `max` — `number`. What a full sweep is worth. Without it the scale comes from the data, so the largest bar always fills the arc — which is right for a comparison and wrong for a gauge. Set it (typically 100) whenever a single value has to read against a fixed total, or "62%" and "98%" will look identical.
+- `innerRadius` — `number | string` default `'30%'`. Where the arc starts, from the centre.
+- `outerRadius` — `number | string` default `'100%'`. Where the arc ends.
+- `defaultSelectedBar` — `string | null` default `null`. The bar lit on first render, when the chart keeps its own selection.
+- `selectedBar` — `string | null`. The selected bar, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedBar`.
+- `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.
+- `valueKey` — `keyof TData & string`. The row field holding each bar's number, for the table view and for the selection the legend reports. Falls back to the `dataKey` of the composed `<RadialChart.RadialBar>`, so the usual call site needs neither.
+- `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
+
+- `RadialVariant` = `'full' | 'semi'`
+
+## Examples
+
+```tsx
+<RadialChart title="Storage used" config={config} data={data} nameKey="tier" max={100}>
+  <RadialChart.RadialBar dataKey="used" />
+  <RadialChart.Tooltip />
+</RadialChart>
+```

package/dist/agent/RadioGroup.md

@@ -0,0 +1,66 @@
+# RadioGroup
+
+A set of mutually exclusive choices.
+
+- Kind: component
+- Group: Forms
+- Import: `import { RadioGroup } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/radio-group/
+- Related: checkbox, select
+
+## Anatomy
+
+- **Group** (required) — A <div role="radiogroup"> stacking its options. Being a div is why the label above it names the group by being pointed AT — aria-labelledby, not htmlFor — and why the words do not click through.
+- **Row** (required) — The <label> RadioGroupItem wraps around control and words. It is the click target — a bare 18px circle is below every pointer-target guideline — and it is the only source of the option’s accessible name.
+- **Circle** (required) — The 18px control itself, its border turning --accent when chosen.
+- **Dot** — The 10px --accent fill inside the circle, present only on the chosen option.
+
+## Best practices
+
+### Do
+
+- Name the group. Inside a Field its label does it, through aria-labelledby; standing alone it needs its own aria-label, and without either the group is announced as three unlabelled radios.
+- Set defaultValue or value. Selection follows focus here, so a group that starts empty commits an answer the moment anybody arrows into it — including a reader who was only passing through on the way to the next field.
+- Add an explicit “None” or “Any” option when the answer is genuinely optional: there is no way back to nothing once a radio is chosen, neither by clicking it again nor from the keyboard.
+
+### Don’t
+
+- Do not hang an expensive effect on onValueChange. Every arrow press commits, so a group whose options fetch or navigate fires once per key on the way past the ones nobody wanted.
+- Do not reach past RadioGroupItem to the Radix primitive or hand-roll the row: selection-follows-focus is implemented in this item’s own focus handler, not upstream, so a hand-rolled one moves the outline and selects nothing.
+- Do not disable one option to mean “not available here”: the roving focus skips it entirely, so a keyboard reader never learns the option exists. Say why in the Field’s hint and leave the option out.
+
+## Accessibility
+
+- One tab stop for the whole group; the arrow keys move between options, per the ARIA radiogroup pattern.
+- The label is inside the <label>, so the whole row is the click target.
+
+## Keyboard
+
+- Tab — Moves into the group, and out of it — the whole group is one stop.
+- ↑ / ↓ / ← / → — Moves between options AND selects as it goes.
+
+## RadioGroup
+
+A set of mutually exclusive choices. Radix owns the roving tabindex, so the whole group is ONE tab stop and the arrow keys move between options — which is what the ARIA radiogroup pattern requires and what a stack of hand-rolled `<input type="radio">` wrappers usually gets wrong. Inside a `Field` the group takes its name from that label, by pointing back at it: the root is a `<div role="radiogroup">` and `<label for>` does not bind to one, so the words above it click through no more than a `<legend>` does. Standing alone, it still needs an `aria-label` of its own — an unnamed group is three unlabelled radios.
+
+Also accepts: `ComponentProps<typeof RadioGroupPrimitive.Root>`.
+
+## RadioGroupItem
+
+One option, and its label, as a single click target. The `<label>` wraps both, so the whole row is clickable — a bare 18px circle is below every pointer-target guideline and is miserable on a phone. It is also what gives the control its accessible name: remove the wrapper and the radio has no name at all. Selection follows focus, which is the half of the pattern that makes a radiogroup usable from the keyboard: moving to an option chooses it, so nobody has to press an extra key to commit. That is implemented here rather than inherited, because the upstream primitive gates it on a flag cleared by `keyup` and loses the race against its own focus move — see ARROW_GRACE_MS. Re-selecting an already-selected option is a no-op, so this stays correct even where the upstream path does fire.
+
+### Props
+
+- `children` (required) — `ReactNode`. The visible label. Rendered inside the `<label>` that wraps the control.
+
+Also accepts: `Omit<ComponentProps<typeof RadioGroupPrimitive.Item>, 'children'>`.
+
+## Examples
+
+```tsx
+<RadioGroup defaultValue="light" aria-label="Theme">
+  <RadioGroupItem value="light">Light</RadioGroupItem>
+  <RadioGroupItem value="dark">Dark</RadioGroupItem>
+</RadioGroup>
+```

package/dist/agent/Reading.md

@@ -0,0 +1,233 @@
+# Reading
+
+Article and project layouts, outlines, media and installation instructions.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { DetailMasthead } from '@misoto22/folio/website'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/reading/
+
+## When to reach for it
+
+Build long-form reading surfaces with consistent section spacing and accessible navigation.
+
+## 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.
+
+## DetailMasthead
+
+### Props
+
+- `backLink` — `ReactNode`.
+- `title` (required) — `string`.
+- `dek` — `ReactNode`.
+- `context` — `ReactNode`.
+- `aside` — `ReactNode`.
+- `actions` — `ReactNode`.
+- `metadata` — `ReadingMetadataItem[]` default `[]`.
+- `width` — `'page' | 'fill'` default `'page'`.
+
+## ReadingLayout
+
+### Props
+
+- `outline` — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ReadingSection
+
+`seamless` lets a structured child continue directly from the section rule without drawing a second seam.
+
+### Props
+
+- `title` — `ReactNode`.
+- `caption` — `ReactNode`.
+- `lead` — `ReactNode`.
+- `compact` — `boolean`.
+- `seamless` — `boolean`.
+
+Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.
+
+## ReadingLead
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `muted` — `ReactNode`.
+- `description` — `ReactNode`.
+
+## RecordPager
+
+### Props
+
+- `label` (required) — `string`.
+- `previous` — `ReadingPagerItem`.
+- `next` — `ReadingPagerItem`.
+
+## isSelfNumbered
+
+## numberToc
+
+## TableOfContents
+
+### Props
+
+- `items` (required) — `OutlineItem[]`.
+- `label` (required) — `string`.
+- `numbering` — `'auto' | 'none'` default `'auto'`.
+- `onNavigate` — `(id: string) => void`.
+- `expanded` — `boolean` default `false`.
+
+## MobileOutline
+
+### Props
+
+- `items` (required) — `OutlineItem[]`.
+- `title` (required) — `string`.
+- `openLabel` (required) — `string`.
+- `closeLabel` (required) — `string`.
+
+## ReadingProgress
+
+## AuthorPanel
+
+### Props
+
+- `avatar` — `ReactNode`.
+- `name` (required) — `string`.
+- `role` — `ReactNode`.
+- `bio` — `ReactNode`.
+- `links` — `ReactNode`.
+
+## ReadingFigure
+
+A reading image can preserve its source framing with `fit="contain"`, rather than silently cropping it to a house ratio.
+
+### Props
+
+- `media` (required) — `ReactNode`.
+- `captionStart` — `ReactNode`.
+- `captionEnd` — `ReactNode`.
+- `width` — `'page' | 'fill'` default `'page'`.
+- `ratio` — `string` default `'16 / 8'`.
+- `fit` — `'cover' | 'contain'` default `'cover'`.
+
+## MediaPlayback
+
+### Props
+
+- `src` (required) — `string`.
+- `poster` — `string`.
+- `label` (required) — `string`.
+- `playLabel` (required) — `string`.
+- `pauseLabel` (required) — `string`.
+- `fallback` (required) — `ReactNode`.
+
+## ActionBand
+
+A terminal project invitation with one strong entry action and quieter supporting actions.
+
+### Props
+
+- `title` (required) — `ReactNode`.
+- `description` — `ReactNode`.
+- `actions` — `ReactNode`.
+- `eyebrow` — `ReactNode`.
+
+## FeaturePairs
+
+### Props
+
+- `items` (required) — `{ id?: string; label?: ReactNode; title?: ReactNode; description: ReactNode }[]`.
+
+## DevicePreview
+
+### Props
+
+- `kind` (required) — `'browser' | 'phone'`.
+- `label` — `string`.
+- `media` (required) — `ReactNode`.
+- `caption` — `ReactNode`.
+
+## PreviewPair
+
+### Props
+
+- `desktop` (required) — `ReactNode`.
+- `mobile` — `ReactNode`.
+
+## CommandTabs
+
+### Props
+
+- `label` (required) — `string`.
+- `tabs` (required) — `CommandTab[]`.
+- `copyLabel` (required) — `string`.
+- `copiedLabel` (required) — `string`.
+- `footer` — `ReactNode`.
+
+## ReadingSurface
+
+### Props
+
+- `numbered` — `boolean`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## ReadingForm
+
+### Props
+
+- `inline` — `boolean`.
+
+Also accepts: `React.FormHTMLAttributes<HTMLFormElement>`.
+
+## ArchitectureColumns
+
+### Props
+
+- `columns` (required) — `{ title: string; connected?: boolean; nodes: ArchitectureColumnNode[] }[]`.
+- `foundation` — `ArchitectureColumnNode[]`.
+
+## TokenLine
+
+### Props
+
+- `items` (required) — `{ label: ReactNode; strong?: boolean; icon?: ReactNode }[]`.
+- `label` — `ReactNode`.
+- `separator` — `string` default `'·'`.
+
+## ContentFigure
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `caption` — `ReactNode`.
+- `wide` — `boolean`.
+
+## ReadingPage
+
+### Props
+
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## CommandSnippet
+
+### Props
+
+- `code` (required) — `string`.
+- `pieces` — `CommandPiece[]`.
+- `copyLabel` (required) — `string`.
+- `copiedLabel` (required) — `string`.
+- `className` — `string`.

package/dist/agent/Recovery.md

@@ -0,0 +1,72 @@
+# Recovery
+
+Loading, unavailable and missing-page states with recovery actions.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { RecoveryState } from '@misoto22/folio/website'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/recovery/
+
+## When to reach for it
+
+Explain the current state and provide a real next action.
+
+## 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.
+
+## RecoveryState
+
+A recovery page composed from the system error primitive and caller-owned destinations.
+
+### Props
+
+- `elsewhere` — `ReactNode`.
+
+Also accepts: `ErrorStateProps`.
+
+## RecoveryLinks
+
+Suggested destinations, with routing supplied by the host.
+
+### Props
+
+- `label` (required) — `string`.
+- `items` (required) — `{ id: string; link: ReactElement }[]`.
+
+## LoadingRouteIntro
+
+The shared masthead geometry, drawn from the core loading primitives.
+
+### Props
+
+- `titleClassName` — `string` default `'w-[min(100%,18rem)]'`.
+
+## LoadingRecords
+
+A collection skeleton with or without a media column.
+
+### Props
+
+- `rows` — `number` default `4`.
+- `media` — `boolean` default `true`.
+
+## WebsiteLoading
+
+Named loading layouts for the website's reusable page shapes.
+
+### Props
+
+- `label` (required) — `string`.
+- `layout` — `'records' | 'gallery' | 'media' | 'metrics' | 'identity'` default `'records'`.
+- `filters` — `boolean` default `false`.
+- `rows` — `number` default `4`.
+- `media` — `boolean` default `true`.
+- `titleClassName` — `string`.

package/dist/agent/SankeyChart.md

@@ -0,0 +1,85 @@
+# SankeyChart
+
+Where a quantity goes as it moves through stages.
+
+- Kind: component
+- Group: Charts
+- Import: `import { SankeyChart } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/sankey-chart/
+- Related: bar-chart
+
+## When to reach for it
+
+A funnel, a budget, an energy or traffic breakdown. The only chart here whose data is a graph rather than a table.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, named by title, with the diagram inside one ChartContainer.
+- **Node rectangles** (required) — The root’s own node renderer. A node whose name is in config is painted from its gradient; one that is not falls back to currentColor, so it is drawn plainly rather than lost.
+- **Node labels** — <SankeyChart.NodeLabel>, composed inside <SankeyChart.Node>, and entirely opt-in. Leave it out and NOTHING on the diagram is named — there is no legend here, so the names exist only in the tooltip and in the hidden table.
+- **Flow bands** — <SankeyChart.Link>. gradient fades the source’s colour into the target’s and is the variant that actually reads as flow; solid gives up colour entirely and lets the node rectangles carry identity.
+- **Hidden data table** (required) — The sr-only table lists the LINKS — from, to, value — rather than the nodes, because a table of node totals loses every from-and-to the diagram exists to state.
+
+## Best practices
+
+### Do
+
+- Treat the nodes array as an addressing table. A link’s source and target are INDEXES into it, so inserting a node at the front silently re-points every link at a different pair — and the layout still renders, which is why this belongs in a test rather than in an eyeball.
+- Compose <SankeyChart.Node> with a <SankeyChart.NodeLabel> inside it. Names are opt-in and there is no legend to fall back on, so a sankey without labels is a set of anonymous grey bands.
+- Keep the flows conserved, or give the shortfall a node of its own with a name. Band width is the only arithmetic on screen, and a node that quietly loses eight percent simply reads as a smaller node.
+
+### Don’t
+
+- Do not reach for it when the quantity only narrows along one path. That is a FunnelChart; a sankey spends its whole layout budget on splits that are not there.
+- Do not put twenty nodes in one column. nodePadding is 10px and the layout distributes what is left, so past a dozen a node rectangle is a few pixels tall and a label centred on it has nowhere to sit.
+
+## Accessibility
+
+- title is required. The hidden table lists the FLOWS rather than the nodes — a table of node totals would lose every “from → to” the diagram exists to show.
+- Four link variants: gradient reads as flow, source and target attribute a band to one end, solid gives up colour and lets the nodes carry identity.
+
+## SankeyChart
+
+Where a quantity goes as it moves through stages — the shape for a funnel, a budget, an energy or traffic breakdown. The only chart here whose data is a GRAPH rather than a table, so it takes `{ nodes, links }` instead of rows, and the table view lists the flows rather than the nodes.
+
+### Props
+
+- `data` (required) — `SankeyData`. The nodes and the links between them, in Recharts' own shape.
+- `config` (required) — `ChartConfig`. Node names → their label and paint.
+- `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.
+- `sankeyProps` — `Omit<SankeyProps, 'data'>`. Escape hatch onto the raw Recharts Sankey element.
+- `nodeWidth` — `number` default `10`. How wide each node rectangle is, in pixels.
+- `nodePadding` — `number` default `10`. Vertical gap between nodes in the same column, in pixels.
+- `linkCurvature` — `number` default `0.5`. 0 draws straight links, 1 the fullest curve.
+- `iterations` — `number` default `32`. Layout passes. More is tidier and slower.
+- `sort` — `boolean` default `true`. Lets the layout reorder nodes for the fewest crossings.
+- `align` — `'left' | 'justify'` default `'justify'`. How nodes are placed along the flow axis.
+- `verticalAlign` — `'justify' | 'top'` default `'justify'`. How nodes are distributed within a column.
+- `defaultSelectedNode` — `string | null` default `null`. The node lit on first render, when the chart keeps its own selection. Selecting one dims every flow it does not touch.
+- `selectedNode` — `string | null`. The selected node, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedNode`.
+- `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
+
+- `SankeyLinkVariant` = `'gradient' | 'solid' | 'source' | 'target'`
+- `SankeyLabelPosition` = `'inside' | 'outside'`
+
+## Examples
+
+```tsx
+<SankeyChart title="Traffic by source and outcome" config={config} data={data}>
+  <SankeyChart.Node radius={2}>
+    <SankeyChart.NodeLabel position="outside" showValues />
+  </SankeyChart.Node>
+  <SankeyChart.Link variant="gradient" />
+  <SankeyChart.Tooltip />
+</SankeyChart>
+```