@fundar/data-chart-telling 1.0.0 → 1.1.0

package/docs/theming.md

@@ -31,25 +31,26 @@ resetConfiguration(); // back to the shipped defaults
 
 ## Sections
 
-| Key                                                      | Controls                                                                                                                                                         |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `font`, `color`, `background`                            | Base text of every figure                                                                                                                                        |
-| `palette`                                                | Categorical series colors, in order                                                                                                                              |
-| `symbols`                                                | Shape cycle for the `symbol` channel                                                                                                                             |
-| `continuous`                                             | Default ramp endpoints, label color and opacity range for continuous color and opacity                                                                           |
-| `spacing`, `chrome`                                      | Padding around header, legend and caption; the chrome `order` and `rowGap`                                                                                       |
-| `title`, `subtitle`, `caption`                           | Text blocks: `font`, `size`, `weight`, `color`, `leading`, `spacing`                                                                                             |
-| `divider`                                                | The line a `'divider'` in the chrome `order` draws                                                                                                               |
-| `legend`                                                 | Text, gaps, swatches, `disabledOpacity`, paginated nav buttons, the continuous bar, its handles, ticks and labels, and the `seriesTitle` and `sizeScale` options |
-| `axis`                                                   | Axis color, font and tick sizes, `grid`, and the number locale (below)                                                                                           |
-| `tooltip`                                                | Tooltip background, color, font size, padding, radius, border                                                                                                    |
-| `margins`                                                | Default margin per side (`'auto'` or a number)                                                                                                                   |
-| `line`, `area`, `bar`, `pyramid`, `histogram`, `scatter` | Per-kind defaults: stroke width, dot radius, series padding, gap fills, fill opacity, inset                                                                      |
-| `text`                                                   | `declutter` geometry of value labels and connectors                                                                                                              |
-| `hover`                                                  | Look of the hover marker: `rule`, `dot`, `font`, `area`                                                                                                          |
-| `timeline`                                               | The rule (`rule`) and the player bar (`player`: controls, speeds, `stepDuration`, button, track, thumb, toggle)                                                  |
-| `facet`                                                  | The position badge and prev/next buttons                                                                                                                         |
-| `frameClip`                                              | Tolerance for clipping marks to the plot frame                                                                                                                   |
+| Key                                                             | Controls                                                                                                                                                                                                                                                                                  |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `font`, `color`, `background`                                   | Base text of every figure                                                                                                                                                                                                                                                                 |
+| `palette`                                                       | Categorical series colors, in order                                                                                                                                                                                                                                                       |
+| `symbols`                                                       | Shape cycle for the `symbol` channel                                                                                                                                                                                                                                                      |
+| `continuous`                                                    | Default ramp endpoints, label color and opacity range for continuous color and opacity                                                                                                                                                                                                    |
+| `spacing`, `chrome`                                             | Padding around header, legend and caption; the chrome `order` and `rowGap`                                                                                                                                                                                                                |
+| `title`, `subtitle`, `caption`                                  | Text blocks: `font`, `size`, `weight`, `color`, `leading`, `spacing`                                                                                                                                                                                                                      |
+| `divider`                                                       | The line a `'divider'` in the chrome `order` draws                                                                                                                                                                                                                                        |
+| `legend`                                                        | Text, gaps, swatches, `disabledOpacity`, paginated nav buttons, the continuous bar, its handles, ticks and labels, and the `seriesTitle` and `sizeScale` options                                                                                                                          |
+| `axis`                                                          | Axis color, font and tick sizes, `grid`, and the number locale (below)                                                                                                                                                                                                                    |
+| `tooltip`                                                       | Tooltip background, color, font size, padding, radius, border                                                                                                                                                                                                                             |
+| `margins`                                                       | Default margin per side (`'auto'` or a number)                                                                                                                                                                                                                                            |
+| `line`, `area`, `bar`, `pyramid`, `histogram`, `box`, `scatter` | Per-kind defaults: stroke width, dot radius, series padding, gap fills, fill opacity, inset, box padding                                                                                                                                                                                  |
+| `text`                                                          | `declutter` geometry of value labels and connectors                                                                                                                                                                                                                                       |
+| `hover`                                                         | Look of the hover marker: `rule`, `dot`, `font`, `area`                                                                                                                                                                                                                                   |
+| `delta`                                                         | The `delta` marker's label, per axis the delta is taken on: `text.x` (beside a vertical delta: `dx: 12`, `textAnchor: 'start'`) and `text.y` (above a horizontal one: `dy: -10`, `textAnchor: 'middle'`). `lineAnchor` picks where along the delta the label sits and how it aligns there |
+| `timeline`                                                      | The rule (`rule`) and the player bar (`player`: controls, speeds, `stepDuration`, button, track, thumb, toggle)                                                                                                                                                                           |
+| `facet`                                                         | The position badge and prev/next buttons                                                                                                                                                                                                                                                  |
+| `frameClip`                                                     | Tolerance for clipping marks to the plot frame                                                                                                                                                                                                                                            |
 
 ## Locale
 
@@ -61,6 +62,16 @@ setConfiguration({ axis: { locale: 'en-US', compactDisplay: 'long' } });
 
 `axis.locale` updates plots already on screen. `axis.compactDisplay` is read when a plot mounts, so a later change shows on the next mount.
 
+## Edge ticks
+
+`axis.edgeTicks.x` and `axis.edgeTicks.y` (`{ enabled, collision }`, on for x and off for y, both `'drop-nice'`) add a tick at the data's first and last values beside the nice ones, on a continuous axis whose other axis is continuous too, so a reader sees where the data starts and ends. When one lands too close to a nice tick for both labels, `collision` picks what gives way: `'drop-nice'` keeps the data's tick, `'drop-edge'` keeps the nice one, `'extend'` widens the axis to the next nice tick past the data.
+
+```ts
+setConfiguration({ axis: { edgeTicks: { x: { enabled: true, collision: 'extend' } } } });
+```
+
+A plot overrides it with `scales.x.edgeTicks` or `scales.y.edgeTicks` (see [Scales](scales.md)).
+
 ## CSS variables
 
 Some fields reach the DOM as CSS custom properties, which every figure sets on its root element and the components read with a fallback. Those can also be overridden with plain CSS on a wrapping element for a one-off, non-reactive tweak:

package/docs/timeline.md

@@ -2,33 +2,50 @@
 
 `timeline` steps a plot through its data by a field - usually a year or a date. Each step shows the rows of one value of that field. It draws as a **player** by default - a control bar with play, pause and a slider - or as a **rule**, a guide beside the plot that the page drives (`type: 'rule'`).
 
+<!-- example: examples/TimelinePlayer.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!--
+	`timeline` slices the rows by `accessor`. A timeline is a player by default:
+	play/pause, the current step and a slider in the chrome. `progress` sets where
+	it starts. `type: 'rule'` draws a guide beside the plot with no controls
+	instead (see TimelineRule). To build your own widget, read
+	`useFigure().timeline` (seek, play, pause, next, ...).
+-->
 <BarPlot
-	{width}
-	{height}
-	data={rows}
+	width={720}
+	height={400}
+	data={REGION_VALUES}
 	x="region"
 	y="value"
-	scales={{ y: { domain: [0, 100] } }}
-	timeline={{ accessor: 'year' }}
+	scales={{ y: { domain: [0, 30] } }}
+	timeline={{ accessor: 'date', progress: 0.25, player: { autoplay: false, loop: true } }}
 />
 ```
 
+<!-- /example -->
+
 ![A bar plot with a player bar](images/timeline-player.png)
 
 ## Options
 
-| Option                             | Meaning                                                                                                                                                                              |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `accessor`                         | Field (or function) giving each row's step - required                                                                                                                                |
-| `type`                             | `'player'` (default) draws a control bar in the chrome; `'rule'` draws a guide with the steps written along it                                                                       |
-| `progress`                         | The position, `0`-`1`. A player keeps its own position from there on, until `progress` changes                                                                                       |
-| `values`                           | The steps, when not every distinct value of `accessor`                                                                                                                               |
-| `filterMode`                       | `'exact'` shows the rows of the current step; `'upTo'` shows every row up to it (a cumulative reveal). `LinePlot` defaults to `'upTo'`                                               |
-| `interpolate`                      | Tween values between steps so a scrub is smooth: `true`, or `{ key, value, create, progressEasing, segmentEasing }`. Line and bar plots default to interpolating their value channel |
-| `scales`                           | `'shared'` (default): axes span every step, so they hold still while scrubbing; `'free'` refits them to each step                                                                    |
-| `onprogress`, `onvalue`            | Called with the new position (`0`-`1`) and with the step it lands on                                                                                                                 |
-| `orientation`, `show`, `thickness` | A rule's direction (`'vertical'` default, beside the plot; `'horizontal'`), visibility and size                                                                                      |
+| Option                             | Meaning                                                                                                                                                                                                                                                                         |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `accessor`                         | Field (or function) giving each row's step - required. A number (a year, a count), a `Date`, or a date string: ISO (`'2023'`, `'2023-05'`, `'2023-05-17'`, with or without a time), or any other read through `dateFormat`. A row whose value reads as none shows at every step |
+| `dateFormat`                       | How a date string that is not ISO reads: the tokens `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, anything else literal (`'DD/MM/YYYY'`, `'MM-YYYY'`). A part it leaves out is the first: January, the 1st, midnight                                                                    |
+| `type`                             | `'player'` (default) draws a control bar in the chrome; `'rule'` draws a guide with the steps written along it                                                                                                                                                                  |
+| `progress`                         | The position, `0`-`1`. A player keeps its own position from there on, until `progress` changes                                                                                                                                                                                  |
+| `values`                           | The steps, when not every distinct value of `accessor` - read like `accessor`'s values                                                                                                                                                                                          |
+| `filterMode`                       | `'exact'` shows the rows of the current step; `'upTo'` shows every row up to it (a cumulative reveal). `LinePlot` defaults to `'upTo'`                                                                                                                                          |
+| `interpolate`                      | Tween values between steps so a scrub is smooth: `true`, or `{ key, value, create, progressEasing, segmentEasing }`. Line and bar plots default to interpolating their value channel                                                                                            |
+| `scales`                           | `'shared'` (default): axes span every step, so they hold still while scrubbing; `'free'` refits them to each step                                                                                                                                                               |
+| `onprogress`, `onvalue`            | Called with the new position (`0`-`1`) and with the step it lands on - a `Date` on a timeline of dates, else the number                                                                                                                                                         |
+| `orientation`, `show`, `thickness` | A rule's direction (`'vertical'` default, beside the plot; `'horizontal'`), visibility and size                                                                                                                                                                                 |
 
 ## Player
 
@@ -52,15 +69,15 @@ The player is a bar in the chrome, below the plot by default, placed like any ot
 />
 ```
 
-| `player` option               | Meaning                                                                                    |
-| ----------------------------- | ------------------------------------------------------------------------------------------ |
-| `controls`                    | The controls drawn, in this order: `'play'`, `'value'`, `'slider'`, `'speed'`, `'loop'`    |
-| `autoplay`                    | Start playing as soon as there are steps                                                   |
-| `loop`, `speed`               | Where the player starts; it keeps them from there and tells `onloop` / `onspeed` on change |
-| `speeds`                      | Speeds the speed control cycles through                                                    |
-| `stepDuration`                | Milliseconds per step at speed `1`                                                         |
-| `format`                      | How the current step reads in the `'value'` control                                        |
-| `onplay`, `onspeed`, `onloop` | Change callbacks                                                                           |
+| `player` option               | Meaning                                                                                                                                                                                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `controls`                    | The controls drawn, in this order: `'play'`, `'value'`, `'slider'`, `'speed'`, `'loop'`                                                                                                                                                                    |
+| `autoplay`                    | Start playing as soon as there are steps                                                                                                                                                                                                                   |
+| `loop`, `speed`               | Where the player starts; it keeps them from there and tells `onloop` / `onspeed` on change                                                                                                                                                                 |
+| `speeds`                      | Speeds the speed control cycles through                                                                                                                                                                                                                    |
+| `stepDuration`                | Milliseconds per step at speed `1`                                                                                                                                                                                                                         |
+| `format`                      | How a step reads, in the `'value'` control and along a rule. It gets a `Date` on a timeline of dates, else the number. Defaults to the step itself; dates read as dates, as precise as the steps need (`2023`, `ene 2023`, `17 ene 2023`) in `axis.locale` |
+| `onplay`, `onspeed`, `onloop` | Change callbacks                                                                                                                                                                                                                                           |
 
 Defaults for `controls`, `speeds` and `stepDuration` come from `timeline.player` in the [configuration](theming.md), together with the bar's colors and sizes.
 
@@ -68,22 +85,39 @@ Defaults for `controls`, `speeds` and `stepDuration` come from `timeline.player`
 
 `type: 'rule'` draws a line with its steps written along it, beside the plot. `progress` picks the step, and the page supplies the control (a slider, a button, scroll position):
 
+<!-- example: examples/TimelineRule.svelte -->
+
 ```svelte
 <script lang="ts">
-	let progress = $state(0);
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+
+	// A rule has no controls of its own: the page moves it through `progress` (0 to 1).
+	// One step per year; a line plot shows every row up to the current step.
+	let progress = $state(0.5);
 </script>
 
 <input type="range" min="0" max="1" step="0.001" bind:value={progress} />
-<LinePlot ... timeline={{ accessor: 'year', type: 'rule', progress }} />
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	timeline={{ accessor: (row) => row.date.getUTCFullYear(), type: 'rule', progress }}
+/>
 ```
 
+<!-- /example -->
+
 ![A line plot revealed up to the current step, with a timeline rule](images/timeline-rule.png)
 
 A rule's look comes from `timeline.rule` in the [configuration](theming.md) (`fontSize`, `activeFontSize`, `axisWidth`, ...) and `--dct-timeline-*` variables.
 
 ## Custom controls
 
-`useFigure().timeline` exposes the timeline's state and actions, to build a widget of your own in place of the player: `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`. See [Reading plot state](state.md).
+`useFigure().timeline` exposes the timeline's state and actions, to build a widget of your own in place of the player: `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`. On a timeline of dates, `steps` and `value` are `Date`s and `seekValue` takes a `Date` or a date string. See [Reading plot state](state.md).
 
 ## One timeline for several plots
 

package/docs/tooltip-and-hover.md

@@ -4,51 +4,99 @@ A plot becomes interactive when it is given a `tooltip`, a `{ type: 'hover' }` m
 
 ## Tooltip
 
+<!-- example: examples/Tooltip.svelte -->
+
 ```svelte
-<LinePlot {width} {height} data={rows} x="year" y="value" color="region" tooltip />
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!--
+	`tooltip` turns the floating box on (`true` for the defaults, or an object
+	to tune it); a `hover` marker draws the in-plot crosshair, dot and label.
+-->
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	tooltip={{ strategy: 'x', format: (row) => `${row.region}: ${row.value}` }}
+	markers={[{ type: 'hover' }]}
+/>
 ```
 
+<!-- /example -->
+
 ![A tooltip and a hover highlight on the hovered point](images/tooltip.png)
 
 `tooltip` is `true` for the defaults, or an options object:
 
-| Option               | Meaning                                                                                                                                                                                       |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `strategy`           | How related points are found: `'x'`, `'y'`, `'punctual'` (the exact point) or `'series'` (all points of the hovered series). Defaults per plot kind                                           |
-| `sync`               | Show the highlight in every synced plot too (default `false`)                                                                                                                                 |
-| `format`             | `(row) => string` - the tooltip text for the hovered row (`\n` breaks lines)                                                                                                                  |
-| `content`            | A snippet `{#snippet content({ rows })}` replacing the text with custom markup. It is drawn in a plain card, so the markup brings its own background, colors and spacing                      |
-| `series`             | Only these series appear in the tooltip                                                                                                                                                       |
-| `anchorX`, `anchorY` | Preferred side of the cursor: `'left' \| 'middle' \| 'right'` (default `'right'`) and `'top' \| 'middle' \| 'bottom'` (default `'bottom'`). It moves to the other side when it would overflow |
+| Option               | Meaning                                                                                                                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strategy`           | How related points are found: `'x'`, `'y'`, `'punctual'` (the exact point) or `'series'` (all points of the hovered series). Defaults per plot kind                                                                                    |
+| `sync`               | Show the highlight in every synced plot too (default `false`)                                                                                                                                                                          |
+| `format`             | `(row) => string` - the tooltip text for the hovered row (`\n` breaks lines). With several rows, they read from the highest value to the lowest (a stacked row by its own value)                                                       |
+| `content`            | A snippet `{#snippet content({ rows })}` replacing the text with custom markup. It gets the rows as the hover matched them, unsorted, and is drawn in a plain card, so the markup brings its own order, background, colors and spacing |
+| `series`             | Only these series appear in the tooltip                                                                                                                                                                                                |
+| `anchorX`, `anchorY` | Preferred side of the cursor: `'left' \| 'middle' \| 'right'` (default `'right'`) and `'top' \| 'middle' \| 'bottom'` (default `'bottom'`). It moves to the other side when it would overflow                                          |
+
+<!-- example: examples/CustomTooltip.svelte -->
 
 ```svelte
-{#snippet content({ rows })}
+<script lang="ts">
+	import { LinePlot, getConfiguration, paletteColor } from '@fundar/data-chart-telling';
+	import TooltipCard from './TooltipCard.svelte';
+	import { REGION_VALUES, type RegionRow } from './data';
+
+	const { palette } = getConfiguration();
+	const regions = [...new Set(REGION_VALUES.map((row) => row.region))];
+</script>
+
+<!--
+	`content` replaces the tooltip text with your own markup, drawn in a plain
+	card: TooltipCard brings its own background, colors and spacing. It is given
+	every row the hover matched, in no particular order, so it sorts them itself;
+	series colors come from the configuration's palette.
+-->
+{#snippet content({ rows }: { rows: RegionRow[] })}
 	<TooltipCard
-		heading={String(rows[0].year)}
-		footer="Value by region"
-		entries={rows.map((row) => ({
-			label: row.region,
-			color: colorOf(row.region),
-			value: row.value,
-			display: String(row.value)
-		}))}
+		heading={rows[0].date.toLocaleDateString('en-US', {
+			month: 'long',
+			year: 'numeric',
+			timeZone: 'UTC'
+		})}
+		footer="Monthly inflation (%)"
+		entries={[...rows]
+			.sort((a, b) => b.value - a.value)
+			.map((row) => ({
+				label: row.region,
+				color: paletteColor(regions.indexOf(row.region), palette),
+				value: row.value,
+				display: String(row.value)
+			}))}
 	/>
 {/snippet}
 
 <LinePlot
-	{width}
-	{height}
-	data={rows}
-	x="year"
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
 	y="value"
 	color="region"
 	tooltip={{ strategy: 'x', content }}
+	markers={[{ type: 'hover' }]}
 />
 ```
 
-![A tooltip with custom markup](images/tooltip-content.png)
+<!-- /example -->
+
+![A tooltip with custom markup](images/custom-tooltip.png)
 
-[examples/CustomTooltip.svelte](../examples/CustomTooltip.svelte) is the runnable version, with the card in [examples/TooltipCard.svelte](../examples/TooltipCard.svelte).
+This is [examples/CustomTooltip.svelte](../examples/CustomTooltip.svelte); the card is [examples/TooltipCard.svelte](../examples/TooltipCard.svelte).
 
 The default strategy follows the plot's axes: it matches along the category (or index) axis - points sharing the hovered `x` when the value axis is vertical, sharing `y` when it is horizontal - and `punctual` (the exact point) on heatmaps and scatter plots.
 

package/docs/transforms-and-statistics.md

@@ -6,33 +6,53 @@ Both derive rows from the data before drawing. A **transform** reshapes the rows
 
 `transforms` is an array of flat objects: `type` picks the transform and the other fields are its channels and options, named as in [svelteplot's transforms](https://svelteplot.dev). It exists on a plot (it then runs once over all the plot's series) and on each [marker](markers.md) (over the marker's rows).
 
+<!-- example: examples/StackedBars.svelte -->
+
 ```svelte
-<!-- stacked bars -->
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { SEX_SHARES } from './data';
+</script>
+
+<!-- Each sex's share of the population per census, stacked with `stackY` so a bar adds up to 100%. -->
 <BarPlot
-	{width}
-	{height}
-	data={rows}
-	x="province"
-	y="value"
+	width={720}
+	height={400}
+	data={SEX_SHARES}
+	x="year"
+	y="share"
 	color="sex"
 	transforms={[{ type: 'stackY' }]}
 />
+```
+
+<!-- /example -->
+
+![Stacked bars](images/stacked-bars.png)
+
+<!-- example: examples/MovingAverage.svelte -->
 
-<!-- a 6-month moving average, run on the plot's rows -->
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- A 6-month moving average, run on the plot's rows. -->
 <LinePlot
-	{width}
-	{height}
-	data={rows}
+	width={720}
+	height={400}
+	data={PRICES}
 	x="date"
 	y="index"
-	color="division"
+	color="commodity"
 	transforms={[{ type: 'windowY', k: 6, reduce: 'mean' }]}
 />
 ```
 
-![Stacked bars](images/transforms-stack.png)
+<!-- /example -->
 
-![Lines smoothed by a moving average](images/transforms-window.png)
+![Lines smoothed by a moving average](images/moving-average.png)
 
 | Family    | `type`                                                                                        | Does                                                                                                                                                                                                                             |
 | --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -57,18 +77,28 @@ Bar stacking is always `stackY`, also for horizontal bars. A transform on a `His
 
 `statistics` is an array of derived summaries drawn as extra marks. On a plot it computes one per series by default; on a marker it applies to that marker's own rows.
 
+<!-- example: examples/Regression.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { ScatterPlot } from '@fundar/data-chart-telling';
+	import { COUNTRIES } from './data';
+</script>
+
+<!-- A linear regression with its 95% confidence band. -->
 <ScatterPlot
-	{width}
-	{height}
-	data={rows}
+	width={720}
+	height={400}
+	data={COUNTRIES}
 	x="gdp"
 	y="life"
 	statistics={[{ type: 'regression', regressionType: 'linear', confidence: 0.95 }]}
 />
 ```
 
-![A scatter plot with a regression line and confidence band](images/statistics-regression.png)
+<!-- /example -->
+
+![A scatter plot with a regression line and confidence band](images/regression.png)
 
 | `type`          | Draws                                                | Options                                                                                                                                                           |
 | --------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/examples/BarValues.svelte

@@ -1,13 +1,13 @@
 <script lang="ts">
 	import { BarPlot } from '@fundar/data-chart-telling';
-	import { ROWS } from './data';
+	import { REGION_VALUES, MONTHS } from './data';
 </script>
 
 <!-- Categories on x, values on y. Swap `x` and `y` for horizontal bars. -->
 <BarPlot
 	width={720}
 	height={400}
-	data={ROWS.filter((d) => d.year === 2023)}
+	data={REGION_VALUES.filter((row) => row.date === MONTHS.at(-1))}
 	x="region"
 	y="value"
 	styles={{ values: { show: true, anchor: 'outside' } }}

package/examples/Box.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+	import { BoxPlot } from '@fundar/data-chart-telling';
+	import { HEIGHTS } from './data';
+</script>
+
+<!-- One box per group: quartiles, median, whiskers and outliers of each height distribution. -->
+<BoxPlot width={720} height={400} data={HEIGHTS} x="group" y="height" color="group" />

package/examples/Chrome.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- A plot carries its own chrome: title, subtitle, legend and caption. -->
+<LinePlot
+	width={720}
+	height={440}
+	title="Commodity prices"
+	subtitle="Price index, January 2021 = 100"
+	caption="Source: IMF, Primary Commodity Prices"
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+/>

package/examples/ChromeOrder.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- `order` places the chrome blocks; `divider` draws a rule between them. -->
+<LinePlot
+	width={720}
+	height={460}
+	title="Commodity prices"
+	subtitle="Price index"
+	caption="Source: IMF, Primary Commodity Prices"
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+	order={['title', 'subtitle', 'divider', 'legend', 'plot', 'divider', 'caption']}
+/>

package/examples/Composer.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import { PlotComposer, LinePlot, BarPlot, ScatterPlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES, PROVINCE_VALUES, COUNTRIES } from './data';
+</script>
+
+<!-- Several plots in one figure, placed on named areas of a grid. -->
+<PlotComposer
+	width={900}
+	height={560}
+	title="Three views, one figure"
+	legend={false}
+	tags="A"
+	layout={{ areas: ['a a b', 'a a c'] }}
+>
+	<LinePlot area="a" data={REGION_VALUES} x="date" y="value" color="region" tooltip />
+	<BarPlot
+		area="b"
+		data={PROVINCE_VALUES.filter((row) => row.sex === 'female').slice(0, 3)}
+		x="province"
+		y="value"
+	/>
+	<ScatterPlot area="c" data={COUNTRIES} x="gdp" y="life" />
+</PlotComposer>

package/examples/CustomTooltip.svelte

@@ -1,35 +1,42 @@
 <script lang="ts">
 	import { LinePlot, getConfiguration, paletteColor } from '@fundar/data-chart-telling';
 	import TooltipCard from './TooltipCard.svelte';
-	import { ROWS, type Row } from './data';
+	import { REGION_VALUES, type RegionRow } from './data';
 
 	const { palette } = getConfiguration();
-	const regions = [...new Set(ROWS.map((d) => d.region))];
+	const regions = [...new Set(REGION_VALUES.map((row) => row.region))];
 </script>
 
 <!--
 	`content` replaces the tooltip text with your own markup, drawn in a plain
 	card: TooltipCard brings its own background, colors and spacing. It is given
-	every row the hover matched; series colors come from the configuration's palette.
+	every row the hover matched, in no particular order, so it sorts them itself;
+	series colors come from the configuration's palette.
 -->
-{#snippet content({ rows }: { rows: Row[] })}
+{#snippet content({ rows }: { rows: RegionRow[] })}
 	<TooltipCard
-		heading={String(rows[0].year)}
-		footer="Value by region"
-		entries={rows.map((row) => ({
-			label: row.region,
-			color: paletteColor(regions.indexOf(row.region), palette),
-			value: row.value,
-			display: String(row.value)
-		}))}
+		heading={rows[0].date.toLocaleDateString('en-US', {
+			month: 'long',
+			year: 'numeric',
+			timeZone: 'UTC'
+		})}
+		footer="Monthly inflation (%)"
+		entries={[...rows]
+			.sort((a, b) => b.value - a.value)
+			.map((row) => ({
+				label: row.region,
+				color: paletteColor(regions.indexOf(row.region), palette),
+				value: row.value,
+				display: String(row.value)
+			}))}
 	/>
 {/snippet}
 
 <LinePlot
 	width={720}
 	height={400}
-	data={ROWS}
-	x="year"
+	data={REGION_VALUES}
+	x="date"
 	y="value"
 	color="region"
 	tooltip={{ strategy: 'x', content }}

package/examples/Facets.svelte

@@ -1,14 +1,14 @@
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { ROWS } from './data';
+	import { REGION_VALUES } from './data';
 </script>
 
 <!-- One panel per region, three columns, sharing scales. A tooltip with `sync` shows in every panel on purpose. -->
 <LinePlot
 	width={900}
 	height={360}
-	data={ROWS}
-	x="year"
+	data={REGION_VALUES}
+	x="date"
 	y="value"
 	facet={{ by: 'region', columns: 3, gap: 12, scales: 'shared' }}
 	tooltip={{ sync: true }}