@fundar/data-chart-telling 1.0.0 → 1.1.0

package/dist/types/layout/timeline.d.ts

@@ -2,7 +2,12 @@ import type { Snippet } from 'svelte';
 import type { AxisValue } from './mapping';
 import type { Accessor } from '../plots/data/common';
 import type { EasingName, EasingFn } from '../misc/easing';
+/** A step as the timeline works with it: a number (a date as its timestamp). */
 export type TimeValue = number;
+/** A step as the rows hold it: a number, a `Date` or a date string. */
+export type TimeInput = TimeValue | Date | string;
+/** A step as authors see it: a `Date` on a timeline of dates, else the number. */
+export type TimelineStep = number | Date;
 export type Orientation = 'horizontal' | 'vertical';
 export type TimelineChildContext<TRow extends Record<string, unknown>> = {
     selectedValue: TimeValue;
@@ -42,8 +47,8 @@ export type PlayerConfig = {
     speeds?: number[];
     /** Milliseconds each step lasts at speed `1`. Defaults to the configuration's `timeline.player.stepDuration`. */
     stepDuration?: number;
-    /** How the current step reads in the `'value'` control. Defaults to the step itself. */
-    format?: (value: TimeValue) => string;
+    /** How a step reads, in the player and along a rule. Defaults to the step, or a date label for dates. */
+    format?: (value: TimelineStep) => string;
     onplay?: (playing: boolean) => void;
     onspeed?: (speed: number) => void;
     onloop?: (loop: boolean) => void;
@@ -53,10 +58,13 @@ export type TimelineCallbacks = {
     /** Called with the new position, `0`-`1`, whenever the player or the reader moves it. */
     onprogress?: (progress: number) => void;
     /** Called with the step the position lands on, when that step changes. */
-    onvalue?: (value: TimeValue) => void;
+    onvalue?: (value: TimelineStep) => void;
 };
 export type TimelineConfig<TRow extends Record<string, unknown>> = TimelineCallbacks & {
-    accessor: Accessor<TRow, TimeValue>;
+    /** The field (or function) giving each row's step: a number, a `Date`, or an ISO or `dateFormat` date string. */
+    accessor: Accessor<TRow, TimeInput>;
+    /** How a non-ISO date string reads, with `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, e.g. `'DD/MM/YYYY'`. */
+    dateFormat?: string;
     /** How it draws. Defaults to `'player'`. */
     type?: TimelineType;
     /** The player bar's own options, when `type` is `'player'`. */
@@ -67,7 +75,8 @@ export type TimelineConfig<TRow extends Record<string, unknown>> = TimelineCallb
      * with its own `timeline`, the composer's wins and nothing draws here.
      */
     progress?: number;
-    values?: TimeValue[];
+    /** The steps, when not every distinct value of `accessor`. */
+    values?: TimeInput[];
     /** Which way a `'rule'` runs. A `'player'` is always horizontal. */
     orientation?: Orientation;
     show?: boolean;

package/dist/types/phases/hover/phase.d.ts

@@ -17,6 +17,12 @@ export type HoverStageOptions<TState, TCtx = unknown> = {
      * that isn't measured, or `'punctual'` with both axes holding categories.
      */
     strategy?: HoverStrategy;
+    /** The rows the pointer hovers over, when they aren't the ones drawn (a box plot's one summary per box). Defaults to the processed rows. */
+    rows?: (state: TState) => Record<string | symbol, unknown>[];
+    /** How a hovered row reads in the tooltip unless the author sets `format`. Defaults to the shared tooltip text. */
+    format?: (state: TState) => (row: never) => string;
+    /** The order a tooltip's rows read in. Defaults to the shared order: highest value first. */
+    sort?: (state: TState) => (a: never, b: never) => number;
     /** Where a row sits. Defaults to its processed position: a stacked row's top, a bin's centre. */
     position?: (state: TState) => HoverPosition;
     /** The short label drawn next to a hovered row. Defaults to its value. */

package/dist/types/phases/state.d.ts

@@ -1,4 +1,4 @@
-import type { Series } from '../plots/data/common';
+import type { Accessor, Series } from '../plots/data/common';
 import type { AxisBasedScalesConfig } from '../layout/scales';
 import type { SegmentsConfig, MarginConfig, HoverConfig, TooltipConfig } from '../plots/props';
 import type { HoverPosition } from './hover/phase';
@@ -9,7 +9,7 @@ import type { PlotStylesConfig } from '../configuration/styling';
 import type { AxisBasedMarkersConfig } from '../markers/common';
 import type { StatisticConfig } from '../layout/statistics';
 import type { MarkerTransform } from '../transforms';
-import type { ProcessedData } from './transforms/phase';
+import type { ProcessedData, ProcessedRow } from './transforms/phase';
 import type { FacetStageState } from './facet/phase';
 import type { AxisBasedStylesConfig, ValuesStyle } from '../layout/styles';
 import type { ValueLabels } from '../../layout/styles/ValueLabels';
@@ -48,6 +48,7 @@ export type AxisPlotState<TData extends Record<string, unknown>, TStyle extends
     /** What each position channel is, which one holds the categories, and which way the plot runs. */
     axes?: PlotAxes;
     resolvedSeries?: TSeries[];
+    seriesGrouping?: Accessor<any, unknown>;
     /** Every series name, before legend-omitted ones are dropped, so colors stay put. */
     allSeriesNames?: string[];
     groupedSeries?: VisualGroup<TSeries, TStyle>[];
@@ -58,9 +59,11 @@ export type AxisPlotState<TData extends Record<string, unknown>, TStyle extends
     gapFillMaps?: Map<string, Map<TData, DiscreteGapFill<TStyle>>>;
     channels?: ResolvedChannels<TData>;
     processedData?: ProcessedData;
+    processedGroups?: VisualGroup<Series<ProcessedRow>, TStyle>[];
     valueLabels?: ValueLabels;
     markers?: AxisBasedMarkersConfig[];
     tooltipFormat?: (row: Record<string, unknown>) => string;
+    tooltipSort?: (a: Record<string, unknown>, b: Record<string, unknown>) => number;
     hover?: HoverConfig<any>;
     hoverPosition?: HoverPosition;
     hoverRows?: unknown[];

package/dist/types/phases/statistics/phase.d.ts

@@ -3,7 +3,7 @@ import type { Accessor, Series } from '../../plots/data/common';
 import type { AxisValue } from '../../layout/mapping';
 import type { StatisticConfig } from '../../layout/statistics';
 import type { AxisBasedMarkersConfig } from '../../markers/common';
-import type { ProcessedData } from '../transforms/phase';
+import type { ProcessedData, TransformsStageState } from '../transforms/phase';
 import type { FacetStageState } from '../facet/phase';
 import type { PlotAxes } from '../../../phases/data/PlotAxes';
 /**
@@ -25,6 +25,8 @@ export type StatisticsStageState = Pick<FacetStageState, 'panels'> & {
     scopedGroups?: ScopedMarkerGroup<any>[];
     /** The plot's rows after its own transforms, which an author marker without rows of its own draws. */
     processedData?: ProcessedData;
+    /** Those rows split back into the plot's visual groups, which a series without a value of its own (a histogram's) is measured by. */
+    processedGroups?: TransformsStageState['processedGroups'];
     markers?: AxisBasedMarkersConfig[];
 };
 /** What differs between plots in the shared "statistics" stage. */

package/dist/types/phases/transforms/phase.d.ts

@@ -1,6 +1,7 @@
 import type { Series } from '../../plots/data/common';
 import type { MarkerTransform } from '../../transforms';
 import type { PlotAxes } from '../../../phases/data/PlotAxes';
+import type { VisualGroup } from '../../plots/segments/config';
 /** A row the plot-level transforms produced: the source row's fields, plus whatever channels they add (often symbol-keyed). */
 export type ProcessedRow = Record<string | symbol, unknown>;
 /** A channel as svelteplot reads it off a processed row: a field key, a symbol key, or a function. */
@@ -32,9 +33,18 @@ export type TransformsStageState = {
     }>>;
     transforms?: MarkerTransform[];
     processedData?: ProcessedData;
+    /** The processed rows split back into the visual groups the plot's own marks draw. */
+    processedGroups?: VisualGroup<Series<ProcessedRow>, any>[];
 };
 /** What differs between plots in the shared "transforms" stage. */
 export type TransformsStageOptions<TState extends TransformsStageState, TCtx> = {
     /** The transforms to run. Defaults to the plot's own `transforms`. */
     transforms?: (state: TState, ctx: TCtx) => MarkerTransform[];
+    /**
+     * How the processed rows split into `processedGroups`: one group per series
+     * (the default), or `'runs'` of consecutive rows from the same series, in
+     * the rows' own order, so a reordering transform (`sort`, `reverse`,
+     * `shuffle`) decides which rows paint on top.
+     */
+    groups?: 'series' | 'runs';
 };

package/dist/types/plots/box/props.d.ts

@@ -0,0 +1,10 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { AxisBasedScalesConfig } from '../../layout/scales';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { SeriesProps, DataProps } from '../data/common';
+import type { AxisBasedStylesConfig } from '../../layout/styles';
+import type { AreaStyle } from '../styling';
+/** `BoxPlot`'s public props. */
+export type BoxPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+/** What `BoxPlot`'s core draws from. */
+export type BoxPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/box/props.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/box/state.d.ts

@@ -0,0 +1,23 @@
+import type { AreaStyle } from '../styling';
+import type { AxisPlotState, AxisPlotCtx, ProcessedRow } from '../../phases';
+import type { AxisValue } from '../../layout/mapping';
+/** BoxPlot's pipeline state: the shared axis-based state, with no extras of its own. */
+export type BoxPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, AreaStyle>;
+/** The environment every BoxPlot phase reads from, alongside the growing state. */
+export type BoxPlotCtx = AxisPlotCtx;
+/**
+ * One box's summary - what a hovered box reads as: its category, its
+ * quartiles, the whisker ends (the farthest values within 1.5 IQR of the
+ * box) and the values past them. It also keeps the series tags and, when the
+ * category channel is a field key, the category under that field.
+ */
+export type BoxSummaryRow = ProcessedRow & {
+    category: AxisValue;
+    min: number;
+    p25: number;
+    median: number;
+    p75: number;
+    max: number;
+    count: number;
+    outliers: number[];
+};

package/dist/types/plots/box/state.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/props.d.ts

@@ -48,8 +48,10 @@ export type HoverConfig<TRow extends Record<string, unknown>> = {
     strategy?: HoverStrategy;
     /** Resolved sync flag for the *local* hover store (ignored once a shared store is in scope). */
     sync?: boolean;
+    /** The resolved tooltip: its `format`, and the order its text reads the rows in (a `content` snippet gets them as matched). */
     tooltip?: TooltipConfig<TRow> & {
         format: (row: TRow) => string;
+        sort?: (a: TRow, b: TRow) => number;
     };
     /** When it returns `true`, that pointer event is treated as a leave instead of a move - lets a nested layout opt part of the plot out of hover matching. */
     exclude?: (e: PointerEvent) => boolean;

package/docs/chrome.md

@@ -2,20 +2,30 @@
 
 The chrome is everything a figure draws around its plot: title, subtitle, legend, timeline player, caption. Every plot and every [composer](composer.md) takes the same chrome props.
 
+<!-- example: examples/Chrome.svelte -->
+
 ```svelte
+<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}
-	{height}
-	title="Consumer prices"
-	subtitle="Index by division, December 2016 = 100"
-	caption="Source: national statistics office"
-	data={rows}
+	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="division"
+	color="commodity"
 />
 ```
 
+<!-- /example -->
+
 ![A plot with title, subtitle and caption](images/chrome.png)
 
 | Prop       | Type                    | Meaning                                          |
@@ -55,10 +65,31 @@ A `header` takes the place of `title` and `subtitle`, and a `footer` the place o
 - `'divider'` draws a line between the two blocks around it, and only when both are drawn. Several dividers may appear.
 - A row puts two or three blocks side by side: `'(plot, timeline)'`, `'(legend, plot)'`. The `plot` takes the width the others leave; a row without `plot` shares its width among the blocks.
 
+<!-- example: examples/ChromeOrder.svelte -->
+
 ```svelte
-<LinePlot ... order={['title', 'subtitle', 'divider', 'legend', 'plot', 'divider', 'caption']} />
+<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']}
+/>
 ```
 
+<!-- /example -->
+
 ![Dividers placed between chrome blocks](images/chrome-order.png)
 
 The default order, from the configuration's `chrome.order`: `header`, `title`, `subtitle`, `divider`, `legend`, `plot`, `timeline`, `footer`, `caption`. It can be changed globally with `setConfiguration({ chrome: { order: [...] } })`.

package/docs/composer.md

@@ -2,20 +2,36 @@
 
 `PlotComposer` puts several plots in one figure. It is a figure like any plot: it takes the same [chrome](chrome.md) (`title`, `subtitle`, `caption`, `legend`, `order`) and a `width` and `height`, and lays its children out on a grid.
 
+<!-- example: examples/Composer.svelte -->
+
 ```svelte
+<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={series} x="year" y="value" color="metric" tooltip />
-	<BarPlot area="b" data={bars} x="region" y="value" />
-	<ScatterPlot area="c" data={points} x="gdp" y="life" />
+	<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>
 ```
 
+<!-- /example -->
+
 ![Three plots in one figure on a named-area layout](images/composer.png)
 
 Plots drawn straight inside the composer take a cell of the grid and draw at the cell's size - they need no `width` or `height`.

package/docs/concepts.md

@@ -2,7 +2,7 @@
 
 ## Plots and figures
 
-A **plot** is one graph: axes and marks. Every plot is a component named after what it draws - `LinePlot`, `AreaPlot`, `BarPlot`, `HistogramPlot`, `HeatmapPlot`, `PyramidPlot`, `ScatterPlot`, `GeoPlot` (see [Plots](plots.md)).
+A **plot** is one graph: axes and marks. Every plot is a component named after what it draws - `LinePlot`, `AreaPlot`, `BarPlot`, `HistogramPlot`, `BoxPlot`, `HeatmapPlot`, `PyramidPlot`, `ScatterPlot`, `GeoPlot` (see [Plots](plots.md)).
 
 A plot is drawn inside a **figure**: the box that holds the plot together with its [chrome](chrome.md) (title, subtitle, legend, timeline, caption). Every plot component is a figure, so a plot with a `title` and a `legend` is still one component. A [`PlotComposer`](composer.md) is a figure that holds several plots.
 

package/docs/development.md

@@ -35,7 +35,7 @@ pnpm test:stories                      # every story as a test (boots Storybook
 
 - Component tests must end in `.svelte.test.ts`; that suffix is what routes a file to the browser project.
 - Browser tests render with `vitest-browser-svelte`. A dot renders as a `<path>`, not a `<circle>`; styles live in the `style` attribute.
-- `tests/unit/docs` and `tests/unit/examples.svelte.test.ts` guard the LLM-facing docs: every example mounts, and the links and exports named in `llms.txt` and `llms-full.txt` exist.
+- `tests/unit/docs` and `tests/unit/examples.svelte.test.ts` guard the LLM-facing docs: every example mounts, the links and exports named in `llms.txt` and `llms-full.txt` exist, and the example snippets in the Markdown match their files.
 
 ## Storybook
 
@@ -53,14 +53,23 @@ Every option has a story under `stories/`, grouped as Plots, Markers, Transforms
 
 ## Documentation figures
 
-Every screenshot in the docs is a real component in `scripts/docs-figures/figures/`, type-checked by `pnpm check` and rendered by Playwright:
+Every screenshot in the docs is an example, rendered by Playwright to `docs/images/<name>.png` in kebab-case (`examples/LineByRegion.svelte` is `line-by-region.png`). The examples and the screenshots share one file of small real datasets, `examples/data.ts`, which names the source of each, and axes are set to English. `docs/images` is left out of the npm package.
 
 ```bash
-pnpm docs:images               # regenerate docs/images/*.png
-pnpm docs:images tooltip scales   # only these figures
+pnpm docs:images                  # regenerate docs/images/*.png
+pnpm docs:images tooltip scales   # only these
 ```
 
-A figure can set `export const meta = { hover: { x, y } }` in a `<script module>` block to rest the pointer before the shot. The data is synthetic and deterministic (`scripts/docs-figures/data.ts`), and axes are set to English. `docs/images` is left out of the npm package.
+`scripts/docs-figures/figures.json` lists the examples that get no screenshot (`skip`) and where the pointer rests before a shot (`meta`, e.g. `{ "hover": { "x": 330, "y": 160 } }`). The maps are the exception: their GeoJSON is too large to ship in `examples/`, so they are components of their own in `scripts/docs-figures/figures/`, importing it from `stories/`, and their snippets in `geo.md` and `styles-and-segments.md` are written by hand.
+
+The Markdown shows each example's source between `<!-- example: examples/Name.svelte -->` and `<!-- /example -->`:
+
+```bash
+pnpm docs:examples           # copy each example's source into README.md and docs/*.md
+pnpm docs:examples --check   # fail when a block is out of date
+```
+
+`tests/unit/docs/examples-sync.test.ts` runs the check, so a snippet never drifts from its example or its screenshot.
 
 ## Continuous integration
 

package/docs/facets.md

@@ -2,18 +2,29 @@
 
 `facet` splits a plot's rows into small multiples: one panel per value of a field, each drawn with the same plot configuration.
 
+<!-- example: examples/Facets.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	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}
-	{height}
-	data={rows}
-	x="year"
+	width={900}
+	height={360}
+	data={REGION_VALUES}
+	x="date"
 	y="value"
-	facet={{ by: 'region', columns: 3, gap: 12 }}
+	facet={{ by: 'region', columns: 3, gap: 12, scales: 'shared' }}
+	tooltip={{ sync: true }}
 />
 ```
 
-![One panel per region](images/facets-grid.png)
+<!-- /example -->
+
+![One panel per region](images/facets.png)
 
 The data phases (grouping, transforms, statistics, shared scales) run once for all panels; each panel then lays itself out in its own box. Panels share legend toggles and hover, so one legend controls them all.
 
@@ -36,20 +47,63 @@ The data phases (grouping, transforms, statistics, shared scales) run once for a
 | `scales`                 | `'shared'` (default), `'free'`, `'free-x'`, `'free-y'`                                                                                          |
 | `axes`                   | `'all'` (default) draws every panel's axes; `'outer'` draws only the left column's y and the bottom row's x, with panels resized to equal boxes |
 
+<!-- example: examples/FacetsCarousel.svelte -->
+
 ```svelte
-<BarPlot ... facet={{ by: 'group', columns: 3, mode: 'carousel', visible: 2 }} />
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- A carousel shows `visible` panels at a time, with navigation below. -->
+<LinePlot
+	width={720}
+	height={340}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	facet={{ by: 'region', columns: 3, mode: 'carousel', visible: 2, navLayout: 'below' }}
+/>
 ```
 
+<!-- /example -->
+
 ![A carousel showing two panels at a time](images/facets-carousel.png)
 
 ## Rows by columns
 
 `{ rows, cols }` makes one panel per combination of a row field and a column field, with each value labelled. Combinations without data stay empty. `rowValues` and `colValues` choose and order the values. A free `x` scale is shared down each column and a free `y` along each row.
 
+<!-- example: examples/FacetsRowsCols.svelte -->
+
 ```svelte
-<LinePlot ... facet={{ rows: 'region', cols: 'sector', scales: 'free' }} />
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+
+	// Each region's value split into two sectors.
+	const SECTORS = [
+		{ sector: 'Goods', share: 0.8 },
+		{ sector: 'Services', share: 1.4 }
+	];
+	const rows = REGION_VALUES.flatMap((row) =>
+		SECTORS.map(({ sector, share }) => ({ ...row, sector, value: row.value * share }))
+	);
+</script>
+
+<!-- One panel per region and sector; `scales: 'free'` fits each panel to its own data. -->
+<LinePlot
+	width={720}
+	height={420}
+	data={rows}
+	x="date"
+	y="value"
+	facet={{ rows: 'region', cols: 'sector', scales: 'free' }}
+/>
 ```
 
+<!-- /example -->
+
 ![Panels for each combination of region and sector](images/facets-rows-cols.png)
 
 ## Alignment

package/docs/getting-started.md

@@ -13,24 +13,23 @@ pnpm add @fundar/data-chart-telling svelte svelteplot
 
 ## A first plot
 
+<!-- example: examples/FirstPlot.svelte -->
+
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-
-	const rows = [
-		{ year: 2020, region: 'North', value: 3.1 },
-		{ year: 2021, region: 'North', value: 3.8 },
-		{ year: 2020, region: 'South', value: 2.2 },
-		{ year: 2021, region: 'South', value: 2.9 }
-	];
+	import { REGION_VALUES } from './data';
 </script>
 
-<LinePlot width={720} height={400} data={rows} x="year" y="value" color="region" />
+<!-- The smallest useful plot: rows, the fields to map and a pixel size. -->
+<LinePlot width={720} height={400} data={REGION_VALUES} x="date" y="value" color="region" />
 ```
 
+<!-- /example -->
+
 ![A line plot with one line per region](images/first-plot.png)
 
-- `data` is an array of flat rows; `x` and `y` name the fields that position each row.
+- `data` is an array of flat rows, here `{ date, region, value }` from [examples/data.ts](../examples/data.ts); `x` and `y` name the fields that position each row.
 - `color="region"` splits the rows into one series per region and gives each its own color.
 - `width` and `height` are pixels.
 

package/docs/legend.md

@@ -37,11 +37,39 @@ Segments and markers join the series section when they carry a `legend` label:
 
 Items become clickable with `interactive` on the series section. `disabled` says what a hidden series becomes:
 
+<!-- example: examples/LegendToggle.svelte -->
+
 ```svelte
-<LinePlot ... legend={{ series: { interactive: { enabled: true, disabled: { mode: 'omit' } } } }} />
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+	import LegendReader from './LegendReader.svelte';
+</script>
+
+<!--
+	The automatic legend can toggle series. `mode: 'omit'` drops a hidden series
+	and refits the axes to what is left; 'dim' and 'hide' keep the axes.
+	Anything inside the figure (here, the footer) reads the toggles through
+	`useFigure().legend` - see LegendReader.
+-->
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	legend={{ series: { interactive: { enabled: true, disabled: { mode: 'omit' } } } }}
+>
+	{#snippet footer()}
+		<LegendReader />
+	{/snippet}
+</LinePlot>
 ```
 
-![Legend items as toggles](images/legend-interactive.png)
+<!-- /example -->
+
+![Legend items as toggles](images/legend-toggle.png)
 
 | `disabled.mode`   | A hidden series...                                                                    |
 | ----------------- | ------------------------------------------------------------------------------------- |
@@ -77,21 +105,40 @@ Each channel key adjusts the section that channel draws: any section field excep
 
 A list replaces the automatic legend with exactly those sections:
 
-```ts
-legend={[
-	{
-		type: 'discrete',
-		title: 'Indicator',
-		interactive: { enabled: true },
-		items: [
-			{ name: 'GDP', color: '#4f46e5', symbol: 'line' },
-			{ name: 'Employment', color: '#e6580d', symbol: 'line' }
-		]
-	},
-	{ type: 'continuous', title: 'Share', min: 0, max: 100, scheme: 'blues' }
-]}
+<!-- example: examples/LegendSections.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- An explicit legend: a discrete section of toggles and a continuous ramp. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	legend={[
+		{
+			type: 'discrete',
+			title: 'Region',
+			interactive: { enabled: true },
+			items: [
+				{ name: 'GBA', color: '#4f46e5', symbol: 'line' },
+				{ name: 'Cuyo', color: '#e6580d', symbol: 'line' },
+				{ name: 'Northwest', color: '#16a34a', symbol: 'line' }
+			]
+		},
+		{ type: 'continuous', title: 'Share', min: 0, max: 100, scheme: 'blues' }
+	]}
+/>
 ```
 
+<!-- /example -->
+
 ![A legend of explicit sections: discrete items and a continuous ramp](images/legend-sections.png)
 
 Section types:

package/docs/markers.md

@@ -2,29 +2,40 @@
 
 `markers` adds marks to a plot beyond the ones its kind draws: annotations, regions, derived shapes, hover highlights, or any Svelte component. It is an array of objects; `type` picks the marker and the other fields configure it.
 
+<!-- example: examples/Markers.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { LIFE } from './data';
+</script>
+
+<!-- Markers add marks to a plot: a hover highlight, a reference rule and a delta between two series. -->
 <LinePlot
-	{width}
-	{height}
-	data={lifeExpectancy}
+	width={720}
+	height={400}
+	data={LIFE}
 	x="year"
 	y="value"
 	color="sex"
+	scales={{ x: { edgeTicks: true } }}
 	markers={[
 		{ type: 'hover' },
-		{ type: 'rule', axis: 'x', value: 2020, styles: { stroke: '#999', strokeDasharray: '4 4' } },
+		{ type: 'rule', axis: 'x', value: 2001, styles: { stroke: '#999', strokeDasharray: '4 4' } },
 		{
 			type: 'delta',
 			axis: 'x',
-			at: 2018,
+			at: 1980,
 			from: { type: 'series', series: 'female' },
 			to: { type: 'series', series: 'male' },
-			formatDiff: (d) => d.toFixed(1)
+			formatDiff: (difference) => difference.toFixed(1)
 		}
 	]}
 />
 ```
 
+<!-- /example -->
+
 ![A line plot with a reference rule and a delta between two series](images/markers.png)
 
 Markers draw in array order. Type a markers array with `satisfies AxisBasedMarkersConfig[]` (or `GeoMarkersConfig[]`) to get completion.