@fundar/data-chart-telling 1.0.0 → 1.2.0

package/docs/plots.md

@@ -1,158 +1,26 @@
 # 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))                     |
+Every plot kind shares one set of props (see [Concepts](concepts.md)). They differ in what they draw, which channels they need and how they hover.
+
+| Category     | Plot                                             | Draws                                                          | Needs                                                   |
+| ------------ | ------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------- |
+| Distribution | [DensityPlot](plots/distribution/density.md)     | A smoothed distribution of a numeric field                     | `x` or `y`                                              |
+| Distribution | [HistogramPlot](plots/distribution/histogram.md) | Counts of a numeric field in bins                              | `x` or `y`                                              |
+| Distribution | [BoxPlot](plots/distribution/box.md)             | The distribution of values per category                        | a category channel and a value channel                  |
+| Distribution | [ViolinPlot](plots/distribution/violin.md)       | The mirrored density of values per category, with a box inside | a category channel and a value channel                  |
+| Distribution | [PyramidPlot](plots/distribution/pyramid.md)     | Two series mirrored around zero                                | a category channel, a value channel, two series         |
+| Correlation  | [HeatmapPlot](plots/correlation/heatmap.md)      | A grid of colored cells                                        | `x`, `y`, `color`                                       |
+| Correlation  | [ScatterPlot](plots/correlation/scatter.md)      | A point per row                                                | `x`, `y`                                                |
+| Ranking      | [BarPlot](plots/ranking/bar.md)                  | Bars, grouped, stacked or horizontal                           | a category channel and a value channel                  |
+| Ranking      | [BulletPlot](plots/ranking/bullet.md)            | A bar against a target, over graded ranges                     | a category channel, a value channel, `target`, `ranges` |
+| Ranking      | [LollipopPlot](plots/ranking/lollipop.md)        | One dot on a stem per category                                 | a category channel and a value channel                  |
+| Ranking      | [DumbbellPlot](plots/ranking/dumbbell.md)        | Two dots per category, joined                                  | a category channel, a value channel, two series         |
+| Ranking      | [ClevelandPlot](plots/ranking/cleveland.md)      | Any number of dots per category, joined                        | a category channel, a value channel, a series per dot   |
+| Ranking      | [ForestPlot](plots/ranking/forest.md)            | One dot on an interval per row                                 | a category channel, a value channel, `lower`/`upper`    |
+| Evolution    | [LinePlot](plots/evolution/line.md)              | A line per series                                              | `x`, `y`                                                |
+| Evolution    | [AreaPlot](plots/evolution/area.md)              | A filled area per series                                       | `x`, `y`                                                |
+| Evolution    | [SparklinePlot](plots/evolution/sparkline.md)    | A small line with its last value, no axes                      | `x`, `y`                                                |
+| Evolution    | [SlopePlot](plots/evolution/slope.md)            | A line per series between two positions                        | a category channel with two values, a value channel     |
+| Map          | [GeoPlot](geo.md)                                | A map from GeoJSON or TopoJSON                                 | `data` (see [Maps](geo.md))                             |
 
 All of them accept `data` with `grouping`/`color`, or pre-built `series`.
-
-## LinePlot
-
-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).
-
-```svelte
-<LinePlot
-	{width}
-	{height}
-	data={rows}
-	x="date"
-	y="index"
-	color="division"
-	styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
-/>
-```
-
-![A line plot with end-of-line labels](images/plots-line.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`.
-- With a [`timeline`](timeline.md), the line reveals itself up to the current step and interpolates `y` between steps.
-- `segments` style ranges of a line; `markers` add `delta`, `rule`, `text` and the rest (see [Markers](markers.md)).
-
-## AreaPlot
-
-One filled area per series, under the line from `y` to the baseline. Default fill opacity comes from `area.fillOpacity` in the configuration.
-
-```svelte
-<AreaPlot
-	{width}
-	{height}
-	data={rows}
-	x="year"
-	y="value"
-	color="region"
-	transforms={[{ type: 'stackY' }]}
-/>
-```
-
-![A stacked area plot](images/plots-area.png)
-
-`transforms={[{ type: 'stackY' }]}` stacks the series.
-
-## BarPlot
-
-Bars where one axis holds the categories and the other the values. Categories on `x` give vertical bars; categories on `y` give horizontal bars.
-
-```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" />
-```
-
-![Vertical grouped bars](images/plots-bar.png)
-
-![Horizontal grouped bars](images/plots-bar-horizontal.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.
-- `scales.x.paddingInner` / `paddingOuter` set the spacing between category bands.
-- `styles.values.show` labels each bar; `styles.values.anchor` places the label (`'outside'`, `'start'`, `'middle'`, `'end'`).
-- The tooltip triggers anywhere over a bar's whole band, not just over the visible bar.
-
-## HistogramPlot
-
-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.
-
-```svelte
-<HistogramPlot
-	{width}
-	{height}
-	data={rows}
-	x="weight"
-	grouping="group"
-	segments={{ default: [{ styles: { fillOpacity: 0.7 } }] }}
-/>
-```
-
-![Two overlapping histograms](images/plots-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.
-
-## HeatmapPlot
-
-A grid of cells, `x` and `y` being the categories of the columns and rows and `color` the value that colors each cell.
-
-```svelte
-<HeatmapPlot {width} {height} data={cells} x="quarter" y="product" color="sales" />
-```
-
-![A heatmap with value labels](images/plots-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).
-- `segments` restyle chosen columns, rows or single cells (see [Styles and segments](styles-and-segments.md)).
-- Hover matches one cell at a time.
-
-## PyramidPlot
-
-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.
-
-```svelte
-<PyramidPlot {width} {height} data={ages} x="share" y="ageGroup" color="sex" />
-```
-
-![A population pyramid](images/plots-pyramid.png)
-
-- `scales.grouping.reverse` swaps which series sits on which side.
-- Hover finds the points sharing the hovered category.
-
-## ScatterPlot
-
-A dot per row.
-
-```svelte
-<ScatterPlot
-	{width}
-	{height}
-	data={countries}
-	x="gdp"
-	y="life"
-	r="population"
-	color="continent"
-	symbol="income"
-/>
-```
-
-![A scatter plot sized, colored and shaped by channels](images/plots-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.
-- A literal number for `r` is a fixed radius in pixels.
-- `dotRadius` defaults come from `scatter.dotRadius` in the configuration.
-
-## GeoPlot
-
-Draws GeoJSON or TopoJSON as a map: base features, a choropleth through `color`, per-feature `segments`, projections, camera and map-specific markers. It has its own page: [Maps](geo.md).

package/docs/scales.md

@@ -2,43 +2,65 @@
 
 `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 './datasets';
+</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`, `zero`, `clamp`, `round`, `percent`                               | Direction, rounding and baseline behaviour                                                                                                                                                                                                                                                                                                                                                                                           |
+| `nice`                                                                       | `true` or `false` to round the domain out to round numbers or not, or `{ tolerance }`: 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; `tolerance: 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`                                               | Time/discrete intervals, log base, symlog constant                                                                                                                                                                                                                                                                                                                                                                                   |
+| `sort`                                                                       | Category order: a comparator of two rows, or by what the categories hold (below)                                                                                                                                                                                                                                                                                                                                                     |
+
+A category axis whose labels do not fit side by side turns them by itself: to 45 degrees, else to 90, and when even that is not enough it writes only every few labels (and a vertical category axis, such as the one of horizontal bars, does the same). The margin grows to fit the turned labels. An axis with a `tickRotate` of its own - 0 included, which keeps the labels flat - is left as the author set it, and `axis.autoRotate: false` in the [configuration](theming.md) turns this off for every plot.
+
+A category axis can be ordered by what its categories hold, without writing a comparator: `sort: { by: 'value', series?, order? }` orders them by their value in one `series` (or, without it, by the sum of their values) and `sort: { by: 'range', order? }` by the spread between their lowest and their highest value; `order` is `'ascending'` (default) or `'descending'`. `grouped: true` orders within each series instead of across all of them: the series stay together, in the order they first appear. On a plot with intervals (`lower`/`upper`) the range counts the interval's ends. A category with nothing to order by goes last. An explicit `domain` wins. With [facets](facets.md) the order is read off every panel's rows, so the panels share it.
 
 Number and date text defaults follow `axis.locale` and `axis.compactDisplay` in the [configuration](theming.md#locale).
 
@@ -46,20 +68,21 @@ Number and date text defaults follow `axis.locale` and `axis.compactDisplay` in
 
 `scales.color` configures the `color` channel (and a choropleth on a map).
 
-| Field     | Meaning                                                                                                                                                                                        |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `domain`  | `[min, max]` for a continuous value, or the list of categories                                                                                                                                 |
-| `scheme`  | A named [d3-scale-chromatic](https://d3js.org/d3-scale-chromatic) ramp (`'turbo'`, `'blues'`, `'rdylbu'`, case-insensitive), two or more colors to interpolate, or a `Record<category, color>` |
-| `pivot`   | Splits an array `scheme` into two halves meeting at this value (a diverging ramp)                                                                                                              |
-| `unknown` | Color of a value outside the mapping (default `#ccc`)                                                                                                                                          |
+| Field         | Meaning                                                                                                                                                                                        |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `domain`      | `[min, max]` for a continuous value, or the list of categories                                                                                                                                 |
+| `scheme`      | A named [d3-scale-chromatic](https://d3js.org/d3-scale-chromatic) ramp (`'turbo'`, `'blues'`, `'rdylbu'`, case-insensitive), two or more colors to interpolate, or a `Record<category, color>` |
+| `schemeRange` | The part of a named `scheme` to use, as `[from, to]` fractions of it (default `[0, 1]`): `[0.3, 1]` skips the near-white start of a ramp like `'blues'`                                        |
+| `pivot`       | Splits an array `scheme` into two halves meeting at this value (a diverging ramp)                                                                                                              |
+| `unknown`     | Color of a value outside the mapping (default `#ccc`)                                                                                                                                          |
 
-A continuous ramp is set with `scheme: [colorA, colorB]`. Categorical colors come from the configuration's `palette` unless `scheme` is a category-to-color record.
+A continuous ramp is set with `scheme: [colorA, colorB]`. Categorical colors come from the configuration's `palette` unless `scheme` is a category-to-color record. Series that follow one another (years, say) read better on a named sequential ramp, which is sampled across the series in order: `scheme: 'blues', schemeRange: [0.3, 1]`.
 
 A marker can carry its own `scales.color`, independent of the plot's, so two ramps can coexist in one plot.
 
 ## Grouping
 
-`scales.grouping.reverse` flips which group sorts first, such as which side of a [pyramid](plots.md#pyramidplot) a series sits on.
+`scales.grouping.reverse` flips which group sorts first, such as which side of a [pyramid](plots/distribution/pyramid.md) a series sits on.
 
 ## Opacity
 

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 './datasets';
+</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,16 +42,21 @@
 />
 ```
 
-![End-of-line value labels](images/styles-values.png)
+<!-- /example -->
 
-| Field          | Meaning                                                                                                                                        |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `show`         | Draws the labels. Off by default, except on a heatmap                                                                                          |
-| `anchor`       | `'outside'`, `'start'`, `'middle'`, `'end'` - where a label sits on its mark                                                                   |
-| `format`       | `(value, seriesName) => string`                                                                                                                |
-| `hoverIsolate` | Hovering a label dims every other series                                                                                                       |
-| `fontStyle`    | Text style: `fontSize`, `fill`, `dx`, `dy`, `textAnchor`, `lineAnchor`, `rotate`, `class`, ... Overrides the anchor's placement field by field |
-| `strokeStyle`  | Style of the connector lines drawn from labels that had to move apart                                                                          |
+![End-of-line value labels](images/value-labels.png)
+
+| Field          | Meaning                                                                                                                                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `show`         | Draws the labels. Off by default, except on a heatmap                                                                                                                                                                     |
+| `anchor`       | `'outside'`, `'start'`, `'middle'`, `'end'` - where a label sits on its mark                                                                                                                                              |
+| `select`       | Which row of each group is labelled: `'first'`, `'last'`, `'min'`, `'max'`, or a list of them. A group is a series on a line or area plot (default `'last'`), a category on the plots that join dots (default: every dot) |
+| `series`       | Labels only these series, by name                                                                                                                                                                                         |
+| `color`        | `'series'` writes each label in its series' color; any other CSS color writes them all in it (`fontStyle.fill` wins)                                                                                                      |
+| `format`       | `(value, seriesName, row) => string`; `row` is the labelled row, for its other fields                                                                                                                                     |
+| `hoverIsolate` | Hovering a label dims every other series                                                                                                                                                                                  |
+| `fontStyle`    | Text style: `fontSize`, `fill`, `dx`, `dy`, `textAnchor`, `lineAnchor`, `rotate`, `class`, ... Overrides the anchor's placement field by field                                                                            |
+| `strokeStyle`  | Style of the connector lines drawn from labels that had to move apart                                                                                                                                                     |
 
 Where the labels go depends on the plot: the end of each series on a line or area plot, one per bar on a bar, pyramid or histogram, one per point on a scatter, one per cell on a heatmap. On lines, overlapping labels spread apart, share one column and are joined to their points by elbow connectors; the right margin grows to fit them when it is `'auto'`. The spread is tuned by `text.declutter` in the [configuration](theming.md).
 
@@ -55,24 +68,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 { FEMALE_LIFE_GAPS } from './datasets';
+</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: FEMALE_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 +135,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 './datasets';
+
+	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 +162,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 './datasets';
+</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 +198,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 +216,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 { PENGUIN_COUNTS } from './datasets';
+</script>
+
+<!-- Segments on a heatmap: an outlined column and a filled block of cells. -->
 <HeatmapPlot
-	{width}
-	{height}
-	{data}
-	x="quarter"
-	y="product"
-	color="sales"
+	width={560}
+	height={360}
+	data={PENGUIN_COUNTS}
+	x="island"
+	y="species"
+	color="count"
 	segments={{
 		default: [
 			{
-				areas: [{ x: { from: 'Q1', to: 'Q1' } }, { x: { from: 'Q3', to: 'Q3' } }],
+				areas: [{ x: { from: 'Biscoe', to: 'Biscoe' } }],
 				styles: { stroke: '#f59e0b', strokeWidth: 2 }
 			},
 			{
-				areas: [{ x: { from: 'Q2', to: 'Q2' }, y: { from: 'Alpha', to: 'Beta' } }],
+				areas: [{ x: { from: 'Dream', to: 'Torgersen' }, y: { from: 'Chinstrap', to: 'Gentoo' } }],
 				styles: { fill: '#ef4444', fillOpacity: 0.8 }
 			}
 		]
@@ -192,7 +247,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: