division-ds 0.1.2 → 0.2.1

package/public/docs/components/carousel.md

@@ -0,0 +1,130 @@
+# Carousel
+
+> A row of items that scrolls sideways. The browser does the scrolling, and Previous and Next move it a page at a time. Nothing ever moves on its own.
+
+- **Best for:** A sideways preview of more items than fit, with a link to the full list nearby.
+- **Not for:** A few items that fit: use a grid. And it's not for the only copy of anything.
+- Organism. Source: `src/components/organisms/carousel/Carousel.tsx`
+- Rendered docs page: `/components/carousel`
+
+## Import
+
+```tsx
+import { Carousel } from 'src/components/organisms/carousel/Carousel'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The region's accessible name (the name a screen reader announces), for example "Offers". Leaving it out is a compile error. |
+| `children` | `ReactNode` |  | Each child becomes one list item and keeps its own key. |
+| `itemWidth` | `string` | `'min(18rem, 80%)'` | Any CSS length. A percentage is a share of the track's width. Keep it under the full width, so the edge of the next item shows. |
+| `gutter` | `string` | `'0.5rem'` | The space between the track's edge and the first and last item, in any CSS length (rem is a unit tied to the base text size). It's never less than 0.5rem, whatever you pass, because an edge item draws its focus ring there. Set it to the page gutter to run the track edge to edge. |
+| `className` | `string` |  | Merged onto the region. |
+| `ref` | `Ref<HTMLElement>` |  | Forwarded to the region. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Product cards
+
+```tsx
+const photo = (id: string) => ({ src: `/media/products/${id}.webp` })
+
+const OFFERS: Product[] = [
+  { id: 'kestrel-k', name: 'Kestrel K compact replica', href: '#kestrel-k', price: 12900, compareAtPrice: 14900, badge: 'Sale' },
+  { id: 'field-goggles', name: 'Field goggles', href: '#field-goggles', price: 3400, compareAtPrice: 3900, badge: 'Sale' },
+  { id: 'beam-600', name: 'Beam 600 rail light', href: '#beam-600', price: 2400, compareAtPrice: 2900 },
+  { id: 'speed-loader', name: 'Speed loader, 150 BBs', href: '#speed-loader', price: 790, compareAtPrice: 990 },
+  { id: 'magazine-amber', name: 'Amber magazine, 48 BBs', href: '#magazine-amber', price: 890, compareAtPrice: 1090 },
+  { id: 'knee-pads', name: 'Knee pads, pair', href: '#knee-pads', price: 2400, compareAtPrice: 2900 },
+].map(product => ({ ...product, image: photo(product.id) }))
+
+function ProductCardsExample() {
+  const { toast } = useToast()
+  return (
+    <Carousel label="Offers" itemWidth="min(16rem, 80%)">
+      {OFFERS.map(product => (
+        <ProductCard
+          key={product.id}
+          product={product}
+          headingLevel={4}
+          onAddToCart={added => toast({ title: 'Added to cart', description: added.name, tone: 'ok' })}
+        />
+      ))}
+    </Carousel>
+  )
+}
+
+<ProductCardsExample />
+```
+
+### Nothing inside takes keyboard focus, so the Tab key stops on the track itself
+
+```tsx
+const STEPS = ['Unload', 'Disconnect', 'Wipe down', 'Clean the barrel', 'Check the hop-up', 'Store']
+
+<Carousel label="Cleaning steps" itemWidth="12rem">
+  {STEPS.map((step, index) => (
+    <div
+      key={step}
+      className="flex h-28 flex-col justify-between border border-[var(--color-border-hairline-strong)] p-4"
+    >
+      <span className="font-mono text-xs tabular-nums text-[var(--color-text-secondary)]">
+        {String(index + 1).padStart(2, '0')}
+      </span>
+      <span className="font-display font-semibold text-[var(--color-text-primary)]">{step}</span>
+    </div>
+  ))}
+</Carousel>
+```
+
+### Three short items: both buttons do nothing while everything fits
+
+```tsx
+<Carousel label="Kestrel lengths" itemWidth="8rem">
+  {['Kestrel K', 'Kestrel C', 'Kestrel L'].map(name => (
+    <div
+      key={name}
+      className="flex h-20 items-center justify-center border border-[var(--color-border-hairline-strong)] font-display font-semibold text-[var(--color-text-primary)]"
+    >
+      {name}
+    </div>
+  ))}
+</Carousel>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to Previous, then Next, then through anything focusable in each item. An item scrolls into view as it takes focus. |
+| `Enter` `Space` | On Previous or Next, scrolls one page of items. Does nothing (it's inert) at the matching end. |
+| `←` `→` | Scroll the track when the track itself has focus. The track is only a tab stop when no item holds anything focusable. |
+
+## Do
+
+- Name it for what it holds: "Offers", "Top-rated accessories".
+- Give it enough items to scroll. Three that fit are a grid.
+- Link to the full list nearby. A carousel is a preview, so it shouldn't be the only way to reach the rest.
+- Set the gutter to the page gutter when the track should run to the edge of the page.
+
+## Don't
+
+- Don't add autoplay. Content that moves on its own needs a pause control, and it pulls attention away from whoever's reading the page.
+- Don't put the only copy of anything in it. What's off to the side is easy to miss.
+- Don't hide the buttons on touch screens. A pointer, a switch device or a screen magnifier may be all someone has.
+- Don't wrap it in an element with overflow hidden to tidy the edges. That clips the focus ring the gutter is there to show.
+
+## Anatomy
+
+- **Region**: A section with aria-roledescription="carousel", named by the label. (ARIA, Accessible Rich Internet Applications, is a set of attributes that tell screen readers what an element is.)
+- **Position**: Monospaced text such as "1 to 3 of 8", saying which items are showing. It updates on every scroll, but it isn't a live region, so screen readers don't read it out each time.
+- **Previous / Next**: Secondary IconButtons, placed before the items in the Tab order. At the ends they're marked aria-disabled instead of disabled, so each stays a tab stop (a place the Tab key lands).
+- **Track**: A list that's the browser's own scroll container, with scroll snap and no visible scrollbar. It's padded on all four sides, so an item at the edge draws its focus ring inside the track.
+- **Item**: A list item, one per child, at the item width. The edge of the next one always shows.
+- **Status**: Hidden from view, read by screen readers. Says where the track stopped after a press on Previous or Next.

package/public/docs/components/cart.md

@@ -0,0 +1,172 @@
+# Cart
+
+> The lines someone means to buy, with quantities, line totals and a subtotal that screen readers announce as it changes. Removing a line can be undone, and focus (where keyboard input goes) is never lost.
+
+- **Best for:** The lines someone means to buy: quantities, line totals, a subtotal and removal that can be undone.
+- **Not for:** Collecting shipping and payment: use CheckoutForm.
+- Organism. Source: `src/components/organisms/cart/Cart.tsx`
+- Rendered docs page: `/components/cart`
+
+## Import
+
+```tsx
+import { Cart } from 'src/components/organisms/cart/Cart'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `lines` | `CartLine[]` |  | Required. The cart doesn't keep any lines of its own. |
+| `onQuantityChange` | `(id: string, quantity: number) => void` |  | Required. Called when a line's QuantityStepper changes. |
+| `onRemove` | `(id: string) => void` |  | Required. Called when Remove is pressed. |
+| `onRestore` | `(line: CartLine, index: number) => void` |  | Puts a removed line back at its old position. When you pass it, the removal toast offers Undo. |
+| `title` | `string` | `'Cart'` | The heading's text, and the cart's accessible name (the name a screen reader announces). |
+| `headingLevel` | `2 \| 3 \| 4` | `2` | Match the page's heading outline. |
+| `emptyMessage` | `string` | `'Your cart is empty.'` | Shown in place of the list. |
+| `footer` | `ReactNode` |  | Under the subtotal, such as a checkout button. Hidden while the cart's empty. |
+| `currency` | `string` | `'EUR'` | Passed to formatMoney. |
+| `locale` | `string` | `'en-IE'` | Passed to formatMoney. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | Draws a line name that has an href. |
+| `className` | `string` |  | Merged with the root classes. Later Tailwind utilities win. |
+| `ref` | `Ref<HTMLElement>` |  | The section. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type CartLine = {
+  /** Unique within lines: rows are keyed by it, and callbacks identify lines by it. */
+  id: string
+  name: string
+  href?: string
+  /** Size, colour and the like: "Size M · Ember". */
+  detail?: string
+  /** In the currency's minor unit (cents for EUR). */
+  unitPrice: number
+  quantity: number
+  /** @default 99 */
+  maxQuantity?: number
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### In the page
+
+```tsx
+const LINES: CartLine[] = [
+  { id: 'kestrel-c', name: 'Kestrel C carbine replica', href: '#kestrel-c', detail: 'Black', unitPrice: 13900, quantity: 1 },
+  {
+    id: 'prism-holo-sight',
+    name: 'Prism holo sight',
+    href: '#prism-holo-sight',
+    unitPrice: 4900,
+    quantity: 2,
+  },
+  { id: 'beam-600', name: 'Beam 600 rail light', href: '#beam-600', unitPrice: 2400, quantity: 1 },
+]
+
+function useCart(initial: CartLine[]) {
+  const [lines, setLines] = useState(initial)
+  return {
+    lines,
+    onQuantityChange: (id: string, quantity: number) =>
+      setLines(all => all.map(line => (line.id === id ? { ...line, quantity } : line))),
+    onRemove: (id: string) => setLines(all => all.filter(line => line.id !== id)),
+    onRestore: (line: CartLine, index: number) => setLines(all => [...all.slice(0, index), line, ...all.slice(index)]),
+  }
+}
+
+function InThePageExample() {
+  const cart = useCart(LINES)
+  return <Cart {...cart} title="Cart" headingLevel={4} footer={<Button>Check out</Button>} />
+}
+
+<InThePageExample />
+```
+
+### In a sheet
+
+```tsx
+const LINES: CartLine[] = [
+  { id: 'kestrel-c', name: 'Kestrel C carbine replica', href: '#kestrel-c', detail: 'Black', unitPrice: 13900, quantity: 1 },
+  {
+    id: 'prism-holo-sight',
+    name: 'Prism holo sight',
+    href: '#prism-holo-sight',
+    unitPrice: 4900,
+    quantity: 2,
+  },
+  { id: 'beam-600', name: 'Beam 600 rail light', href: '#beam-600', unitPrice: 2400, quantity: 1 },
+]
+
+function useCart(initial: CartLine[]) {
+  const [lines, setLines] = useState(initial)
+  return {
+    lines,
+    onQuantityChange: (id: string, quantity: number) =>
+      setLines(all => all.map(line => (line.id === id ? { ...line, quantity } : line))),
+    onRemove: (id: string) => setLines(all => all.filter(line => line.id !== id)),
+    onRestore: (line: CartLine, index: number) => setLines(all => [...all.slice(0, index), line, ...all.slice(index)]),
+  }
+}
+
+function InASheetExample() {
+  const cart = useCart(LINES)
+  return (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button variant="secondary">Open cart</Button>
+      </SheetTrigger>
+      <SheetContent title="Your cart">
+        <Cart {...cart} title="Items" headingLevel={3} footer={<Button>Check out</Button>} />
+      </SheetContent>
+    </Sheet>
+  )
+}
+
+<InASheetExample />
+```
+
+### Empty
+
+```tsx
+<Cart lines={[]} onQuantityChange={() => {}} onRemove={() => {}} headingLevel={4} title="Saved for later" />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through each line's link, quantity and Remove. |
+| `↑` `↓` | On a quantity, steps it by one. |
+| `Enter` | On Remove, removes the line. Focus moves to the next line. |
+| `F8` | Jumps to the removal toast, so you can reach Undo. |
+
+## Do
+
+- Pass onRestore, so a removal can be undone.
+- Store prices in the currency's smallest unit (cents for EUR).
+- Put the cart in a Sheet on narrow screens. The Undo toast shows inside it.
+- Remove a line on the page, then open a sheet: the Undo toast moves into the sheet and still works there.
+- Expect Undo pressed there to leave focus on the sheet's own toast list, inside its focus trap (the sheet keeps keyboard focus inside itself), never on the page body. The page's cart is hidden and can't take it.
+
+## Don't
+
+- Don't let a quantity reach zero. Remove is how a line leaves.
+- Don't remove a line without telling the cart. It's controlled: it shows only the lines you pass in.
+
+## Anatomy
+
+- **Heading**: Names the cart. Focus lands here once it's empty.
+- **Line**: Name (a link when it has an href), detail, unit price, quantity, line total and Remove.
+- **Quantity**: A QuantityStepper named '{name} quantity', starting at 1.
+- **Remove**: A ghost icon button named 'Remove {name}'.
+- **Subtotal**: A status line visible only to screen readers (sr-only), plus a visual twin. Screen readers announce the status as it changes. The twin, in tabular figures, is what sighted readers see, and it's aria-hidden (hidden from screen readers) so nothing is announced twice.
+- **Footer**: Optional actions, such as Check out.

package/public/docs/components/chart-panel.md

@@ -0,0 +1,358 @@
+# ChartPanel
+
+> One chart in a card. A sentence says what it shows, and the same numbers sit in a table. The data below is sample data.
+
+- **Best for:** One chart (a line over time, bars by category, a donut of one whole, or a radar of several measures) with a summary sentence and the numbers as a table.
+- **Not for:** One number and its change: use Stat. One score from 0 to 100: use ScoreRing. Two measures on two scales: use two panels.
+- Organism. Source: `src/components/organisms/chart-panel/ChartPanel.tsx`
+- Rendered docs page: `/components/chart-panel`
+
+## Import
+
+```tsx
+import { ChartPanel } from 'src/components/organisms/chart-panel/ChartPanel'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` |  | Required. The panel's heading and its name. |
+| `summary` | `string` |  | Required. One sentence, the chart's caption. |
+| `kind` | `'line' \| 'bar' \| 'donut' \| 'radar'` |  | Required. Line for change over time. Bar to compare categories. Donut for parts of one whole (one series, a slice per row). Radar for several measures of one or two things (an axis per row). |
+| `data` | `Row[]` |  | Required. One object per category. |
+| `xKey` | `keyof Row` |  | Required. The category. Its values must be unique. |
+| `xLabel` | `string` |  | Required. The header of the table's first column. |
+| `series` | `[ChartSeries] \| [ChartSeries, ChartSeries]` |  | Required. One or two series, coloured chart.series-1 then chart.series-2. Passing a third is a type error, and so is a ChartSeries.key that isn't one of Row's own numeric columns. |
+| `area` | `boolean` | `false` | Line only. Fills under each line with a gradient of its colour that fades to nothing. |
+| `curve` | `'linear' \| 'smooth'` | `'linear'` | Line only. smooth draws a monotone curve, so it never overshoots a data point. |
+| `grid` | `boolean` | `true` | The dashed horizontal grid (on a radar, its web). false also drops the axis lines but keeps the tick labels. |
+| `size` | `'md' \| 'sm'` | `'md'` | sm is the stat-card size: a short sparkline with no axes or grid, and the caption under it. Pair it with headline. |
+| `headline` | `string` |  | A formatted figure printed large under the title. |
+| `centerLabel` | `string` |  | Donut only. The caption under the total in the centre of the ring. |
+| `formatValue` | `(value: number) => string` | `Intl.NumberFormat('en-IE')` | Formats numbers in the tooltip and the table. It formats the y-axis too, unless you give formatAxisValue. |
+| `formatAxisValue` | `(value: number) => string` | `formatValue` | Formats only the y-axis tick labels. Use a shorter, compact formatter when formatValue's output is too wide for the axis. SpendChart's compact euro formatter is one example. |
+| `axisWidth` | `number` | `48` | The width the y-axis reserves, in px (pixels). 48 is Recharts' own YAxis default. Make it bigger if formatAxisValue's labels still get cut off. |
+| `bands` | `{ from: string \| number; to: string \| number; label?: string }[]` | `[]` | Line and bar only. Shades stretches of the x-axis, such as night hours on a 24-hour chart. from and to are x-axis values (values of xKey), both included. When from comes after to in the data, the band wraps past the end: 22:00 to 06:00 shades 22:00 to the last point and the first point to 06:00. A band naming a value that isn't in the data is skipped. Every band is listed under the chart with its label, so screen readers hear it too. |
+| `limits` | `{ value: number; label?: string }[]` | `[]` | Line and bar only, not at size sm. Draws a dashed horizontal line at a y value, such as an alert limit of 35 µg/m³. The y-axis grows to include it, so a limit above every data point stays in view. Every limit is listed under the chart with its label and its value formatted by formatValue, so screen readers hear it too. |
+| `headingLevel` | `2 \| 3 \| 4` | `3` | Pick the level that fits the page's heading outline. |
+| `className` | `string` |  | Merged with the Card classes. Later Tailwind utilities win. |
+| `ref` | `Ref<HTMLElement>` |  | Points at the section element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type ChartSeries<Row> = { key: NumericKey<Row>; label: string }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Line, two series
+
+```tsx
+type Week = { week: string; online: number; store: number }
+
+const WEEKS: Week[] = [
+  { week: 'W1', online: 120, store: 160 },
+  { week: 'W2', online: 131, store: 158 },
+  { week: 'W3', online: 142, store: 163 },
+  { week: 'W4', online: 150, store: 155 },
+  { week: 'W5', online: 171, store: 162 },
+  { week: 'W6', online: 188, store: 159 },
+  { week: 'W7', online: 197, store: 166 },
+  { week: 'W8', online: 214, store: 161 },
+]
+
+<ChartPanel<Week>
+  title="Weekly orders"
+  summary="Online orders rose from 120 to 214 over eight weeks and passed in-store orders in week 5."
+  kind="line"
+  data={WEEKS}
+  xKey="week"
+  xLabel="Week"
+  series={[
+    { key: 'online', label: 'Online' },
+    { key: 'store', label: 'In store' },
+  ]}
+  headingLevel={4}
+/>
+```
+
+### Bar, one series
+
+```tsx
+type Category = { category: string; returns: number }
+
+const RETURNS: Category[] = [
+  { category: 'Replicas', returns: 18 },
+  { category: 'Optics', returns: 11 },
+  { category: 'Parts', returns: 26 },
+  { category: 'Ammo', returns: 7 },
+  { category: 'Tactical', returns: 4 },
+]
+
+<ChartPanel<Category>
+  title="Returns by category"
+  summary="Parts have the most returns (26), then replicas (18); tactical equipment has the fewest (4)."
+  kind="bar"
+  data={RETURNS}
+  xKey="category"
+  xLabel="Category"
+  series={[{ key: 'returns', label: 'Returns' }]}
+  headingLevel={4}
+/>
+```
+
+### Area under a smooth line
+
+```tsx
+type Day = { day: string; visits: number; orders: number }
+
+const DAYS: Day[] = [
+  { day: 'Mon', visits: 1840, orders: 61 },
+  { day: 'Tue', visits: 2210, orders: 74 },
+  { day: 'Wed', visits: 1960, orders: 58 },
+  { day: 'Thu', visits: 2650, orders: 92 },
+  { day: 'Fri', visits: 3120, orders: 118 },
+  { day: 'Sat', visits: 3890, orders: 141 },
+  { day: 'Sun', visits: 3370, orders: 126 },
+]
+
+<ChartPanel<Day>
+  title="Visits this week"
+  summary="Visits climbed from 1,840 on Monday to a Saturday peak of 3,890."
+  kind="line"
+  area
+  curve="smooth"
+  data={DAYS}
+  xKey="day"
+  xLabel="Day"
+  series={[{ key: 'visits', label: 'Visits' }]}
+  headline="19,040"
+  headingLevel={4}
+/>
+```
+
+### No grid lines: only the labels along the axes
+
+```tsx
+type Week = { week: string; online: number; store: number }
+
+const WEEKS: Week[] = [
+  { week: 'W1', online: 120, store: 160 },
+  { week: 'W2', online: 131, store: 158 },
+  { week: 'W3', online: 142, store: 163 },
+  { week: 'W4', online: 150, store: 155 },
+  { week: 'W5', online: 171, store: 162 },
+  { week: 'W6', online: 188, store: 159 },
+  { week: 'W7', online: 197, store: 166 },
+  { week: 'W8', online: 214, store: 161 },
+]
+
+<ChartPanel<Week>
+  title="Weekly orders, gridless"
+  summary="Online orders rose from 120 to 214 over eight weeks and passed in-store orders in week 5."
+  kind="line"
+  area
+  curve="smooth"
+  grid={false}
+  data={WEEKS}
+  xKey="week"
+  xLabel="Week"
+  series={[
+    { key: 'online', label: 'Online' },
+    { key: 'store', label: 'In store' },
+  ]}
+  headingLevel={4}
+/>
+```
+
+### A shaded band: night hours on a 24-hour series (the band wraps past midnight)
+
+```tsx
+type Hour = { hour: string; pm25: number }
+
+const PM25 = [9, 8, 7, 7, 8, 11, 17, 26, 31, 24, 18, 15, 14, 13, 14, 16, 21, 29, 34, 27, 19, 14, 11, 10]
+
+const HOURS: Hour[] = PM25.map((pm25, hour) => ({ hour: `${String(hour).padStart(2, '0')}:00`, pm25 }))
+
+<ChartPanel<Hour>
+  title="Fine particles today"
+  summary="PM2.5 peaked at the morning and evening rush hours, 31 and 34 µg/m³, and stayed lowest overnight."
+  kind="line"
+  area
+  curve="smooth"
+  data={HOURS}
+  xKey="hour"
+  xLabel="Hour"
+  series={[{ key: 'pm25', label: 'PM2.5 (µg/m³)' }]}
+  bands={[{ from: '22:00', to: '06:00', label: 'Night' }]}
+  limits={[{ value: 35, label: 'Alert limit (µg/m³)' }]}
+  headingLevel={4}
+/>
+```
+
+### Small: stat cards, each with a sparkline (a tiny line chart with no axes)
+
+```tsx
+type Week = { week: string; online: number; store: number }
+
+type Day = { day: string; visits: number; orders: number }
+
+const WEEKS: Week[] = [
+  { week: 'W1', online: 120, store: 160 },
+  { week: 'W2', online: 131, store: 158 },
+  { week: 'W3', online: 142, store: 163 },
+  { week: 'W4', online: 150, store: 155 },
+  { week: 'W5', online: 171, store: 162 },
+  { week: 'W6', online: 188, store: 159 },
+  { week: 'W7', online: 197, store: 166 },
+  { week: 'W8', online: 214, store: 161 },
+]
+
+const DAYS: Day[] = [
+  { day: 'Mon', visits: 1840, orders: 61 },
+  { day: 'Tue', visits: 2210, orders: 74 },
+  { day: 'Wed', visits: 1960, orders: 58 },
+  { day: 'Thu', visits: 2650, orders: 92 },
+  { day: 'Fri', visits: 3120, orders: 118 },
+  { day: 'Sat', visits: 3890, orders: 141 },
+  { day: 'Sun', visits: 3370, orders: 126 },
+]
+
+<ChartPanel<Day>
+  title="Visits"
+  headline="19,040"
+  summary="Up every day but Wednesday and Sunday."
+  kind="line"
+  area
+  curve="smooth"
+  size="sm"
+  data={DAYS}
+  xKey="day"
+  xLabel="Day"
+  series={[{ key: 'visits', label: 'Visits' }]}
+  headingLevel={4}
+/>
+<ChartPanel<Day>
+  title="Orders"
+  headline="670"
+  summary="Saturday took 141, the most of the week."
+  kind="bar"
+  size="sm"
+  data={DAYS}
+  xKey="day"
+  xLabel="Day"
+  series={[{ key: 'orders', label: 'Orders' }]}
+  headingLevel={4}
+/>
+<ChartPanel<Week>
+  title="Online orders"
+  headline="214"
+  summary="Eight weeks of growth, from 120 a week."
+  kind="line"
+  curve="smooth"
+  size="sm"
+  data={WEEKS}
+  xKey="week"
+  xLabel="Week"
+  series={[{ key: 'online', label: 'Online' }]}
+  headingLevel={4}
+/>
+```
+
+### Donut with a centre total
+
+```tsx
+type Slice = { channel: string; orders: number }
+
+const CHANNELS: Slice[] = [
+  { channel: 'Web shop', orders: 412 },
+  { channel: 'Field store', orders: 236 },
+  { channel: 'Club orders', orders: 148 },
+  { channel: 'Marketplace', orders: 87 },
+  { channel: 'Phone', orders: 41 },
+]
+
+<ChartPanel<Slice>
+  title="Orders by channel"
+  summary="The web shop took 412 of 924 orders this month, nearly half; phone orders are 4%."
+  kind="donut"
+  data={CHANNELS}
+  xKey="channel"
+  xLabel="Channel"
+  series={[{ key: 'orders', label: 'Orders' }]}
+  centerLabel="Orders"
+  headingLevel={4}
+/>
+```
+
+### Radar, two series
+
+```tsx
+type Profile = { measure: string; m4: number; ak: number }
+
+const PROFILES: Profile[] = [
+  { measure: 'Range', m4: 78, ak: 64 },
+  { measure: 'Accuracy', m4: 82, ak: 70 },
+  { measure: 'Rate of fire', m4: 74, ak: 86 },
+  { measure: 'Weight', m4: 58, ak: 44 },
+  { measure: 'Reliability', m4: 70, ak: 90 },
+  { measure: 'Upgrades', m4: 92, ak: 62 },
+]
+
+<ChartPanel<Profile>
+  title="Replica profiles"
+  summary="The M4 replica leads on range, accuracy and upgrades; the AK replica on rate of fire and reliability."
+  kind="radar"
+  data={PROFILES}
+  xKey="measure"
+  xLabel="Measure"
+  series={[
+    { key: 'm4', label: 'M4 replica' },
+    { key: 'ak', label: 'AK replica' },
+  ]}
+  headingLevel={4}
+/>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Skips the chart, which isn't a tab stop (a place the Tab key lands), and goes to Show as table. |
+| `Enter` `Space` | On Show as table, shows or hides the table. |
+
+## Do
+
+- Write the summary as the finding. Don't just describe the axes.
+- Use a line for change over time and bars to compare categories.
+- Keep to two series. Give a third its own panel.
+- In print or greyscale, you can rely on the second line series being dashed. It doesn't depend on colour alone.
+- Use size sm with a headline for a stat card. The caption and the table stay.
+- Use bands for context such as night hours or a sale, and give each one a label.
+- Past six slices, fold a donut's smallest slices into one Other row.
+
+## Don't
+
+- Don't give a chart two y-axes. Two measures means two panels.
+- Don't colour a series with a status colour. Those colours mean state.
+- Don't put a number on every point. The table has them all.
+- Don't use a donut to compare categories over time. That's a job for a line or bars.
+
+## Anatomy
+
+- **Title**: The panel's heading. It's also the accessible name, the name a screen reader announces for the panel.
+- **Summary**: One sentence that works as the chart's caption: what a reader should take away.
+- **Legend**: Names both series when there are two. With one series, the title names it. A donut lists every slice with its value and share.
+- **Headline**: Optional. The figure the chart is about, printed large under the title.
+- **Chart**: A line, bar, donut or radar chart, with a tooltip that follows the pointer. It's hidden from assistive tech (screen readers and similar tools), which get the table instead.
+- **Centre total**: Donut only. The sum of the slices, with centerLabel under it.
+- **Shaded ranges**: Optional, line and bar only. A quiet wash behind the chart for each band, listed under it with its label and range.
+- **Show as table**: A button that opens and closes a DataTable with the same rows. It uses aria-expanded, an ARIA (Accessible Rich Internet Applications) attribute that tells screen readers whether it's open.