@fundar/data-chart-telling 1.0.0 → 1.1.0

package/docs/plots.md

@@ -1,17 +1,18 @@
 # Plots
 
-Eight plot kinds share one set of props (see [Concepts](concepts.md)). They differ in what they draw, which channels they need and how they hover.
-
-| Plot                              | Draws                                | Needs                                           |
-| --------------------------------- | ------------------------------------ | ----------------------------------------------- |
-| [`LinePlot`](#lineplot)           | A line per series                    | `x`, `y`                                        |
-| [`AreaPlot`](#areaplot)           | A filled area per series             | `x`, `y`                                        |
-| [`BarPlot`](#barplot)             | Bars, grouped, stacked or horizontal | a category channel and a value channel          |
-| [`HistogramPlot`](#histogramplot) | Counts of a numeric field in bins    | `x` or `y`                                      |
-| [`HeatmapPlot`](#heatmapplot)     | A grid of colored cells              | `x`, `y`, `color`                               |
-| [`PyramidPlot`](#pyramidplot)     | Two series mirrored around zero      | a category channel, a value channel, two series |
-| [`ScatterPlot`](#scatterplot)     | A point per row                      | `x`, `y`                                        |
-| [`GeoPlot`](#geoplot)             | A map from GeoJSON or TopoJSON       | `data` (see [Maps](geo.md))                     |
+Nine plot kinds share one set of props (see [Concepts](concepts.md)). They differ in what they draw, which channels they need and how they hover.
+
+| Plot                              | Draws                                   | Needs                                           |
+| --------------------------------- | --------------------------------------- | ----------------------------------------------- |
+| [`LinePlot`](#lineplot)           | A line per series                       | `x`, `y`                                        |
+| [`AreaPlot`](#areaplot)           | A filled area per series                | `x`, `y`                                        |
+| [`BarPlot`](#barplot)             | Bars, grouped, stacked or horizontal    | a category channel and a value channel          |
+| [`HistogramPlot`](#histogramplot) | Counts of a numeric field in bins       | `x` or `y`                                      |
+| [`BoxPlot`](#boxplot)             | The distribution of values per category | a category channel and a value channel          |
+| [`HeatmapPlot`](#heatmapplot)     | A grid of colored cells                 | `x`, `y`, `color`                               |
+| [`PyramidPlot`](#pyramidplot)     | Two series mirrored around zero         | a category channel, a value channel, two series |
+| [`ScatterPlot`](#scatterplot)     | A point per row                         | `x`, `y`                                        |
+| [`GeoPlot`](#geoplot)             | A map from GeoJSON or TopoJSON          | `data` (see [Maps](geo.md))                     |
 
 All of them accept `data` with `grouping`/`color`, or pre-built `series`.
 
@@ -19,19 +20,29 @@ All of them accept `data` with `grouping`/`color`, or pre-built `series`.
 
 One line per series. Rows with a missing value (`null`, `undefined`, `NaN`) break the line; `styles.gaps` can [bridge the break](styles-and-segments.md#gaps).
 
+<!-- example: examples/LineDates.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- A line per commodity over a date axis, with end-of-line labels. -->
 <LinePlot
-	{width}
-	{height}
-	data={rows}
+	width={720}
+	height={400}
+	data={PRICES}
 	x="date"
 	y="index"
-	color="division"
+	color="commodity"
 	styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
 />
 ```
 
-![A line plot with end-of-line labels](images/plots-line.png)
+<!-- /example -->
+
+![A line plot with end-of-line labels](images/line-dates.png)
 
 - `styles.values.show` writes a label at the end of each series, with the series name and value. Overlapping labels spread apart automatically and the margin grows to fit them.
 - Hover finds the points sharing the hovered `x`.
@@ -42,19 +53,30 @@ One line per series. Rows with a missing value (`null`, `undefined`, `NaN`) brea
 
 One filled area per series, under the line from `y` to the baseline. Default fill opacity comes from `area.fillOpacity` in the configuration.
 
+<!-- example: examples/StackedArea.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { AreaPlot } from '@fundar/data-chart-telling';
+	import { AGE_SHARES } from './data';
+</script>
+
+<!-- Each age group's share of the population, stacked with `stackY` so the bands add up to 100%. -->
 <AreaPlot
-	{width}
-	{height}
-	data={rows}
+	width={720}
+	height={400}
+	data={AGE_SHARES}
 	x="year"
-	y="value"
-	color="region"
+	y="share"
+	color="ageGroup"
+	scales={{ x: { ticks: [1991, 2001, 2010, 2022] } }}
 	transforms={[{ type: 'stackY' }]}
 />
 ```
 
-![A stacked area plot](images/plots-area.png)
+<!-- /example -->
+
+![A stacked area plot](images/stacked-area.png)
 
 `transforms={[{ type: 'stackY' }]}` stacks the series.
 
@@ -62,16 +84,53 @@ One filled area per series, under the line from `y` to the baseline. Default fil
 
 Bars where one axis holds the categories and the other the values. Categories on `x` give vertical bars; categories on `y` give horizontal bars.
 
+<!-- example: examples/GroupedBars.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './data';
+</script>
+
+<!-- Vertical bars, grouped by `color`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="province"
+	y="value"
+	color="sex"
+	scales={{ y: { domain: [70, 85] } }}
+/>
+```
+
+<!-- /example -->
+
+![Vertical grouped bars](images/grouped-bars.png)
+
+<!-- example: examples/HorizontalBars.svelte -->
+
 ```svelte
-<!-- vertical -->
-<BarPlot {width} {height} data={rows} x="province" y="value" color="sex" />
-<!-- horizontal -->
-<BarPlot {width} {height} data={rows} x="value" y="province" color="sex" />
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './data';
+</script>
+
+<!-- Horizontal bars: the categories go on `y`, the values on `x`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="value"
+	y="province"
+	color="sex"
+	scales={{ x: { domain: [70, 85] } }}
+/>
 ```
 
-![Vertical grouped bars](images/plots-bar.png)
+<!-- /example -->
 
-![Horizontal grouped bars](images/plots-bar-horizontal.png)
+![Horizontal grouped bars](images/horizontal-bars.png)
 
 - Several series sharing a category sit side by side, each in its slice of the category band. The gap between them is `bar.seriesPadding` in the configuration.
 - `transforms={[{ type: 'stackY' }]}` stacks the series instead. Stacking is always `stackY`, also for horizontal bars, because the value channel is the one stacked.
@@ -83,33 +142,80 @@ Bars where one axis holds the categories and the other the values. Categories on
 
 Bins the rows of each series along one axis and draws the count per bin. Give `x` alone for vertical bars or `y` alone for horizontal bars.
 
+<!-- example: examples/Histogram.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { HistogramPlot } from '@fundar/data-chart-telling';
+	import { HEIGHTS } from './data';
+</script>
+
+<!-- Two overlapping distributions, one per `grouping` value. -->
 <HistogramPlot
-	{width}
-	{height}
-	data={rows}
-	x="weight"
+	width={720}
+	height={400}
+	data={HEIGHTS}
+	x="height"
 	grouping="group"
 	segments={{ default: [{ styles: { fillOpacity: 0.7 } }] }}
 />
 ```
 
-![Two overlapping histograms](images/plots-histogram.png)
+<!-- /example -->
+
+![Two overlapping histograms](images/histogram.png)
 
 - `grouping` (or `color`) draws one histogram per group.
 - Override the default binning with a `binX` (or `binY`) transform: `transforms={[{ type: 'binX', thresholds: 20 }]}`. A transform given here is merged over the default one.
 - `transforms={[{ type: 'stackY' }]}` stacks groups in each bin.
 - `segments={{ default: [{ styles: { fillOpacity: 0.7 } }] }}` makes overlapping groups translucent.
 
+## BoxPlot
+
+Summarizes the values of each series per category as a box: it spans the middle half of the values (25th to 75th percentile), the line across it is the median, the whiskers reach the farthest values within 1.5 times the box's height, and dots mark the values past them. String values on `x` stand the boxes upright; on `y` they lie sideways.
+
+<!-- example: examples/Box.svelte -->
+
+```svelte
+<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" />
+```
+
+<!-- /example -->
+
+![Box plots of two height distributions](images/box.png)
+
+- `grouping` (or `color`) draws one box per group and category. Groups that share categories draw their boxes on top of each other, so split them with `facet` instead, or color by the category field itself.
+- Categories keep the order the data gives them; `scales.x.domain` (or `y`) orders them.
+- The value axis fits the values without reaching for zero; pin `scales.y.domain` to start it at zero.
+- `scales.x.paddingInner` / `paddingOuter` set how wide the boxes are; the defaults come from `box` in the [configuration](theming.md).
+- The tooltip reads one box at a time, not every value inside it: the hovered row carries `category`, `min`, `p25`, `median`, `p75`, `max`, `count` and `outliers`.
+- `segments` restyle whole categories (`areas: [{ x: { from: 'Bus', to: 'Bus' } }]`). A segment that splits one category's values draws two boxes.
+
 ## HeatmapPlot
 
 A grid of cells, `x` and `y` being the categories of the columns and rows and `color` the value that colors each cell.
 
+<!-- example: examples/Heatmap.svelte -->
+
 ```svelte
-<HeatmapPlot {width} {height} data={cells} x="quarter" y="product" color="sales" />
+<script lang="ts">
+	import { HeatmapPlot } from '@fundar/data-chart-telling';
+	import { HOUSEHOLDS } from './data';
+</script>
+
+<!-- One cell per number of rooms and of people, colored by the share of households. -->
+<HeatmapPlot width={560} height={360} data={HOUSEHOLDS} x="rooms" y="people" color="share" />
 ```
 
-![A heatmap with value labels](images/plots-heatmap.png)
+<!-- /example -->
+
+![A heatmap with value labels](images/heatmap.png)
 
 - The color domain spans the whole dataset, so it stays comparable across [facets](facets.md).
 - Cell value labels are on by default (`styles.values.show` turns them off).
@@ -120,11 +226,21 @@ A grid of cells, `x` and `y` being the categories of the columns and rows and `c
 
 Two series mirrored around a shared zero baseline, such as a population pyramid. Categories on `y` give horizontal bars; categories on `x` give vertical ones.
 
+<!-- example: examples/Pyramid.svelte -->
+
 ```svelte
-<PyramidPlot {width} {height} data={ages} x="share" y="ageGroup" color="sex" />
+<script lang="ts">
+	import { PyramidPlot } from '@fundar/data-chart-telling';
+	import { AGES } from './data';
+</script>
+
+<!-- A population pyramid: one side per `color` value. -->
+<PyramidPlot width={720} height={400} data={AGES} x="share" y="ageGroup" color="sex" />
 ```
 
-![A population pyramid](images/plots-pyramid.png)
+<!-- /example -->
+
+![A population pyramid](images/pyramid.png)
 
 - `scales.grouping.reverse` swaps which series sits on which side.
 - Hover finds the points sharing the hovered category.
@@ -133,11 +249,19 @@ Two series mirrored around a shared zero baseline, such as a population pyramid.
 
 A dot per row.
 
+<!-- example: examples/Scatter.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { ScatterPlot } from '@fundar/data-chart-telling';
+	import { COUNTRIES } from './data';
+</script>
+
+<!-- Points sized by `r`, colored by `color` and shaped by `symbol`. -->
 <ScatterPlot
-	{width}
-	{height}
-	data={countries}
+	width={720}
+	height={420}
+	data={COUNTRIES}
 	x="gdp"
 	y="life"
 	r="population"
@@ -146,7 +270,9 @@ A dot per row.
 />
 ```
 
-![A scatter plot sized, colored and shaped by channels](images/plots-scatter.png)
+<!-- /example -->
+
+![A scatter plot sized, colored and shaped by channels](images/scatter.png)
 
 - `r` sizes the dots (area follows the value; configure with `scales.r`). The legend gets a size section.
 - `symbol` varies the dot shape by category (`scales.symbol`), `opacity` varies transparency, `color` colors by category or by a continuous ramp.

package/docs/scales.md

@@ -2,43 +2,60 @@
 
 `scales` configures how data values become positions and visual properties. It has one entry per channel.
 
+<!-- example: examples/Scales.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- Axis labels, a fixed domain with gridlines and a color per series. -->
 <LinePlot
-	{width}
-	{height}
-	data={rows}
+	width={720}
+	height={400}
+	data={PRICES}
 	x="date"
 	y="index"
-	color="division"
+	color="commodity"
 	scales={{
 		x: { label: 'Month' },
-		y: { label: 'Index (Jan 2021 = 100)', domain: [90, 280], grid: true },
+		y: { label: 'Index (Jan 2021 = 100)', domain: [0, 600], grid: true },
 		color: {
-			scheme: { Food: '#1b9e77', Transport: '#d95f02', Housing: '#7570b3', Health: '#e7298a' }
+			scheme: {
+				'Brent oil': '#1b9e77',
+				'Natural gas': '#d95f02',
+				Coal: '#7570b3',
+				Wheat: '#e7298a'
+			}
 		}
 	}}
 />
 ```
 
+<!-- /example -->
+
 ![A line plot with a labelled axis, gridlines and custom colors](images/scales.png)
 
 ## Axes: `x` and `y`
 
 Each axis takes an `AxisScale`.
 
-| Field                                                                        | Meaning                                                                                                                                                                                                                       |
-| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`                                                                       | `'auto'` (default), `'linear'`, `'pow'`, `'sqrt'`, `'log'`, `'symlog'`, `'time'`, `'utc'`, `'band'`, `'point'`, `'ordinal'`, `'categorical'` and the color-oriented types (`'sequential'`, `'diverging'`, `'threshold'`, ...) |
-| `domain`, `range`                                                            | Explicit input and output extent                                                                                                                                                                                              |
-| `reverse`, `nice`, `zero`, `clamp`, `round`, `percent`                       | Direction, rounding and baseline behaviour                                                                                                                                                                                    |
-| `label`, `labelAnchor`, `labelOrientation`, `labelPosition`, `titleFontSize` | The axis title (`label: false` hides it)                                                                                                                                                                                      |
-| `ticks`, `tickSpacing`, `tickSize`, `tickPadding`, `tickRotate`              | Tick placement and size                                                                                                                                                                                                       |
-| `tickFormat`                                                                 | `false`, an `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions` object, or `(d, index, ticks) => string`                                                                                                                |
-| `grid`                                                                       | `true` or a stroke style for gridlines                                                                                                                                                                                        |
-| `axisDisplay`                                                                | `'visible'` (default), `'hidden'` (keeps the space, so aligned panels stay aligned) or `'none'`                                                                                                                               |
-| `padding`, `paddingInner`, `paddingOuter`, `align`                           | Band and point spacing                                                                                                                                                                                                        |
-| `insetLeft`, `insetRight`, `insetTop`, `insetBottom`                         | Pixels kept free at each end                                                                                                                                                                                                  |
-| `interval`, `base`, `constant`, `sort`                                       | Time/discrete intervals, log base, symlog constant, category order                                                                                                                                                            |
+| Field                                                                        | Meaning                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`                                                                       | `'auto'` (default), `'linear'`, `'pow'`, `'sqrt'`, `'log'`, `'symlog'`, `'time'`, `'utc'`, `'band'`, `'point'`, `'ordinal'`, `'categorical'` and the color-oriented types (`'sequential'`, `'diverging'`, `'threshold'`, ...)                                                                                                                                                                   |
+| `domain`, `range`                                                            | Explicit input and output extent                                                                                                                                                                                                                                                                                                                                                                |
+| `reverse`, `nice`, `zero`, `clamp`, `round`, `percent`                       | Direction, rounding and baseline behaviour                                                                                                                                                                                                                                                                                                                                                      |
+| `niceTolerance`                                                              | How far past a tick, as a share of the step, a domain the plot nices itself still ends on it (default `0.05`), so parts adding up to `100.2` stay at `100`. Applies to stacked and ranged axes, axes grown to cover markers or a transform's output, a bar plot's value axis and shared facet/timeline domains; `0` rounds like d3                                                              |
+| `edgeTicks`                                                                  | Ticks at the data's first and last values beside the nice ones. `false` turns them off, `true` on, `{ collision: 'drop-nice' \| 'drop-edge' \| 'extend' }` picks what happens when one crowds a nice tick. Defaults to `axis.edgeTicks.x` / `.y` in the [configuration](theming.md#edge-ticks) (on for x, off for y); ignored when the axis sets `ticks`, `tickSpacing`, `interval` or `domain` |
+| `label`, `labelAnchor`, `labelOrientation`, `labelPosition`, `titleFontSize` | The axis title (`label: false` hides it)                                                                                                                                                                                                                                                                                                                                                        |
+| `ticks`, `tickSpacing`, `tickSize`, `tickPadding`, `tickRotate`              | Tick placement and size                                                                                                                                                                                                                                                                                                                                                                         |
+| `tickFormat`                                                                 | `false`, an `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions` object, or `(d, index, ticks) => string`                                                                                                                                                                                                                                                                                  |
+| `grid`                                                                       | `true` or a stroke style for gridlines                                                                                                                                                                                                                                                                                                                                                          |
+| `axisDisplay`                                                                | `'visible'` (default), `'hidden'` (keeps the space, so aligned panels stay aligned) or `'none'`                                                                                                                                                                                                                                                                                                 |
+| `padding`, `paddingInner`, `paddingOuter`, `align`                           | Band and point spacing                                                                                                                                                                                                                                                                                                                                                                          |
+| `insetLeft`, `insetRight`, `insetTop`, `insetBottom`                         | Pixels kept free at each end                                                                                                                                                                                                                                                                                                                                                                    |
+| `interval`, `base`, `constant`, `sort`                                       | Time/discrete intervals, log base, symlog constant, category order                                                                                                                                                                                                                                                                                                                              |
 
 Number and date text defaults follow `axis.locale` and `axis.compactDisplay` in the [configuration](theming.md#locale).
 

package/docs/state.md

@@ -8,7 +8,7 @@ Works anywhere inside a figure, including the `header`, `footer` and `content` s
 
 - `hover` - `activeX`, `activeY`, `activeSeries`, `strategy`, `sync`, `source` (the id of the plot owning the hover).
 - `legend` (or `null`) - `entries`, `range`, `off` (names of hidden series), `isOff(name)`, `turnOff(name, action)`, `turnOn(name)`, `toggle(name, action)`. `action` is `{ mode: 'dim' | 'hide' | 'omit' }`; `'omit'` removes the series and refits the axes.
-- `timeline` (or `null`) - `enabled`, `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, `controls`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`.
+- `timeline` (or `null`) - `enabled`, `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, `controls`, 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.
 
 A footer that toggles series through the legend:
 

package/docs/styles-and-segments.md

@@ -16,14 +16,22 @@
 
 ### Value labels
 
+<!-- example: examples/ValueLabels.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- End-of-line value labels with a custom format and font size. -->
 <LinePlot
-	{width}
-	{height}
-	data={rows}
+	width={720}
+	height={400}
+	data={PRICES}
 	x="date"
 	y="index"
-	color="division"
+	color="commodity"
 	styles={{
 		values: {
 			show: true,
@@ -34,7 +42,9 @@
 />
 ```
 
-![End-of-line value labels](images/styles-values.png)
+<!-- /example -->
+
+![End-of-line value labels](images/value-labels.png)
 
 | Field          | Meaning                                                                                                                                        |
 | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -55,24 +65,35 @@ Where the labels go depends on the plot: the end of each series on a line or are
 
 A row whose value is `null`, `undefined` or `NaN` breaks a line. `styles.gaps` bridges the break with a distinct, interpolated stretch. It is keyed by series name, or `'default'` for the series with no entry of their own, and has three zones: `start` (before the first real point), `middle` and `end` (after the last).
 
+<!-- example: examples/Gaps.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { LIFE_GAPS } from './data';
+</script>
+
+<!-- Missing values bridged: dashed in the middle, faded at the start, extended to the 2025 projection at the end. -->
 <LinePlot
-	{width}
-	{height}
-	series={[{ name: 'female', x: 'year', y: 'value', data: rowsWithHoles }]}
+	width={720}
+	height={400}
+	series={[{ name: 'female', x: 'year', y: 'value', data: LIFE_GAPS }]}
+	scales={{ x: { edgeTicks: true }, y: { domain: [55, 85] } }}
 	styles={{
 		gaps: {
 			default: {
 				middle: { interpolate: 'linear', style: { stroke: { strokeDasharray: '4 4' } } },
-				start: { x: 2007, style: { stroke: { strokeOpacity: 0.4 } } },
-				end: { x: 2023, y: 85 }
+				start: { x: 1940, style: { stroke: { strokeOpacity: 0.4 } } },
+				end: { x: 2025, y: 81.1 }
 			}
 		}
 	}}
 />
 ```
 
-![A line bridged across missing values with dashed segments](images/styles-gaps.png)
+<!-- /example -->
+
+![A line bridged across missing values with dashed segments](images/gaps.png)
 
 - `middle` bridges holes between real points, `interpolate` is an easing name (default `'linear'`).
 - `start` and `end` reach out to the given `x` (required to fill the zone), landing on `y` there (default: the nearest real value).
@@ -111,16 +132,26 @@ The style shape depends on the plot:
 
 A baseline color with a highlighted range:
 
+<!-- example: examples/SegmentHighlight.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+
+	const gba = REGION_VALUES.filter((row) => row.region === 'GBA');
+</script>
+
+<!-- A grey line with the 2023-2024 surge drawn in red. -->
 <LinePlot
-	{width}
-	{height}
-	series={[{ name: 'gdp', x: 'year', y: 'value', data: gdp }]}
+	width={720}
+	height={380}
+	series={[{ name: 'GBA', x: 'date', y: 'value', data: gba }]}
 	segments={{
-		gdp: [
+		GBA: [
 			{ styles: { stroke: { stroke: '#94a3b8', strokeWidth: 1 } } },
 			{
-				areas: [{ x: { from: 2008, to: 2010 } }],
+				areas: [{ x: { from: new Date('2023-07-01'), to: new Date('2024-03-01') } }],
 				styles: { stroke: { stroke: '#ef4444', strokeWidth: 3 } }
 			}
 		]
@@ -128,24 +159,35 @@ A baseline color with a highlighted range:
 />
 ```
 
-![A grey line with a highlighted red range](images/segments-highlight.png)
+<!-- /example -->
+
+![A grey line with a highlighted red range](images/segment-highlight.png)
 
 Per-series colors, plus dots over a range shared by every series:
 
+<!-- example: examples/SegmentsBySeries.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { LIFE } from './data';
+</script>
+
+<!-- Segments per series name, plus `default` for rules shared by every series. -->
 <LinePlot
-	{width}
-	{height}
-	data={lifeExpectancy}
+	width={720}
+	height={380}
+	data={LIFE}
 	x="year"
 	y="value"
 	color="sex"
+	scales={{ x: { edgeTicks: true } }}
 	segments={{
 		female: [{ styles: { stroke: { stroke: 'steelblue' } } }],
 		male: [{ styles: { stroke: { stroke: 'tomato' } } }],
 		default: [
 			{
-				areas: [{ x: { from: 2010, to: 2012 } }],
+				areas: [{ x: { from: 1965, to: 1980 } }],
 				styles: { dots: { dotRadius: 5, dotSymbol: 'circle' } }
 			}
 		]
@@ -153,7 +195,9 @@ Per-series colors, plus dots over a range shared by every series:
 />
 ```
 
-![Two series colored individually, with dots on a shared range](images/segments-series.png)
+<!-- /example -->
+
+![Two series colored individually, with dots on a shared range](images/segments-by-series.png)
 
 Two areas in one segment, the second with a `y` limit:
 
@@ -169,22 +213,30 @@ Two areas in one segment, the second with a `y` limit:
 
 Heatmap columns and cells:
 
+<!-- example: examples/HeatmapSegments.svelte -->
+
 ```svelte
+<script lang="ts">
+	import { HeatmapPlot } from '@fundar/data-chart-telling';
+	import { HOUSEHOLDS } from './data';
+</script>
+
+<!-- Segments on a heatmap: an outlined column and a filled block of overcrowded households. -->
 <HeatmapPlot
-	{width}
-	{height}
-	{data}
-	x="quarter"
-	y="product"
-	color="sales"
+	width={560}
+	height={360}
+	data={HOUSEHOLDS}
+	x="rooms"
+	y="people"
+	color="share"
 	segments={{
 		default: [
 			{
-				areas: [{ x: { from: 'Q1', to: 'Q1' } }, { x: { from: 'Q3', to: 'Q3' } }],
+				areas: [{ x: { from: '1', to: '1' } }],
 				styles: { stroke: '#f59e0b', strokeWidth: 2 }
 			},
 			{
-				areas: [{ x: { from: 'Q2', to: 'Q2' }, y: { from: 'Alpha', to: 'Beta' } }],
+				areas: [{ x: { from: '1', to: '2' }, y: { from: '4', to: '5+' } }],
 				styles: { fill: '#ef4444', fillOpacity: 0.8 }
 			}
 		]
@@ -192,7 +244,9 @@ Heatmap columns and cells:
 />
 ```
 
-![A heatmap with highlighted columns and cells](images/segments-heatmap.png)
+<!-- /example -->
+
+![A heatmap with highlighted columns and cells](images/heatmap-segments.png)
 
 Map features, keyed by feature id: