@rinzai/zen 0.13.0 → 0.15.0

package/dist/docs/card.md

@@ -0,0 +1,180 @@
+# Card
+
+Glass panels for grouping content, and stats for single figures.
+
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, Stat, StatRow } from '@rinzai/zen';
+```
+
+## Examples
+
+### Goal
+
+```tsx
+import {
+    Button,
+    buttonVariants,
+    Card,
+    CardHeader,
+    CardTitle,
+    Menu,
+    MenuContent,
+    MenuItem,
+    MenuTrigger,
+    ProgressRing,
+} from '@rinzai/zen';
+// Icons from Heroicons (https://heroicons.com): Ellipsis (ellipsis-horizontal).
+
+export default function Goal() {
+    return (
+        <Card className="w-full max-w-sm">
+            <CardHeader>
+                <CardTitle>Emergency fund</CardTitle>
+                <Menu>
+                    <MenuTrigger
+                        aria-label="Goal actions"
+                        className={buttonVariants({ variant: 'ghost', size: 'icon' })}
+                    >
+                        <Ellipsis />
+                    </MenuTrigger>
+                    <MenuContent>
+                        <MenuItem>Edit</MenuItem>
+                    </MenuContent>
+                </Menu>
+            </CardHeader>
+            <div className="flex items-center gap-4">
+                <ProgressRing value={0.64} label="Emergency fund">
+                    <span className="text-sm font-semibold tabular-nums">64%</span>
+                </ProgressRing>
+                <div className="flex flex-col gap-1">
+                    <span className="text-muted-foreground text-sm">$6,400 of $10,000</span>
+                    <Button size="sm" variant="secondary" className="self-start">
+                        Add money
+                    </Button>
+                </div>
+            </div>
+        </Card>
+    );
+}
+```
+
+### Stats
+
+```tsx
+import { Stat, StatRow } from '@rinzai/zen';
+
+export default function Stats() {
+    return (
+        <StatRow className="w-full max-w-3xl">
+            <Stat label="Income" value="$8,450" hint="+4% on last month" />
+            <Stat label="Spent" value="$5,120" tone="negative" />
+            <Stat label="Net this month" value="$3,330" tone="positive" />
+        </StatRow>
+    );
+}
+```
+
+### Morph
+
+```tsx
+import { Button, Card, CardDescription, CardHeader, CardTitle, Sparkline } from '@rinzai/zen';
+import { startTransition, useState, ViewTransition } from 'react';
+
+const accounts = [
+    { id: 'checking', name: 'Checking', balance: '$4,280.15', trend: [31, 34, 30, 38, 36, 42, 40, 45] },
+    { id: 'savings', name: 'Savings', balance: '$12,940.00', trend: [80, 82, 83, 85, 86, 88, 91, 94] },
+    { id: 'card', name: 'Credit card', balance: '−$612.40', trend: [12, 18, 15, 22, 27, 21, 30, 26] },
+];
+
+export default function Morph() {
+    const [open, setOpen] = useState<string | null>(null);
+    const go = (id: string | null) => startTransition(() => setOpen(id));
+    const account = accounts.find((a) => a.id === open);
+
+    if (account)
+        return (
+            <ViewTransition name={`account-${account.id}`} share="zen-morph">
+                <Card className="w-full max-w-md">
+                    <CardHeader>
+                        <CardTitle>{account.name}</CardTitle>
+                        <Button size="sm" variant="ghost" onClick={() => go(null)}>
+                            Back
+                        </Button>
+                    </CardHeader>
+                    <p className="text-3xl font-semibold tabular-nums">{account.balance}</p>
+                    <CardDescription className="mt-1">Last 8 weeks</CardDescription>
+                    <Sparkline values={account.trend} className="mt-4 h-24 w-full" />
+                </Card>
+            </ViewTransition>
+        );
+
+    return (
+        <div className="grid w-full max-w-md gap-3">
+            {accounts.map((a) => (
+                <ViewTransition key={a.id} name={`account-${a.id}`} share="zen-morph">
+                    <Card className="p-0 md:p-0">
+                        <button
+                            type="button"
+                            onClick={() => go(a.id)}
+                            className="flex w-full items-center justify-between rounded-xl p-4 text-left"
+                        >
+                            <span className="font-medium">{a.name}</span>
+                            <span className="tabular-nums">{a.balance}</span>
+                        </button>
+                    </Card>
+                </ViewTransition>
+            ))}
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Card
+
+Glass panel whose border catches the pointer light. For a title with an
+action beside it, start it with a CardHeader holding a CardTitle and the action.
+
+No props of its own; it accepts the props of the element it renders.
+
+### CardHeader
+
+The top row of a Card: its title, and an action (a button, a menu) at the end.
+
+No props of its own; it accepts the props of the element it renders.
+
+### CardTitle
+
+The card's title: an h4 by default; with `asChild`, your own heading (an h2, say) gets its look.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  | Put the title's look on your own heading element instead of an h4. |
+
+### CardDescription
+
+A line under the CardTitle: what the card is about, or a figure's context ("₹12L at 8.5% · 20 years").
+
+No props of its own; it accepts the props of the element it renders.
+
+### Stat
+
+A single figure with a label, e.g. "Revenue  $12,400".
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` (required) | `string` |  |  |
+| `value` (required) | `ReactNode` |  |  |
+| `children` | `ReactNode` |  | Under the figure: how it got there, like a Sparkline. |
+| `className` | `string` |  |  |
+| `hint` | `ReactNode` |  |  |
+| `tone` | `"default" \| "negative" \| "positive"` | `default` |  |
+
+### StatRow
+
+Row of stats: two columns on phones (an odd last one spans both), three from `sm` up.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` |  |  |

package/dist/docs/carousel.md

@@ -0,0 +1,162 @@
+# Carousel
+
+Slides in a row that snap as you swipe or scroll, with glass buttons and dots that light the current one beneath, and the arrow keys. Native scrolling, so it follows the finger exactly.
+
+```tsx
+import { Carousel, CarouselContent, CarouselItem, CarouselControls, CarouselPrevious, CarouselNext, CarouselDots } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import {
+    Card,
+    Carousel,
+    CarouselContent,
+    CarouselControls,
+    CarouselDots,
+    CarouselItem,
+    CarouselNext,
+    CarouselPrevious,
+    ProgressRing,
+} from '@rinzai/zen';
+
+const GOALS = [
+    { name: 'Emergency fund', saved: 6400, target: 10000 },
+    { name: 'New laptop', saved: 1150, target: 1800 },
+    { name: 'Trip to Kyoto', saved: 2100, target: 4500 },
+    { name: 'Wedding gift', saved: 300, target: 300 },
+];
+
+const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+
+/** One slide at a time, with buttons and dots below. Swipe or scroll it too, or focus it and use the arrow keys. */
+export default function Default() {
+    return (
+        <Carousel aria-label="Savings goals" className="w-full max-w-sm">
+            <CarouselContent>
+                {GOALS.map((goal) => (
+                    <CarouselItem key={goal.name}>
+                        <Card className="flex items-center gap-5">
+                            <ProgressRing value={goal.saved / goal.target} label={goal.name}>
+                                <span className="text-sm font-semibold tabular-nums">
+                                    {Math.round((goal.saved / goal.target) * 100)}%
+                                </span>
+                            </ProgressRing>
+                            <div className="flex min-w-0 flex-col gap-1">
+                                <span className="truncate font-medium">{goal.name}</span>
+                                <span className="text-muted-foreground text-sm tabular-nums">
+                                    {usd.format(goal.saved)} of {usd.format(goal.target)}
+                                </span>
+                            </div>
+                        </Card>
+                    </CarouselItem>
+                ))}
+            </CarouselContent>
+            <CarouselControls>
+                <CarouselPrevious />
+                <CarouselDots />
+                <CarouselNext />
+            </CarouselControls>
+        </Carousel>
+    );
+}
+```
+
+### Several
+
+```tsx
+import { Carousel, CarouselContent, CarouselControls, CarouselItem, CarouselNext, CarouselPrevious } from '@rinzai/zen';
+
+const CATEGORIES = [
+    { name: 'Groceries', spent: '$412', chart: 6 },
+    { name: 'Rent', spent: '$1,600', chart: 7 },
+    { name: 'Transport', spent: '$96', chart: 1 },
+    { name: 'Eating out', spent: '$238', chart: 2 },
+    { name: 'Subscriptions', spent: '$54', chart: 5 },
+    { name: 'Health', spent: '$120', chart: 3 },
+];
+
+/**
+ * Several slides in view: size the items (here a half, then a third on wider
+ * screens). It snaps to each; the buttons sit together at the end, each gone when there's no further to go.
+ */
+export default function Several() {
+    return (
+        <Carousel aria-label="Spending by category" className="w-full max-w-xl">
+            <CarouselContent className="gap-3">
+                {CATEGORIES.map((c) => (
+                    <CarouselItem key={c.name} className="basis-[calc(50%-0.375rem)] sm:basis-[calc(33.333%-0.5rem)]">
+                        <div
+                            className="border-tint/10 flex h-28 flex-col justify-end gap-0.5 rounded-xl border p-4"
+                            style={{
+                                // The chart palette, so each category looks as it does in charts.
+                                background: `linear-gradient(160deg, color-mix(in oklch, var(--chart-${c.chart}) 35%, transparent), color-mix(in oklch, var(--chart-${c.chart}) 6%, transparent))`,
+                            }}
+                        >
+                            <span className="text-muted-foreground text-xs">{c.name}</span>
+                            <span className="text-lg font-semibold tabular-nums">{c.spent}</span>
+                        </div>
+                    </CarouselItem>
+                ))}
+            </CarouselContent>
+            <CarouselControls className="justify-end">
+                <CarouselPrevious />
+                <CarouselNext />
+            </CarouselControls>
+        </Carousel>
+    );
+}
+```
+
+## API reference
+
+### Carousel
+
+Slides in a row that scrolls sideways and snaps to each one: swipe, scroll,
+use the arrow keys once it has focus, or the CarouselPrevious and
+CarouselNext buttons. Put a CarouselContent of CarouselItems inside, then a
+CarouselControls of the buttons and CarouselDots if you want them. A slide is as wide as the
+carousel unless you size it (e.g. `basis-1/3` for three in view).
+
+No props of its own; it accepts the props of the element it renders.
+
+### CarouselContent
+
+The scrolling row of slides.
+
+No props of its own; it accepts the props of the element it renders.
+
+### CarouselItem
+
+One slide: it's announced as which of how many.
+
+No props of its own; it accepts the props of the element it renders.
+
+### CarouselControls
+
+The row under the slides: CarouselPrevious at the start, CarouselNext at the end, CarouselDots between.
+
+No props of its own; it accepts the props of the element it renders.
+
+### CarouselPrevious
+
+Scroll back one slide: a round glass button, gone at the first (keeping its
+place, so the controls don't shift). Put it in CarouselControls, under the
+slides, where it never covers them.
+
+No props of its own; it accepts the props of the element it renders.
+
+### CarouselNext
+
+Scroll on one slide: a round glass button, gone at the last.
+
+No props of its own; it accepts the props of the element it renders.
+
+### CarouselDots
+
+A dot for each place it can scroll to, the current one drawn out long and lit; each goes there.
+
+No props of its own; it accepts the props of the element it renders.

package/dist/docs/chart.md

@@ -0,0 +1,325 @@
+# Chart
+
+Areas, lines and bars on one axis, a donut and an allocation bar: plain SVG that draws itself in, with a crosshair tooltip, keyboard reading, a legend and a table for screen readers.
+
+```tsx
+import { Chart, ChartArea, ChartLine, ChartBar, ChartReference, ChartTooltipCard, DonutChart, AllocationBar } from '@rinzai/zen';
+```
+
+## Examples
+
+### Balance
+
+```tsx
+import { Chart, ChartArea, ChartReference } from '@rinzai/zen';
+
+const MONTHS = [
+    '2026-04',
+    '2026-05',
+    '2026-06',
+    '2026-07',
+    '2026-08',
+    '2026-09',
+    '2026-10',
+    '2026-11',
+    '2026-12',
+    '2027-01',
+    '2027-02',
+    '2027-03',
+];
+const BALANCE = [4.2, 5.1, 3.8, 4.6, 6.2, 7.1, 6.4, 7.9, 8.8, 7.6, 9.4, 10.2].map((l) => l * 100000);
+const TODAY = '2026-09';
+// One series split in two at today: solid where it happened, dashed where it's projected.
+const DATA = MONTHS.map((month, i) => ({
+    month,
+    balance: month <= TODAY ? BALANCE[i] : null,
+    projected: month >= TODAY ? BALANCE[i] : null,
+}));
+const label = (m: string) => new Date(`${m}-01T00:00Z`).toLocaleString('en-IN', { month: 'short', timeZone: 'UTC' });
+const money = new Intl.NumberFormat('en-IN', {
+    style: 'currency',
+    currency: 'INR',
+    notation: 'compact',
+    maximumFractionDigits: 1,
+});
+
+/** An area in the theme's glow: solid up to today, dashed ahead, with a "Today" marker. Point at it, or focus it and use the arrow keys. */
+export default function Balance() {
+    return (
+        <Chart
+            data={DATA}
+            x="month"
+            label="Balance over time"
+            summary="Balance grows from ₹4.2L in April to a projected ₹10.2L next March."
+            formatX={label}
+            formatY={(v) => money.format(v)}
+            className="w-full max-w-2xl"
+        >
+            <ChartArea dataKey="balance" label="Balance" color="oklch(var(--glow))" />
+            <ChartArea dataKey="projected" label="Projected" color="oklch(var(--glow-2))" dashed />
+            <ChartReference x={TODAY} label="Today" />
+        </Chart>
+    );
+}
+```
+
+### Cashflow
+
+```tsx
+import { Chart, ChartBar, ChartLine, ChartReference } from '@rinzai/zen';
+
+const DATA = [
+    { month: 'Apr', income: 92000, spending: 61000 },
+    { month: 'May', income: 92000, spending: 74000 },
+    { month: 'Jun', income: 98000, spending: 58000 },
+    { month: 'Jul', income: 98000, spending: 103000 },
+    { month: 'Aug', income: 98000, spending: 66000 },
+    { month: 'Sep', income: 112000, spending: 71000 },
+    { month: 'Oct', income: 112000, spending: 69000 },
+    { month: 'Nov', income: 112000, spending: 80000 },
+].map((r) => ({ ...r, net: r.income - r.spending }));
+const inr = new Intl.NumberFormat('en-IN', {
+    style: 'currency',
+    currency: 'INR',
+    notation: 'compact',
+    maximumFractionDigits: 1,
+});
+
+/** Bars grouped by month with a line on the same axis; months still to come are faded. */
+export default function Cashflow() {
+    return (
+        <Chart
+            data={DATA}
+            x="month"
+            label="Income and spending by month"
+            formatY={(v) => inr.format(v)}
+            className="w-full max-w-2xl"
+        >
+            <ChartBar dataKey="income" label="Income" dim={(_, i) => i > 5} />
+            <ChartBar dataKey="spending" label="Spending" dim={(_, i) => i > 5} />
+            <ChartLine dataKey="net" label="Net" color="var(--chart-3)" />
+            <ChartReference y={0} tone="negative" />
+        </Chart>
+    );
+}
+```
+
+### Lines
+
+```tsx
+import { Chart, ChartLine } from '@rinzai/zen';
+
+const DATA = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'].map((day, i) => ({
+    day,
+    web: [420, 480, 510, 470, 560, 690, 640][i],
+    ios: [310, 330, 360, 390, 380, 450, 470][i],
+    android: [220, 260, 250, 300, 330, 310, 360][i],
+}));
+
+/** Several series in the chart palette, in the order they're written; the legend appears for two or more. */
+export default function Lines() {
+    return (
+        <Chart data={DATA} x="day" label="Sessions by platform" height={220} className="w-full max-w-2xl">
+            <ChartLine dataKey="web" label="Web" />
+            <ChartLine dataKey="ios" label="iOS" />
+            <ChartLine dataKey="android" label="Android" />
+        </Chart>
+    );
+}
+```
+
+### Donut
+
+```tsx
+import { DonutChart, paletteColor } from '@rinzai/zen';
+
+const SPENDING = [
+    { key: 'home', label: 'Home', value: 28000 },
+    { key: 'food', label: 'Food', value: 14500 },
+    { key: 'travel', label: 'Travel', value: 9200 },
+    { key: 'fun', label: 'Fun', value: 6100 },
+    { key: 'other', label: 'Other', value: 3400 },
+];
+const total = SPENDING.reduce((s, x) => s + x.value, 0);
+const inr = (v: number) =>
+    new Intl.NumberFormat('en-IN', { style: 'currency', currency: 'INR', maximumFractionDigits: 0 }).format(v);
+
+/** Parts of a whole with the total in the middle, and a legend of your own beside it, in the chart's colours (paletteColor). */
+export default function Donut() {
+    return (
+        <div className="flex flex-wrap items-center gap-8">
+            <DonutChart items={SPENDING} label="Spending by category" formatValue={inr}>
+                <div>
+                    <div className="text-muted-foreground text-[0.68rem] tracking-[0.1em] uppercase">Spent</div>
+                    <div className="text-lg font-semibold tracking-tight">{inr(total)}</div>
+                </div>
+            </DonutChart>
+            <ul className="flex min-w-48 flex-col gap-2 text-sm">
+                {SPENDING.map((s, i) => (
+                    <li key={s.key} className="flex items-center gap-2.5">
+                        <span
+                            className="size-2.5 rounded-[3px]"
+                            style={{ background: paletteColor('chart', i, SPENDING.length) }}
+                        />
+                        <span className="flex-1">{s.label}</span>
+                        <span className="font-medium tabular-nums">{inr(s.value)}</span>
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+}
+```
+
+### Allocation
+
+```tsx
+import { AllocationBar, formatMoney } from '@rinzai/zen';
+
+/** Where September's income went. */
+export default function Allocation() {
+    return (
+        <AllocationBar
+            label="Income in September"
+            className="w-full max-w-md"
+            locale="en-US"
+            formatValue={(v) => formatMoney(v, 'USD', 'en-US', { showDecimals: false })}
+            items={[
+                { key: 'bills', label: 'Bills', value: 182000 },
+                { key: 'spending', label: 'Spending', value: 145600 },
+                { key: 'savings', label: 'Savings', value: 96000 },
+                { key: 'investing', label: 'Investing', value: 50000 },
+                { key: 'left', label: 'Left over', value: 26400 },
+            ]}
+        />
+    );
+}
+```
+
+## API reference
+
+### Chart
+
+A chart on one axis: areas, lines and bars over rows of data (e.g. months),
+with a recessive grid, a crosshair and a tooltip listing every series at the
+pointer (or keyboard: focus it and use the arrow keys), a legend for two or
+more series, and a table of the values for screen readers. Series draw in
+as they appear. Colours default to the chart palette (--chart-1…8) in the
+order the series are written; give each its own `color` for meaning (e.g.
+the theme's glow).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` (required) | `ReactNode` |  | ChartArea, ChartLine, ChartBar and ChartReference parts. |
+| `data` (required) | `readonly T[]` |  | One row per point on the x axis (e.g. a month). |
+| `label` (required) | `string` |  | Names the chart for screen readers. |
+| `x` (required) | `string` |  | The row field placed along the x axis. |
+| `className` | `string` |  |  |
+| `formatTooltipX` | `((value: T[X]) => string)` |  | The tooltip's title for an x value (defaults to formatX). |
+| `formatX` | `((value: T[X]) => string)` |  | Axis labels for x values. |
+| `formatY` | `((value: number) => string)` | `(n: number) => compactFormat.format(n)` | Axis ticks and tooltip values (defaults to compact numbers: 1.2K). |
+| `height` | `number` | `240` | Height in px, including the axis labels. |
+| `legend` | `boolean` |  | Show the legend. Defaults to on for two or more series, or a bar's `dimLabel`. |
+| `palette` | `ChartPalette` | `chart` | Colours for series that don't give their own: the categorical palette (default), or shades of the theme's glow. |
+| `renderTooltip` | `((row: T, index: number) => ReactNode)` |  | Your own tooltip for a row (build it from ChartTooltipCard). |
+| `summary` | `string` |  | A sentence on what the chart shows, for screen readers (e.g. its highest and lowest points). |
+
+### ChartArea
+
+A line with a soft fill down to the baseline.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dataKey` (required) | `string` |  | The row field holding this series' values (numbers; null for none). |
+| `label` (required) | `string` |  | Its name in the legend, the tooltip and the table. |
+| `color` | `string` |  | Any CSS colour. Defaults to the next of --chart-1…8. |
+| `curve` | `"linear" \| "monotone"` |  | Smooth (default) or straight between points. |
+| `dashed` | `boolean` |  | Dashed (e.g. a projection). |
+
+### ChartLine
+
+A 2px line. Gaps (null values) break it, so one series can be split into solid and dashed parts.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dataKey` (required) | `string` |  | The row field holding this series' values (numbers; null for none). |
+| `label` (required) | `string` |  | Its name in the legend, the tooltip and the table. |
+| `color` | `string` |  | Any CSS colour. Defaults to the next of --chart-1…8. |
+| `curve` | `"linear" \| "monotone"` |  | Smooth (default) or straight between points. |
+| `dashed` | `boolean` |  | Dashed (e.g. a projection). |
+
+### ChartBar
+
+Bars, grouped with the other bar series, growing from the baseline.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dataKey` (required) | `string` |  | The row field holding this series' values (numbers; null for none). |
+| `label` (required) | `string` |  | Its name in the legend, the tooltip and the table. |
+| `color` | `string` |  | Any CSS colour. Defaults to the next of --chart-1…8. |
+| `dim` | `((row: Row, index: number) => boolean)` |  | Rows whose bar is faded, e.g. months still to come. |
+| `dimLabel` | `string` |  | What the faded bars mean, e.g. "Planned": the legend gets a faded key for it (and shows, even for one series). |
+
+### ChartReference
+
+A marker across the plot: a horizontal line at `y` (e.g. zero), or a vertical one at the row whose x is `x` (e.g. today).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dashed` | `boolean` |  | Vertical lines are dashed unless `dashed={false}`; horizontal ones solid unless `dashed`. |
+| `label` | `string` |  | Text beside a vertical line, e.g. "Today". |
+| `tone` | `"muted" \| "negative"` |  | Destructive for a line that warns (e.g. below zero). |
+| `x` | `unknown` |  | A vertical line at the row whose x field equals this. |
+| `y` | `number` |  | A horizontal line at this value. |
+
+### ChartTooltipCard
+
+The tooltip's card: a title and one row per series, the value first and the
+series keyed by a short stroke of its colour. Use it in `renderTooltip` to
+show your own rows.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `rows` (required) | `{ label: string; value: string; color?: string \| undefined; dashed?: boolean \| undefined; }[]` |  |  |
+| `title` (required) | `ReactNode` |  |  |
+| `className` | `string` |  |  |
+
+### DonutChart
+
+A ring of parts of a whole (e.g. spending by category), with your content in
+the middle (e.g. the total). Segments are parted by a small gap, with
+rounded corners; pointing at one (or focusing it) lifts it and shows its
+value. A part too small to show at its share is drawn as a pill, the
+narrowest segment, taking the room from the larger parts in proportion. Best
+for a handful of parts: past about six, use bars. Colours default to the
+chart palette in order.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` (required) | `{ key: string; label: string; value: number; color?: string \| undefined; }[]` |  | The parts, in order round the ring from 12 o'clock. |
+| `label` (required) | `string` |  | Names the chart for screen readers. |
+| `children` | `ReactNode` |  | Content in the middle, e.g. the total. |
+| `className` | `string` |  |  |
+| `formatValue` | `((value: number) => string)` |  | Values in the tooltip and for screen readers. |
+| `palette` | `ChartPalette` | `chart` | Colours for items that don't give their own: the categorical palette (default), or shades of the theme's glow. |
+| `size` | `number` | `200` | Diameter in px. |
+| `thickness` | `number` | `0.32` | Ring thickness as a share of the radius. |
+
+### AllocationBar
+
+Where a whole went, as one bar split into its parts (e.g. income across
+spending, savings and bills), with a legend of each part's value and share.
+Pointing at a part, in the bar or the legend, picks it out; screen readers
+hear every part's value and share from the bar's label. Sweeps in from
+the start the first time it's seen. Colours default to the chart palette in
+order, like DonutChart's.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` (required) | `AllocationItem[]` |  |  |
+| `label` (required) | `string` |  | What the whole is, e.g. "Income in September", for screen readers. |
+| `className` | `string` |  |  |
+| `formatValue` | `((value: number) => string)` |  |  |
+| `legend` | `boolean` | `true` | The list of parts under the bar (default on). |
+| `locale` | `string` |  | For the shares' percent format. |
+| `palette` | `ChartPalette` | `chart` | Colours for items that don't give their own: the categorical palette (default), or shades of the theme's glow. |