@fundar/data-chart-telling 1.0.0 → 1.2.0

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 small real datasets, one file each in `examples/datasets/`, which name their source, and axes are set to English. `docs/images` is left out of the npm package. So are the map boundaries the stories draw: the GeoJSON files in `examples/geo/`, and the datasets in `examples/datasets/` that load them (provinces, countries, comunas, partidos), which are not in the `$datasets` barrel - import them as `$datasets/<name>`.
 
 ```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 './datasets';
+</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 './datasets';
+</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 './datasets';
+
+	// 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 './datasets';
 </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/datasets/inflation-by-region.ts](../examples/datasets/inflation-by-region.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

@@ -6,13 +6,13 @@ A plot builds its legend from what it draws: its series, the scales its channels
 
 `legend` is unset or `true` for the automatic legend, `false` for none. The automatic legend can have these sections:
 
-| Section            | Appears when                    | Content                                    |
-| ------------------ | ------------------------------- | ------------------------------------------ |
-| series (discrete)  | the plot has several series     | one item per series, in its color and mark |
-| color (continuous) | `color` is a continuous value   | a ramp with its min and max                |
-| opacity            | `opacity` is a continuous value | a ramp fading across the opacity range     |
-| size               | `r` is mapped                   | a few dots at representative values        |
-| symbol             | `symbol` is mapped              | each category next to its shape            |
+| Section            | Appears when                    | Content                                                    |
+| ------------------ | ------------------------------- | ---------------------------------------------------------- |
+| series (discrete)  | the plot has several series     | one item per series, in its color and mark                 |
+| color (continuous) | `color` is a continuous value   | a ramp with its min and max                                |
+| opacity            | `opacity` is a continuous value | a bar fading across the opacity range, over a checkerboard |
+| size               | `r` is mapped                   | a few dots at representative values                        |
+| symbol             | `symbol` is mapped              | each category next to its shape                            |
 
 Segments and markers join the series section when they carry a `legend` label:
 
@@ -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 './datasets';
+	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...                                                                    |
 | ----------------- | ------------------------------------------------------------------------------------- |
@@ -66,32 +94,51 @@ legend={{
 	series: { title: 'Division', layout: { type: 'flex' } },
 	color: { title: 'Temperature', interactive: { enabled: true } },
 	opacity: { title: 'Confidence' },
-	size: { title: 'Population' },
+	r: { title: 'Population' },
 	symbol: { title: 'Income group' }
 }}
 ```
 
-Each channel key adjusts the section that channel draws: any section field except what the plots compute (items, ranges, domains). An entry with `match` adjusts only the section whose title matches; a list of entries adjusts several.
+Each key is the name of the channel (the plot's own prop: `r` for the size section) and adjusts the section that channel draws: any section field except what the plots compute (items, ranges, domains). An entry with `match` adjusts only the section whose title matches; a list of entries adjusts several.
 
 ## Explicit sections
 
 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 './datasets';
+</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:
@@ -103,4 +150,6 @@ Section types:
 
 ## Placement and look
 
+An opacity section draws its bar as one color fading over a checkerboard, so it reads as transparency and not as a color ramp; the color is the marker's own when it has one, else `legend.continuous.opacity.color` (black by default), and `legend.continuous.opacity.checker` sets the squares.
+
 The legend is a chrome block: `order` places it (`'legend'`, or in a row with the plot). Its fonts, gaps, swatch size and the continuous bar's geometry are `legend.*` in the [configuration](theming.md). A paginated section's prev/next arrows are replaceable with a `navButton` snippet.

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 './datasets';
+</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.
@@ -34,43 +45,45 @@ Markers draw in array order. Type a markers array with `satisfies AxisBasedMarke
 | Field                      | Meaning                                                                                                                                                                                         |
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `data`                     | The marker's own rows. Unset, it draws the plot's rows                                                                                                                                          |
-| `x`, `y`, `grouping`       | Accessors, when the marker reads other fields than the plot                                                                                                                                     |
+| `x`, `y`, `grouping`       | Accessors, when the marker reads other fields than the plot (a `bollinger` marker takes the plot's own `x` and `y` when it sets none)                                                           |
 | `series`                   | Draw over one series only (by name)                                                                                                                                                             |
 | `scope`                    | With `series`: `'series'` (default) draws once over the whole series; `'segment'` draws once per [segment](styles-and-segments.md), in its color - a `selectMaxY` marks each segment's own peak |
 | `scales`                   | The marker's own `color`/`opacity`/`symbol` scales, independent of the plot's                                                                                                                   |
 | `transforms`, `statistics` | Derive rows for this marker ([Transforms](transforms-and-statistics.md))                                                                                                                        |
 | `clip`                     | Clip to the plot's frame                                                                                                                                                                        |
+| `dx`, `dy`                 | Move the marker this many pixels right and down, on a map too. A `dot`, `text` or `image` marker also takes a function of the row, to move each row on its own: `dy: (row) => row.side * 15`    |
 | `legend`                   | Name the marker on the automatic [legend](legend.md)                                                                                                                                            |
 
 Many markers also take channel fields (`color`, `fill`, `opacity`, `r`, `symbol`, `weight`, `x1`/`x2`/`y1`/`y2`) and a `styles` object (`StrokeStyle`, `AreaStyle`, `DotStyle` or `FontStyle` depending on the mark).
 
 ## Catalog for axis-based plots
 
-| `type`                                                   | Draws                                                                                                        |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `dot`                                                    | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`)                                               |
-| `text`                                                   | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins` |
-| `line`                                                   | A line through the rows                                                                                      |
-| `rule`                                                   | A reference line: `axis: 'x' \| 'y'`, `value` (or a function with `data`), `styles`                          |
-| `tick`                                                   | A short tick per row along one axis                                                                          |
-| `bar`                                                    | A bar; `rect`, `cell`: rectangles and heatmap cells                                                          |
-| `rect`                                                   | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges                                   |
-| `area`                                                   | A filled area under a curve, or between `y1` and `y2`; `curve`                                               |
-| `difference`                                             | The area between two series, colored by which one is on top                                                  |
-| `arrow`                                                  | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`                                          |
-| `trail`                                                  | A variable-width ribbon along a path, its width set by `r`                                                   |
-| `delta`                                                  | The distance between two series (or a series and a fixed value) at a position, as a line and a label         |
-| `hull`                                                   | The convex hull around a cluster of points                                                                   |
-| `density`                                                | 2D density contour bands                                                                                     |
-| `box`                                                    | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`                        |
-| `regression`, `bollinger`                                | A fitted curve, a moving-average band                                                                        |
-| `waffle`                                                 | The value as a grid of unit squares; `unit`, `multiple`, `gap`                                               |
-| `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation                                                                     |
-| `image`                                                  | An image per row; `src`, `width`, `height`                                                                   |
-| `raster`                                                 | A field sampled over a rectangle, drawn to a canvas                                                          |
-| `brush`                                                  | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend`                                      |
-| `hover`                                                  | The in-plot hover highlight (see below)                                                                      |
-| `component`                                              | Your own Svelte component (see below)                                                                        |
+| `type`                                                   | Draws                                                                                                                                                                               |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dot`                                                    | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`)                                                                                                                      |
+| `text`                                                   | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins`                                                                        |
+| `line`                                                   | A line through the rows                                                                                                                                                             |
+| `rule`                                                   | A reference line: `axis: 'x' \| 'y'`, `value` (or a function with `data`), `styles`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row |
+| `tick`                                                   | A short tick per row along one axis                                                                                                                                                 |
+| `bar`                                                    | A bar; `rect`, `cell`: rectangles and heatmap cells                                                                                                                                 |
+| `rect`                                                   | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges                                                                                                          |
+| `area`                                                   | A filled area under a curve, or between `y1` and `y2`; `curve`                                                                                                                      |
+| `difference`                                             | The area between two series, colored by which one is on top                                                                                                                         |
+| `arrow`                                                  | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row                 |
+| `trail`                                                  | A variable-width ribbon along a path, its width set by `r`                                                                                                                          |
+| `delta`                                                  | The distance between two series (or a series and a fixed value) at a position, as a line and a label                                                                                |
+| `hull`                                                   | The convex hull around a cluster of points                                                                                                                                          |
+| `density`                                                | 2D density contour bands                                                                                                                                                            |
+| `box`                                                    | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`; `thickness` sets its width in pixels, `slot` its share of a band                             |
+| `violin`                                                 | A violin per category of its rows: the mirrored density of `y` (or `x`), `kernel`, `bandwidth`, `trim`, `peak`, `slot`; add a narrow `box` over the same rows for the box inside    |
+| `regression`, `bollinger`                                | A fitted curve, a moving-average band                                                                                                                                               |
+| `waffle`                                                 | The value as a grid of unit squares; `unit`, `multiple`, `gap`                                                                                                                      |
+| `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation                                                                                                                                            |
+| `image`                                                  | An image per row; `src`, `width`, `height`                                                                                                                                          |
+| `raster`                                                 | A field sampled over a rectangle, drawn to a canvas                                                                                                                                 |
+| `brush`                                                  | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend`                                                                                                             |
+| `hover`                                                  | The in-plot hover highlight (see below)                                                                                                                                             |
+| `component`                                              | Your own Svelte component (see below)                                                                                                                                               |
 
 ## Hover highlight
 

package/docs/plots/correlation/heatmap.md

@@ -0,0 +1,26 @@
+# HeatmapPlot
+
+Part of [Plots](../../plots.md).
+
+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
+<script lang="ts">
+	import { HeatmapPlot } from '@fundar/data-chart-telling';
+	import { PENGUIN_COUNTS } from './datasets';
+</script>
+
+<!-- One cell per island and species, colored by the number of penguins. -->
+<HeatmapPlot width={560} height={360} data={PENGUIN_COUNTS} x="island" y="species" color="count" />
+```
+
+<!-- /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).
+- `segments` restyle chosen columns, rows or single cells (see [Styles and segments](../../styles-and-segments.md)).
+- Hover matches one cell at a time.

package/docs/plots/correlation/scatter.md

@@ -0,0 +1,35 @@
+# ScatterPlot
+
+Part of [Plots](../../plots.md).
+
+A dot per row.
+
+<!-- example: examples/Scatter.svelte -->
+
+```svelte
+<script lang="ts">
+	import { ScatterPlot } from '@fundar/data-chart-telling';
+	import { COUNTRIES_AT_2007 } from './datasets';
+</script>
+
+<!-- Points sized by `r`, colored by `color` and shaped by `symbol`. -->
+<ScatterPlot
+	width={720}
+	height={420}
+	data={COUNTRIES_AT_2007}
+	x="gdp"
+	y="life"
+	r="population"
+	color="continent"
+	symbol="income"
+/>
+```
+
+<!-- /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.
+- A literal number for `r` is a fixed radius in pixels.
+- `dotRadius` defaults come from `scatter.dotRadius` in the configuration.

package/docs/plots/distribution/box.md

@@ -0,0 +1,28 @@
+# BoxPlot
+
+Part of [Plots](../../plots.md).
+
+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 './datasets';
+</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.

package/docs/plots/distribution/density.md

@@ -0,0 +1,26 @@
+# DensityPlot
+
+Part of [Plots](../../plots.md).
+
+Smooths the rows of each series along one axis into a kernel density estimate, the continuous pair of [HistogramPlot](histogram.md). Give `x` alone for a vertical curve or `y` alone for a horizontal one.
+
+<!-- example: examples/Density.svelte -->
+
+```svelte
+<script lang="ts">
+	import { DensityPlot } from '@fundar/data-chart-telling';
+	import { HEIGHTS } from './datasets';
+</script>
+
+<!-- A smoothed distribution per `grouping` value, the continuous pair of a histogram. -->
+<DensityPlot width={720} height={400} data={HEIGHTS} x="height" grouping="group" />
+```
+
+<!-- /example -->
+
+![Two density curves](../../images/density.png)
+
+- `grouping` (or `color`) draws one curve per group.
+- `styles={{ mark: 'line' }}` draws lines instead of filled areas; `styles.curve` sets how a curve joins its points.
+- Override the estimate with a `densityX` (or `densityY`) transform: `transforms={[{ type: 'densityX', bandwidth: 2 }]}`. A transform given here is merged over the default one; see [Transforms and statistics](../../transforms-and-statistics.md) for its options.
+- `segments={{ default: [{ styles: { fillOpacity: 0.3 } }] }}` restyles the areas.

package/docs/plots/distribution/histogram.md

@@ -0,0 +1,33 @@
+# HistogramPlot
+
+Part of [Plots](../../plots.md).
+
+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 './datasets';
+</script>
+
+<!-- Two overlapping distributions, one per `grouping` value. -->
+<HistogramPlot
+	width={720}
+	height={400}
+	data={HEIGHTS}
+	x="height"
+	grouping="group"
+	segments={{ default: [{ styles: { fillOpacity: 0.7 } }] }}
+/>
+```
+
+<!-- /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.

package/docs/plots/distribution/pyramid.md

@@ -0,0 +1,31 @@
+# PyramidPlot
+
+Part of [Plots](../../plots.md).
+
+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
+<script lang="ts">
+	import { PyramidPlot } from '@fundar/data-chart-telling';
+	import { POPULATION_BY_AGE_AT_2022 } from './datasets';
+</script>
+
+<!-- A population pyramid: one side per `color` value. -->
+<PyramidPlot
+	width={720}
+	height={400}
+	data={POPULATION_BY_AGE_AT_2022}
+	x="share"
+	y="ageGroup"
+	color="sex"
+/>
+```
+
+<!-- /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.