@fundar/data-chart-telling 1.1.0 → 1.3.0

package/docs/development.md

@@ -53,7 +53,7 @@ Every option has a story under `stories/`, grouped as Plots, Markers, Transforms
 
 ## Documentation figures
 
-Every screenshot in the docs is an example, rendered by Playwright to `docs/images/<name>.png` in kebab-case (`examples/LineByRegion.svelte` is `line-by-region.png`). The examples and the screenshots share one file of small real datasets, `examples/data.ts`, which names the source of each, and axes are set to English. `docs/images` is left out of the npm package.
+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

package/docs/facets.md

@@ -7,7 +7,7 @@
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- One panel per region, three columns, sharing scales. A tooltip with `sync` shows in every panel on purpose. -->
@@ -52,7 +52,7 @@ The data phases (grouping, transforms, statistics, shared scales) run once for a
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- A carousel shows `visible` panels at a time, with navigation below. -->
@@ -79,7 +79,7 @@ The data phases (grouping, transforms, statistics, shared scales) run once for a
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 
 	// Each region's value split into two sectors.
 	const SECTORS = [
@@ -106,6 +106,53 @@ The data phases (grouping, transforms, statistics, shared scales) run once for a
 
 ![Panels for each combination of region and sector](images/facets-rows-cols.png)
 
+## Markers and segments in some panels
+
+Every panel draws the plot's `markers` and `segments`. Add `facet` to one to limit it to the panels it names: the value of its `by` field, or a list of them. Without `facet` it applies to every panel, as before.
+
+<!-- example: examples/FacetsScoped.svelte -->
+
+```svelte
+<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. `facet` on a marker or a segment limits it to the panels it names: the rule is drawn in GBA only, and Services is dashed in Cuyo only. -->
+<LinePlot
+	width={900}
+	height={360}
+	data={rows}
+	x="date"
+	y="value"
+	color="sector"
+	facet={{ by: 'region', columns: 3 }}
+	markers={[{ type: 'rule', axis: 'y', value: 10, facet: 'GBA' }]}
+	segments={{ Services: [{ facet: 'Cuyo', styles: { stroke: { strokeDasharray: '4 4' } } }] }}
+/>
+```
+
+<!-- /example -->
+
+![Markers and segments in some panels](images/facets-scoped.png)
+
+| `facet`                              | Applies to                                                                                                                                  |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| _not set_                            | Every panel, and a plot with no facet                                                                                                       |
+| `'GBA'` or `['GBA', 'Cuyo']`         | The panels with that `by` value (numbers and booleans match the text they print as)                                                         |
+| `{ row: 'GBA' }`, `{ col: 'Goods' }` | In a `rows`/`cols` grid, the panels with that row or column value; `{ row, col }` takes both, and a side left out matches every value of it |
+
+A marker or a segment that names a facet is not drawn by a plot that has none. It works on every plot kind: a `GeoPlot` map takes it the same way, on top of slicing its marker rows by the facet field.
+
 ## Alignment
 
 Panels line up: each plot reports the margins it settled on, and once all have, every column and row pins its widest ones, so the plot areas align whatever their tick labels need.

package/docs/getting-started.md

@@ -18,7 +18,7 @@ pnpm add @fundar/data-chart-telling svelte svelteplot
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- The smallest useful plot: rows, the fields to map and a pixel size. -->
@@ -29,7 +29,7 @@ pnpm add @fundar/data-chart-telling svelte svelteplot
 
 ![A line plot with one line per region](images/first-plot.png)
 
-- `data` is an array of flat rows, here `{ date, region, value }` from [examples/data.ts](../examples/data.ts); `x` and `y` name the fields that position each row.
+- `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:
 
@@ -42,7 +42,7 @@ Items become clickable with `interactive` on the series section. `disabled` says
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 	import LegendReader from './LegendReader.svelte';
 </script>
 
@@ -94,12 +94,12 @@ 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
 
@@ -110,7 +110,7 @@ A list replaces the automatic legend with exactly those sections:
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- An explicit legend: a discrete section of toggles and a continuous ramp. -->
@@ -150,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

@@ -7,7 +7,7 @@
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { LIFE } from './data';
+	import { LIFE } from './datasets';
 </script>
 
 <!-- Markers add marks to a plot: a hover highlight, a reference rule and a delta between two series. -->
@@ -45,43 +45,73 @@ 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` (a list draws a line at each, 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 - or at each of a list of them, `at: [1980, 2000]` - 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)                                                                                                                                                                            |
+
+## Markers in some facets
+
+On a plot with a [`facet`](facets.md#markers-and-segments-in-some-panels), every marker is drawn in every panel. A marker takes `facet`, a panel's value or a list of them, to be drawn only in the panels it names.
+
+## Several positions at once
+
+A `rule` takes a list as its `value`, and a `delta` a list as its `at`. One marker then draws one line, or one delta, at each position, all with the same style and the same ends - instead of one marker for each.
+
+```ts
+markers={[
+	// A rule at each of the three years.
+	{ type: 'rule', axis: 'x', value: [1991, 2001, 2010], styles: { strokeDasharray: '4 4' } },
+	// The gap between the two series at each of the three.
+	{ type: 'delta', axis: 'x', at: [1991, 2001, 2010], from: { type: 'series', series: 'female' }, to: { type: 'series', series: 'male' } }
+]}
+```
+
+A delta's `line`, `text` and `dot` can be functions of the position, to style each one on its own - a label to the left of the last one, say, so it stays inside the plot:
+
+```ts
+{
+	type: 'delta', axis: 'x', at: [1991, 2001, 2022], from: { type: 'series', series: 'female' }, to: { type: 'series', series: 'male' },
+	text: (at) => (at === 2022 ? { dx: -20, textAnchor: 'end' } : { dx: 20 })
+}
+```
+
+Every other marker draws from `data` rows, one mark per row, so it already takes many positions.
 
 ## 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.

package/docs/plots/distribution/violin.md

@@ -0,0 +1,35 @@
+# ViolinPlot
+
+Part of [Plots](../../plots.md).
+
+Draws, for each category, the density estimate of its values mirrored around the middle of its band, with a box inside: the shape of the distribution that [BoxPlot](box.md) summarizes. Give the category on `x` and the values on `y`, or swap them for horizontal violins.
+
+<!-- example: examples/Violin.svelte -->
+
+```svelte
+<script lang="ts">
+	import { ViolinPlot } from '@fundar/data-chart-telling';
+	import { IRIS } from './datasets';
+</script>
+
+<!-- The sepal length of the flowers of each species: its density, mirrored, with a box inside. -->
+<ViolinPlot
+	width={720}
+	height={400}
+	data={IRIS}
+	x="species"
+	y="sepalLength"
+	scales={{ y: { label: 'Sepal length (cm)' } }}
+/>
+```
+
+<!-- /example -->
+
+![Violins of sepal length by iris species](../../images/violin.png)
+
+- `grouping` (or `color`) draws one violin per group inside each category's band, side by side. A category with fewer than two values in a group draws no violin.
+- `styles.kernel` and `styles.bandwidth` set the estimate; Silverman's rule picks each violin's bandwidth when unset.
+- `styles.trim` (default `true`) cuts each violin at its values' own extent. With `false` the tails fade out past it, beyond what the value axis reaches.
+- `styles.scale: 'shared'` draws every violin on one density scale, so their areas compare; the default gives each the same full width.
+- `styles.box: false` leaves the inner box out, and a number sets its width in pixels.
+- Hovering a violin reads the same summary as a box plot: quartiles, whisker ends and the values past them.

package/docs/plots/evolution/area.md

@@ -0,0 +1,32 @@
+# AreaPlot
+
+Part of [Plots](../../plots.md).
+
+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 './datasets';
+</script>
+
+<!-- Each age group's share of the population, stacked with `stackY` so the bands add up to 100%. -->
+<AreaPlot
+	width={720}
+	height={400}
+	data={AGE_SHARES}
+	x="year"
+	y="share"
+	color="ageGroup"
+	scales={{ x: { ticks: [1991, 2001, 2010, 2022] } }}
+	transforms={[{ type: 'stackY' }]}
+/>
+```
+
+<!-- /example -->
+
+![A stacked area plot](../../images/stacked-area.png)
+
+`transforms={[{ type: 'stackY' }]}` stacks the series.

package/docs/plots/evolution/line.md

@@ -0,0 +1,93 @@
+# LinePlot
+
+Part of [Plots](../../plots.md).
+
+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 './datasets';
+</script>
+
+<!-- A line per commodity over a date axis, with end-of-line labels. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+	styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
+/>
+```
+
+<!-- /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. `styles.values.select` labels another point instead - or besides: `'first'`, `'min'`, `'max'`, or a list such as `['first', 'last']`.
+- 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.
+- `styles.curve` joins the points with another curve than the straight one: `'step'`, `'step-after'` and `'step-before'` draw stairs (a step plot), `'monotone-x'`, `'basis'` and `'catmull-rom'` smooth the line. The default is `'auto'` (straight segments), which `line.curve` in the [configuration](../../theming.md) sets for every line. There is no separate step plot: it is this one.
+- `segments` style ranges of a line; `markers` add `delta`, `rule`, `text` and the rest (see [Markers](../../markers.md)).
+
+## Step lines
+
+A step plot suits a value that holds until something changes it (a rate, a price list, a life table). `styles.curve` takes any svelteplot curve; `'step-after'` holds each value until the next point, `'step-before'` reaches it at the previous one and `'step'` changes halfway.
+
+<!-- example: examples/LineStep.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { LIFE } from './datasets';
+</script>
+
+<!-- A step plot is a line plot with a step curve: each life table holds its value until the next one. -->
+<LinePlot
+	width={720}
+	height={380}
+	data={LIFE}
+	x="year"
+	y="value"
+	color="sex"
+	scales={{ x: { edgeTicks: true } }}
+	styles={{ curve: 'step-after' }}
+/>
+```
+
+<!-- /example -->
+
+![A line plot drawn as steps](../../images/line-step.png)
+
+A segment's own `curve` wins over `styles.curve`, so one stretch of a line can step while the rest stays straight.
+
+<!-- example: examples/LineStepSegment.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { LIFE } from './datasets';
+</script>
+
+<!-- A segment sets its own curve: the female line is straight until 1980 and steps from then on. -->
+<LinePlot
+	width={720}
+	height={380}
+	data={LIFE}
+	x="year"
+	y="value"
+	color="sex"
+	scales={{ x: { edgeTicks: true } }}
+	segments={{
+		female: [{ areas: [{ x: { from: 1980 } }], styles: { curve: 'step-after' } }]
+	}}
+/>
+```
+
+<!-- /example -->
+
+![A line plot with one stepped segment](../../images/line-step-segment.png)