@colixsystems/widget-sdk 0.246.0 → 0.247.0

package/README.md

@@ -84,7 +84,26 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.246.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.247.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.247.0 (contract 1.201.0)
+
+**`<Grid>` lays out card grids, tile rows and calendar-style cells for you.** It measures its own unpadded box and balances the lines, so there is no lone card under a full row, no fifth stat tile running off the edge, and no 200px calendar day. `<Grid minCellWidth={240}>{items.map((item) => <Card key={item.id} style={{ flex: 1 }}>…</Card>)}</Grid>` fills every line but the last and pads that one so its cards line up; `<Grid balance="tiles">` spreads tiles evenly; `<Grid columns={7} cell={{ min: 32, max: 64 }} square gap="xs">` draws a month of square days capped at 64px and centred (a block wider than the space starts at the leading edge). Every cell stays mounted as lines change, so a cell keeps its state across a resize. Layouts it cannot express (masonry, spanning cells) can still be laid out by hand with `useContainerWidth()`.
+
+**A themed chart: `<Chart>` and Design > Components > Charts.** `<Chart type data />` draws a bar (default), horizontal bar (`hbar`), line, area, donut or sparkline chart whose series colours, axis and gridline colours and bar corners come from the new `chart` theme scope; colours left unset follow the theme, primary first. It measures its own width, holds its place with a `Skeleton` while `loading`, shows an `EmptyState` when there is nothing to plot, adds a legend for a donut or several `series`, thins crowded labels, groups numbers for the app's language, and reads to a screen reader as one image with a summary and the values (`accessibilityLabel` replaces the summary, `moreText` translates its tail). `valueFormat="percent"` expects values already in percent. A chart type it does not draw (a scatter plot, a timeline) is still yours to draw with `react-native-svg`, in the same colours through `chartColors(theme)`.
+
+```jsx
+const { groups, loading } = useDatastoreAggregate(tableId, { groupBy: "city", sumColumn: "visits", order: "sum:desc", limit: 10 });
+<Chart type="bar" loading={loading} valueFormat="compact"
+  data={groups.map((g) => ({ label: String(g.group), value: Number(g.sum) || 0 }))} />
+```
+
+**Searchable pickers: `<Select searchable>` and `<PeoplePicker>`.** A long `Select` can be searched: pass `searchable` to filter the options you hold, `onSearch` to fetch each query yourself (called with "" when the sheet opens and again once typing pauses), or an async `options` function and Select fetches, keeping only the latest answer. `<PeoplePicker source="users" | "groups" | "records">` does this for the workspace's people, groups or a table's records with avatar rows, server-side search and `excludeIds`, and names a saved choice that is not on the first page instead of showing its id (a malformed saved id reads "Unknown" without failing the rest). `useGroups({ ids })` names groups by id.
+
+```jsx
+<PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />
+<PeoplePicker source="groups" multiple label="Teams" values={teams} onValuesChange={setTeams} />
+```
 
 ### What's new in 0.246.0 (contract 1.200.0)
 
@@ -3067,14 +3086,17 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `isSafeMarkdownImageSrc`, `isHttpImageSrc`, `normaliseMarkdownImageSize`, `readMarkdownAlt` — the image half of that grammar, for a widget rendering images itself via `renderImage`. `isSafeMarkdownImageSrc` is the same allowlist the parser applies (an `http(s)` URL or a filestore id; a `javascript:` scheme is refused), so the widget and the parser cannot disagree about which src is renderable.
 - `List`, `ListRow`, `ListHeader`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<ListHeader>` labels a table's columns on the rows' own inset; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row or a header row from `View` + `Pressable`.
 - `Badge`, `Avatar`, `Progress`, `Stat`, `Divider` — the themed status pill, person picture, completion bar or ring, headline figure and rule the built-in widgets of the same names render through. Reach for them inside a record row instead of hand-rolling a pill or a circle from `View`.
+- `Grid` — balanced lines of cells sized from the grid's own measured width, on both hosts. `<Grid minCellWidth gap balance>`: `balance` `"cards"` (default) fits as many cells to a line as `minCellWidth` allows (240 when unset), fills every line but the last and pads that one with empty cells; `"tiles"` spreads the remainder and stretches each line (5 at 4 per line are 3 + 2), with `maxColumns` or the width tier (4 / 3 / 2) as the ceiling. `columns` fixes the count per line; `cell={{ min, max }}` with `square` makes definite-size cells (calendar days, seats, swatches) in a centred block. It measures an inner box with no padding, and `gap` is a theme spacing name or a number. Each child keeps its own look, and a child with `flex: 1` fills its cell's height. Use it by default for card grids, tile rows and capped cells; masonry or spanning cells are yours to lay out with `useContainerWidth()`.
 - `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Design > Components (Cards, Buttons, Inputs); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
 - `Banner` — the themed inline message. `<Banner tone message>` shows an error, warning, success or notice in place, styled by the theme's `alert` scope; `action` adds one button and `onDismiss` a close control. Use `useToast()` for a brief confirmation instead. Never hand-roll a tinted error box.
 - `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
 - `Checkbox`, `Switch`, `Select`, `SearchField` — the themed tick box, on/off toggle, picker and search box. Like `TextField` they follow the theme's `muted` scope, Design > Components > Inputs (and `popover`, Dropdown menus, for the Select's option sheet; `SearchField` also reads `search`, Search fields, for its glyph position, corner radius, background, border colour and height, each falling back to Inputs) and take `label`, `helper`, `error` and `disabled`. `Select` opens its options at screen level; with `multiple` it takes `values` / `onValuesChange`, ticks options in the same sheet and commits them on Done. Never hand-roll one from `Pressable` and `View`.
 - `RadioGroup` — the themed pick-ONE of a short list that stays on screen. `<RadioGroup options value onValueChange variant>` with `variant` `"list"` (default) or `"card"`, both following `muted` (Design > Components > Inputs), or `"segmented"`, the `tabs` scope's segmented strip; options are `{ value, label, description, icon, disabled, testID }`, and it takes `label`, `helper`, `error` and `disabled`. Radio role and checked state on both hosts; on the web one tab stop, arrows move the choice. Use it by default for two to about six visible options; a long list is a `Select`, and a choice it cannot draw (a picture or a swatch per option) is yours to build, with the radio role.
+- `PeoplePicker` — the themed pick of a workspace user, a group or a table's record. `<PeoplePicker source value onValueChange>` (`source` `"users"` (default), `"groups"` or `"records"` with `table`) is a searchable `Select`: it reads `useDirectory`, `useGroups` or `useDatastoreQuery`, searches on the server once typing pauses, leads each row with an `Avatar`, leaves out `excludeIds`, and looks up a saved value outside the first page once by id so the field names it, never showing the id. A `Select` of your own options turns searchable with `searchable` (filters what you pass), `onSearch(query)` with `loading`, or an async `options(query)`; `selectedOptions` names saved values the page does not hold.
 - `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.
 - `Chip`, `ChipGroup` — the themed filter chip, tag or pill. `<Chip label selected onPress onRemove disabled>` follows the theme's `chip` scope; `<ChipGroup>` spaces and wraps its chips and, with `selection="single"`, announces them as one choice. Never hand-roll a chip from `Pressable` + a pill radius.
+- `Chart` — the themed chart, drawn with `react-native-svg` on both hosts. `<Chart type data series valueFormat height loading>` with `type` `"bar"` (default), `"hbar"`, `"line"`, `"area"`, `"donut"` or `"sparkline"`; `data` is `[{ label, value }]`, or one number per `series` key. It measures its own width, shows a `Skeleton` while `loading` and an `EmptyState` with no data, draws a legend for a donut or several series, and is one image to a screen reader, labelled with a summary and the values. Its series colours, axis and gridline colours and bar corners follow the theme's `chart` scope (Design > Components > Charts), falling back to the theme's colours. Use it by default, fed by `useDatastoreAggregate`; a chart it does not draw (a scatter plot, a timeline) is yours to draw with `react-native-svg`.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 
@@ -3104,7 +3126,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
-- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a count or size computed from the width (a calendar day, a chart, a card grid's cards per line), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers** (sc-8508): `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead — but a card grid or a tile row is never capped. **A card grid fills its lines, it never wraps freely** — a free `flexWrap` strands the remainder (six cards that fit five render 5 + 1). Count the cards that fit the measured width (`const max = Math.max(1, Math.floor((width + gap) / (CARD_MIN + gap)));`), take `const lines = Math.ceil(count / max); const cols = Math.ceil(count / lines);`, and render each slice of `cols` cards as a row of `{ flex: 1, minWidth: 0 }` cells, padding the last line with empty `{ flex: 1 }` spacers so its cards keep the width of the cards above (six that fit five are 3 + 3, ten that fit four are 4 + 4 + 2). **A short value never breaks across lines** — a time, date, price, count, percentage or code takes `numberOfLines={1}` and `flexShrink: 0`, never a fixed width narrower than it, and a narrow slot re-arranges or steps the font down instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
+- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a count or size computed from the width (a calendar day, a chart, a card grid's cards per line), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers** (sc-8508): `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead — but a card grid or a tile row is never capped. **Lay out a card grid, a tile row or a grid of capped cells with `<Grid>` by default** — it measures its own unpadded box and applies the rules below; lay one out yourself when it needs what `<Grid>` cannot express, such as masonry or cells that span lines. **A card grid fills its lines, it never wraps freely** — a free `flexWrap` strands the remainder (six cards that fit five render 5 + 1). Count the cards that fit the measured width (`const max = Math.max(1, Math.floor((width + gap) / (CARD_MIN + gap)));`), take `const lines = Math.ceil(count / max); const cols = Math.ceil(count / lines);`, and render each slice of `cols` cards as a row of `{ flex: 1, minWidth: 0 }` cells, padding the last line with empty `{ flex: 1 }` spacers so its cards keep the width of the cards above (six that fit five are 3 + 3, ten that fit four are 4 + 4 + 2). **A short value never breaks across lines** — a time, date, price, count, percentage or code takes `numberOfLines={1}` and `flexShrink: 0`, never a fixed width narrower than it, and a narrow slot re-arranges or steps the font down instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
 - **Compose forms — pair fields into rows, don't stack one per row.** Lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. A search box is `<SearchField>`, which already carries its glyph and clear control. Put any other icon or unit beside the field as a sibling in a row (`flex: 1, minWidth: 0` on the field, so a long value shrinks instead of pushing the row past its container) rather than rebuilding the field to hold it: a hand-built bordered wrapper around a bare `TextInput` loses the app's input look and its label, focus and error handling.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.

package/dist/chart-logic.js

@@ -0,0 +1,575 @@
+// The geometry `<Chart>` draws, as plain numbers and SVG path strings. No
+// React and no renderer, so both hosts draw the same marks and node tests
+// can pin them.
+
+export const CHART_TYPES = Object.freeze(["bar", "hbar", "line", "area", "donut", "sparkline"]);
+export const DEFAULT_CHART_TYPE = "bar";
+export const DEFAULT_CHART_HEIGHT = 220;
+export const DEFAULT_SPARKLINE_HEIGHT = 48;
+export const VALUE_FORMATS = Object.freeze(["number", "compact", "percent"]);
+
+// The single series a chart draws when the caller names none.
+export const DEFAULT_SERIES_KEY = "value";
+// A screen reader hears at most this many values, over all series.
+export const SPOKEN_VALUES_MAX = 24;
+/** The tail of a cut-short spoken list, until a widget passes `moreText`. */
+export const DEFAULT_MORE_TEXT = (count) => `and ${count} more`;
+
+const TYPE_NAMES = Object.freeze({
+  bar: "Bar chart",
+  hbar: "Horizontal bar chart",
+  line: "Line chart",
+  area: "Area chart",
+  donut: "Donut chart",
+  sparkline: "Sparkline",
+});
+
+// Average glyph width as a share of the font size, for fitting labels.
+const GLYPH_WIDTH = 0.58;
+const TICK_COUNT = 4;
+// A crowded axis keeps every n-th label once labels would shrink below this.
+const LABEL_MIN_CHARS = 6;
+const TICK_GAP = 6;
+const GROUP_SHARE = 0.72;
+const BAR_MAX_WIDTH = 48;
+const BAR_MIN_WIDTH = 2;
+const DONUT_HOLE = 0.62;
+const DOTS_MAX_POINTS = 24;
+const HBAR_LABEL_SHARE = 0.38;
+const HBAR_ROW_SHARE = 0.7;
+// A horizontal bar's label needs its line height; crowded rows label every n-th.
+const HBAR_LABEL_GAP = 4;
+
+export function normaliseChartType(type) {
+  return CHART_TYPES.includes(type) ? type : DEFAULT_CHART_TYPE;
+}
+
+/** The plot's height: a positive number, else the type's own default. */
+export function chartHeight(type, height) {
+  if (typeof height === "number" && Number.isFinite(height) && height > 0) return height;
+  return type === "sparkline" ? DEFAULT_SPARKLINE_HEIGHT : DEFAULT_CHART_HEIGHT;
+}
+
+function labelText(value) {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "object" && typeof value.label === "string") return value.label;
+  return String(value);
+}
+
+function numberOrNull(value) {
+  if (value === null || value === undefined || value === "") return null;
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Turn `data` (and the optional `series`) into the labels and the value rows
+ * every chart type reads. Without `series` each item is `{ label, value }`;
+ * with it, each item carries one number per series key.
+ *
+ * @returns {{ labels: string[], series: Array<{ key: string, label: string, color?: string, values: Array<number|null> }> }}
+ */
+export function normaliseChartData(data, series) {
+  const rows = Array.isArray(data) ? data.filter((row) => row && typeof row === "object") : [];
+  const declared = Array.isArray(series)
+    ? series.filter((s) => s && typeof s === "object" && typeof s.key === "string" && s.key)
+    : [];
+  const lines = declared.length
+    ? declared.map((s) => ({
+        key: s.key,
+        label: labelText(s.label ?? s.key),
+        color: typeof s.color === "string" && s.color ? s.color : undefined,
+      }))
+    : [{ key: DEFAULT_SERIES_KEY, label: "", color: undefined }];
+  return {
+    labels: rows.map((row) => labelText(row.label)),
+    series: lines.map((line) => ({ ...line, values: rows.map((row) => numberOrNull(row[line.key])) })),
+  };
+}
+
+/** The values a donut draws: the first series, positive values only. */
+function donutValues(model) {
+  const first = model.series[0];
+  return first ? first.values.map((v) => (v !== null && v > 0 ? v : 0)) : [];
+}
+
+/** True when there is nothing to plot, so the chart shows its empty state. */
+export function isChartEmpty(model, type) {
+  if (!model || model.labels.length === 0) return true;
+  if (type === "donut") return donutValues(model).reduce((sum, v) => sum + v, 0) <= 0;
+  return !model.series.some((s) => s.values.some((v) => v !== null));
+}
+
+// `locale` is the app's language; an unknown one falls back to the device's.
+function localNumber(value, digits, locale) {
+  try {
+    return value.toLocaleString(locale, { maximumFractionDigits: digits });
+  } catch {
+    return String(Number(value.toFixed(digits)));
+  }
+}
+
+function compactNumber(value, locale) {
+  const abs = Math.abs(value);
+  for (const [size, suffix] of [
+    [1e12, "T"],
+    [1e9, "B"],
+    [1e6, "M"],
+    [1e3, "k"],
+  ]) {
+    if (abs >= size) return `${localNumber(value / size, abs / size < 10 ? 1 : 0, locale)}${suffix}`;
+  }
+  return localNumber(value, abs < 10 ? 2 : 1, locale);
+}
+
+/**
+ * One value as text. `format` is a function of the number, or `"number"`
+ * (default, grouped), `"compact"` (1.2k, 3M) or `"percent"`, which appends a
+ * percent sign to a value that is already a percentage (42 reads "42%"; it
+ * never multiplies by 100). Digits are grouped for `locale`, the app's language.
+ */
+export function formatChartValue(value, format, locale) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "";
+  if (typeof format === "function") {
+    try {
+      return String(format(value));
+    } catch {
+      return localNumber(value, 2, locale);
+    }
+  }
+  if (format === "compact") return compactNumber(value, locale);
+  if (format === "percent") return `${localNumber(value, 2, locale)}%`;
+  return localNumber(value, 2, locale);
+}
+
+/** An axis tick as text: compact unless the caller formats values itself. */
+export function formatChartTick(value, format, locale) {
+  if (typeof format === "function" || format === "percent") return formatChartValue(value, format, locale);
+  return compactNumber(value, locale);
+}
+
+function niceStep(raw) {
+  const power = 10 ** Math.floor(Math.log10(raw));
+  const fraction = raw / power;
+  const nice = fraction < 1.5 ? 1 : fraction < 3 ? 2 : fraction < 7 ? 5 : 10;
+  return nice * power;
+}
+
+function cleanFloat(value) {
+  return Number(value.toPrecision(12));
+}
+
+/**
+ * Round a value range out to "nice" tick values (0, 25, 50 …).
+ *
+ * @returns {{ min: number, max: number, ticks: number[] }}
+ */
+export function niceTicks(min, max, count = TICK_COUNT) {
+  let low = Number.isFinite(min) ? min : 0;
+  let high = Number.isFinite(max) ? max : 0;
+  if (low > high) [low, high] = [high, low];
+  if (low === high) {
+    if (low === 0) high = 1;
+    else if (low > 0) low = 0;
+    else high = 0;
+  }
+  const step = niceStep((high - low) / Math.max(1, count));
+  const niceMin = cleanFloat(Math.floor(low / step) * step);
+  const niceMax = cleanFloat(Math.ceil(high / step) * step);
+  const ticks = [];
+  for (let tick = niceMin; tick <= niceMax + step / 2; tick += step) ticks.push(cleanFloat(tick));
+  return { min: niceMin, max: niceMax, ticks };
+}
+
+/** Map `[d0, d1]` onto `[r0, r1]`; a zero-width domain maps to the middle. */
+export function linearScale(d0, d1, r0, r1) {
+  const span = d1 - d0;
+  if (!span) return () => (r0 + r1) / 2;
+  return (value) => r0 + ((value - d0) / span) * (r1 - r0);
+}
+
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+
+/**
+ * A line through the points, broken where a point is null (a missing value).
+ *
+ * @param {Array<{x:number,y:number}|null>} points
+ */
+export function linePath(points) {
+  let d = "";
+  let pen = false;
+  for (const point of points) {
+    if (!point) {
+      pen = false;
+      continue;
+    }
+    d += `${d ? " " : ""}${pen ? "L" : "M"} ${round(point.x)} ${round(point.y)}`;
+    pen = true;
+  }
+  return d;
+}
+
+/** The area under each unbroken run of points, closed down to `baseY`. */
+export function areaPath(points, baseY) {
+  const runs = [];
+  let run = [];
+  for (const point of points) {
+    if (point) run.push(point);
+    else if (run.length) {
+      runs.push(run);
+      run = [];
+    }
+  }
+  if (run.length) runs.push(run);
+  return runs
+    .map((part) => {
+      const first = part[0];
+      const last = part[part.length - 1];
+      const top = part.map((p) => `L ${round(p.x)} ${round(p.y)}`).join(" ");
+      return `M ${round(first.x)} ${round(baseY)} ${top} L ${round(last.x)} ${round(baseY)} Z`;
+    })
+    .join(" ");
+}
+
+/**
+ * A bar rounded only at its far end (`edge`: "top" | "bottom" | "right" |
+ * "left"), so it stands square on its baseline.
+ */
+export function barPath({ x, y, width, height }, radius, edge = "top") {
+  const across = edge === "top" || edge === "bottom" ? width : height;
+  const along = edge === "top" || edge === "bottom" ? height : width;
+  const r = Math.max(0, Math.min(radius || 0, across / 2, along));
+  const [x0, y0, x1, y1] = [x, y, x + width, y + height].map(round);
+  if (r <= 0) return `M ${x0} ${y0} L ${x1} ${y0} L ${x1} ${y1} L ${x0} ${y1} Z`;
+  const q = round(r);
+  const arc = (tx, ty) => `A ${q} ${q} 0 0 1 ${round(tx)} ${round(ty)}`;
+  if (edge === "top") {
+    return `M ${x0} ${y1} L ${x0} ${round(y + r)} ${arc(x + r, y)} L ${round(x + width - r)} ${y0} ${arc(x + width, y + r)} L ${x1} ${y1} Z`;
+  }
+  if (edge === "bottom") {
+    return `M ${x1} ${y0} L ${x1} ${round(y + height - r)} ${arc(x + width - r, y + height)} L ${round(x + r)} ${y1} ${arc(x, y + height - r)} L ${x0} ${y0} Z`;
+  }
+  if (edge === "right") {
+    return `M ${x0} ${y0} L ${round(x + width - r)} ${y0} ${arc(x + width, y + r)} L ${x1} ${round(y + height - r)} ${arc(x + width - r, y + height)} L ${x0} ${y1} Z`;
+  }
+  return `M ${x1} ${y1} L ${round(x + r)} ${y1} ${arc(x, y + height - r)} L ${x0} ${round(y + r)} ${arc(x + r, y)} L ${x1} ${y0} Z`;
+}
+
+function polar(cx, cy, r, angle) {
+  return { x: cx + r * Math.cos(angle), y: cy + r * Math.sin(angle) };
+}
+
+function circlePath(cx, cy, r, sweep) {
+  const top = `${round(cx)} ${round(cy - r)}`;
+  const bottom = `${round(cx)} ${round(cy + r)}`;
+  const q = round(r);
+  return `M ${top} A ${q} ${q} 0 1 ${sweep} ${bottom} A ${q} ${q} 0 1 ${sweep} ${top} Z`;
+}
+
+/** One ring segment from `start` to `end` (radians, 0 = 3 o'clock, clockwise). */
+export function ringSlicePath(cx, cy, outer, inner, start, end) {
+  if (end - start >= Math.PI * 2 - 1e-6) {
+    // A whole ring: the hole is cut out by the opposite winding.
+    return `${circlePath(cx, cy, outer, 1)} ${inner > 0 ? circlePath(cx, cy, inner, 0) : ""}`.trim();
+  }
+  const large = end - start > Math.PI ? 1 : 0;
+  const a = polar(cx, cy, outer, start);
+  const b = polar(cx, cy, outer, end);
+  const c = polar(cx, cy, inner, end);
+  const d = polar(cx, cy, inner, start);
+  const o = round(outer);
+  const i = round(inner);
+  return (
+    `M ${round(a.x)} ${round(a.y)} A ${o} ${o} 0 ${large} 1 ${round(b.x)} ${round(b.y)} ` +
+    `L ${round(c.x)} ${round(c.y)} A ${i} ${i} 0 ${large} 0 ${round(d.x)} ${round(d.y)} Z`
+  );
+}
+
+function estimateWidth(text, fontSize) {
+  return String(text).length * fontSize * GLYPH_WIDTH;
+}
+
+/** Shorten a label to fit `maxWidth`, ending it with an ellipsis. */
+export function fitLabel(text, maxWidth, fontSize) {
+  const value = String(text);
+  if (estimateWidth(value, fontSize) <= maxWidth) return value;
+  const chars = Math.max(1, Math.floor(maxWidth / (fontSize * GLYPH_WIDTH)) - 1);
+  return `${value.slice(0, chars)}…`;
+}
+
+function valueExtent(model) {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const s of model.series) {
+    for (const v of s.values) {
+      if (v === null) continue;
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+  }
+  return Number.isFinite(min) ? { min, max } : { min: 0, max: 0 };
+}
+
+// Bars and areas stand on zero; a line or sparkline shows its own range.
+function valueDomain(model, type) {
+  const { min, max } = valueExtent(model);
+  if (type === "line" || type === "sparkline") return { min, max };
+  return { min: Math.min(0, min), max: Math.max(0, max) };
+}
+
+// A bar's thickness: its share of the group, at least a hairline, never past its slot.
+function barThickness(groupSize, groups, slot) {
+  return Math.min(Math.max(BAR_MIN_WIDTH, groupSize / groups), slot / groups);
+}
+
+// Every n-th category label, so neighbouring labels never overlap.
+function labelStride(labels, slot, fontSize) {
+  const longest = labels.reduce((m, l) => Math.max(m, Math.min(String(l).length, LABEL_MIN_CHARS)), 1);
+  const needed = longest * fontSize * GLYPH_WIDTH + TICK_GAP;
+  return Math.max(1, Math.ceil(needed / Math.max(1, slot)));
+}
+
+function pointsFor(values, xAt, scale) {
+  return values.map((v, i) => (v === null ? null : { x: xAt(i), y: scale(v) }));
+}
+
+function verticalLayout({ type, width, height, model, fontSize, valueFormat, locale }) {
+  const sparkline = type === "sparkline";
+  const domain = valueDomain(model, type);
+  const nice = sparkline ? { ...domain, ticks: [] } : niceTicks(domain.min, domain.max);
+  const tickTexts = nice.ticks.map((t) => formatChartTick(t, valueFormat, locale));
+  const stroke = sparkline ? 2 : 0;
+  const left = sparkline ? stroke : Math.ceil(tickTexts.reduce((m, t) => Math.max(m, estimateWidth(t, fontSize)), 0)) + TICK_GAP;
+  const right = sparkline ? stroke : Math.ceil(fontSize / 2);
+  const top = sparkline ? stroke : Math.ceil(fontSize / 2) + 1;
+  const bottom = sparkline ? stroke : fontSize + TICK_GAP + 2;
+  const plotW = Math.max(1, width - left - right);
+  const plotH = Math.max(1, height - top - bottom);
+  const scale = linearScale(nice.min, nice.max, top + plotH, top);
+  const baseY = scale(Math.min(Math.max(0, nice.min), nice.max));
+  const count = model.labels.length;
+
+  const out = {
+    plot: { left, top, width: plotW, height: plotH },
+    gridLines: nice.ticks.map((t) => ({ x1: left, x2: left + plotW, y: round(scale(t)) })),
+    tickLabels: nice.ticks.map((t, i) => ({ x: left - TICK_GAP, y: round(scale(t) + fontSize / 3), text: tickTexts[i], anchor: "end" })),
+    baseline: sparkline ? null : { x1: left, x2: left + plotW, y: round(baseY) },
+    categoryLabels: [],
+    bars: [],
+    lines: [],
+    areas: [],
+    dots: [],
+  };
+
+  if (type === "bar") {
+    const slot = plotW / Math.max(1, count);
+    const groups = model.series.length;
+    const groupW = Math.min(slot * GROUP_SHARE, BAR_MAX_WIDTH * groups);
+    const barW = barThickness(groupW, groups, slot);
+    model.series.forEach((s, si) => {
+      s.values.forEach((v, i) => {
+        if (v === null) return;
+        const x = left + i * slot + (slot - barW * groups) / 2 + si * barW;
+        const y = scale(v);
+        const up = y <= baseY;
+        out.bars.push({
+          seriesIndex: si,
+          index: i,
+          rect: { x, y: up ? y : baseY, width: barW, height: Math.abs(baseY - y) },
+          edge: up ? "top" : "bottom",
+        });
+      });
+    });
+    const stride = labelStride(model.labels, slot, fontSize);
+    model.labels.forEach((label, i) => {
+      if (i % stride) return;
+      out.categoryLabels.push({
+        x: round(left + i * slot + slot / 2),
+        y: round(top + plotH + TICK_GAP + fontSize * 0.8),
+        text: fitLabel(label, slot * stride - TICK_GAP, fontSize),
+        anchor: "middle",
+      });
+    });
+    return out;
+  }
+
+  const xAt = count > 1 ? (i) => left + (i * plotW) / (count - 1) : () => left + plotW / 2;
+  model.series.forEach((s, si) => {
+    const points = pointsFor(s.values, xAt, scale);
+    out.lines.push({ seriesIndex: si, d: linePath(points) });
+    if (type === "area") out.areas.push({ seriesIndex: si, d: areaPath(points, baseY) });
+    if (sparkline) {
+      const last = [...points].reverse().find(Boolean);
+      if (last) out.dots.push({ seriesIndex: si, cx: round(last.x), cy: round(last.y) });
+    } else if (count <= DOTS_MAX_POINTS) {
+      points.forEach((p) => p && out.dots.push({ seriesIndex: si, cx: round(p.x), cy: round(p.y) }));
+    }
+  });
+  if (!sparkline) {
+    const slot = count > 1 ? plotW / (count - 1) : plotW;
+    const stride = labelStride(model.labels, slot, fontSize);
+    model.labels.forEach((label, i) => {
+      if (i % stride) return;
+      const first = i === 0 && count > 1;
+      const last = i === count - 1 && count > 1;
+      out.categoryLabels.push({
+        x: round(xAt(i)),
+        y: round(top + plotH + TICK_GAP + fontSize * 0.8),
+        text: fitLabel(label, Math.max(slot * stride - TICK_GAP, fontSize * 3), fontSize),
+        anchor: first ? "start" : last ? "end" : "middle",
+      });
+    });
+  }
+  return out;
+}
+
+function horizontalLayout({ width, height, model, fontSize, valueFormat, locale }) {
+  const domain = valueDomain(model, "hbar");
+  const nice = niceTicks(domain.min, domain.max);
+  const count = model.labels.length;
+  const longest = model.labels.reduce((m, l) => Math.max(m, estimateWidth(l, fontSize)), 0);
+  const left = Math.ceil(Math.min(longest, width * HBAR_LABEL_SHARE)) + TICK_GAP;
+  const lastTick = formatChartTick(nice.ticks[nice.ticks.length - 1], valueFormat, locale);
+  const right = Math.ceil(estimateWidth(lastTick, fontSize) / 2) + 2;
+  const top = 2;
+  const bottom = fontSize + TICK_GAP + 2;
+  const plotW = Math.max(1, width - left - right);
+  const plotH = Math.max(1, height - top - bottom);
+  const scale = linearScale(nice.min, nice.max, left, left + plotW);
+  const baseX = scale(Math.min(Math.max(0, nice.min), nice.max));
+  const slot = plotH / Math.max(1, count);
+  const groups = model.series.length;
+  const groupH = Math.min(slot * HBAR_ROW_SHARE, BAR_MAX_WIDTH * groups);
+  const barH = barThickness(groupH, groups, slot);
+  // The chart keeps its height, so rows thinner than a line of text label every n-th.
+  const stride = Math.max(1, Math.ceil((fontSize + HBAR_LABEL_GAP) / Math.max(slot, 1e-6)));
+  const out = {
+    plot: { left, top, width: plotW, height: plotH },
+    gridLines: nice.ticks.map((t) => ({ y1: top, y2: top + plotH, x: round(scale(t)) })),
+    tickLabels: nice.ticks.map((t) => ({ x: round(scale(t)), y: round(top + plotH + TICK_GAP + fontSize * 0.8), text: formatChartTick(t, valueFormat, locale), anchor: "middle" })),
+    baseline: { y1: top, y2: top + plotH, x: round(baseX) },
+    categoryLabels: model.labels.flatMap((label, i) =>
+      i % stride
+        ? []
+        : [{ x: left - TICK_GAP, y: round(top + i * slot + slot / 2 + fontSize / 3), text: fitLabel(label, left - TICK_GAP, fontSize), anchor: "end" }],
+    ),
+    bars: [],
+    lines: [],
+    areas: [],
+    dots: [],
+  };
+  model.series.forEach((s, si) => {
+    s.values.forEach((v, i) => {
+      if (v === null) return;
+      const x = scale(v);
+      const forward = x >= baseX;
+      out.bars.push({
+        seriesIndex: si,
+        index: i,
+        rect: { x: forward ? baseX : x, y: top + i * slot + (slot - barH * groups) / 2 + si * barH, width: Math.abs(x - baseX), height: barH },
+        edge: forward ? "right" : "left",
+      });
+    });
+  });
+  return out;
+}
+
+/**
+ * Everything a bar, horizontal bar, line, area or sparkline chart draws, in
+ * the pixel space of a `width` x `height` SVG.
+ */
+export function cartesianLayout({ type, width, height, model, fontSize = 12, valueFormat, locale }) {
+  const kind = normaliseChartType(type);
+  if (kind === "hbar") return horizontalLayout({ width, height, model, fontSize, valueFormat, locale });
+  return verticalLayout({ type: kind, width, height, model, fontSize, valueFormat, locale });
+}
+
+/** The ring segments of a donut, one per positive value of the first series. */
+export function donutLayout({ width, height, model }) {
+  const values = donutValues(model);
+  const total = values.reduce((sum, v) => sum + v, 0);
+  const size = Math.max(0, Math.min(width, height));
+  const cx = width / 2;
+  const cy = height / 2;
+  const outer = size / 2;
+  const inner = outer * DONUT_HOLE;
+  const slices = [];
+  let angle = -Math.PI / 2;
+  values.forEach((v, index) => {
+    if (v <= 0 || total <= 0) return;
+    const sweep = (v / total) * Math.PI * 2;
+    slices.push({ index, d: ringSlicePath(cx, cy, outer, inner, angle, angle + sweep), share: v / total });
+    angle += sweep;
+  });
+  return { cx, cy, outer, inner, total, slices };
+}
+
+function spokenValues(labels, values, { format, locale, moreText, budget }) {
+  const said = [];
+  values.forEach((v, i) => {
+    if (v === null || said.length >= budget) return;
+    said.push(`${labels[i]} ${formatChartValue(v, format, locale)}`.trim());
+  });
+  const shown = values.filter((v) => v !== null).length;
+  const rest = shown - said.length;
+  return rest > 0 ? `${said.join(", ")}, ${moreText(rest)}` : said.join(", ");
+}
+
+function highest(labels, values) {
+  let best = -1;
+  values.forEach((v, i) => {
+    if (v !== null && (best === -1 || v > values[best])) best = i;
+  });
+  return best === -1 ? null : { label: labels[best], value: values[best] };
+}
+
+function plural(count, one, many) {
+  return `${count} ${count === 1 ? one : many}`;
+}
+
+/**
+ * What a screen reader hears: a one-line summary, then the values, at most
+ * `SPOKEN_VALUES_MAX` of them over all series. `lead` replaces the summary (a
+ * widget passes its translated title there) and `moreText(count)` the tail
+ * of a list cut short, so a widget can say both in the app's language.
+ */
+export function chartSummary({ type, model, valueFormat, lead, locale, moreText }) {
+  const kind = normaliseChartType(type);
+  const name = TYPE_NAMES[kind];
+  const labels = model.labels;
+  const tail = typeof moreText === "function" ? moreText : DEFAULT_MORE_TEXT;
+  const say = (values, budget = SPOKEN_VALUES_MAX) =>
+    spokenValues(labels, values, { format: valueFormat, locale, moreText: tail, budget });
+  const value = (v) => formatChartValue(v, valueFormat, locale);
+  if (kind === "donut") {
+    const values = donutValues(model).map((v) => (v > 0 ? v : null));
+    const total = values.reduce((sum, v) => sum + (v || 0), 0);
+    const top = highest(labels, values);
+    const share = top && total > 0 ? Math.round((top.value / total) * 100) : 0;
+    const summary = top
+      ? `${name}, ${plural(values.filter((v) => v !== null).length, "slice", "slices")}, largest: ${top.label} ${value(top.value)} (${share}%)`
+      : name;
+    return `${lead || summary}. ${say(values)}`;
+  }
+  if (model.series.length > 1) {
+    let best = null;
+    for (const s of model.series) {
+      const top = highest(labels, s.values);
+      if (top && (!best || top.value > best.value)) best = { ...top, series: s.label };
+    }
+    const summary = best
+      ? `${name}, ${plural(model.series.length, "series", "series")} of ${plural(labels.length, "value", "values")}, highest: ${best.series}, ${best.label} ${value(best.value)}`
+      : name;
+    const each = Math.max(1, Math.floor(SPOKEN_VALUES_MAX / model.series.length));
+    const spoken = model.series.map((s) => `${s.label}: ${say(s.values, each)}`).join("; ");
+    return `${lead || summary}. ${spoken}`;
+  }
+  const values = model.series[0] ? model.series[0].values : [];
+  const top = highest(labels, values);
+  const summary = top
+    ? `${name}, ${plural(values.filter((v) => v !== null).length, "value", "values")}, highest: ${top.label} ${value(top.value)}`
+    : name;
+  return `${lead || summary}. ${say(values)}`;
+}