@fundar/data-chart-telling 1.1.0 → 1.2.0

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,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.

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)

package/docs/plots/evolution/slope.md

@@ -0,0 +1,39 @@
+# SlopePlot
+
+Part of [Plots](../../plots.md).
+
+A line per series between two positions of a category axis, a dot on each end, to read how every series changed between two moments - and how they changed against one another. Its first and last points are labelled before and after the dots, spread apart where they would overlap. It is a [`LinePlot`](line.md) over a category axis, so any number of positions works, but the plot is made for two.
+
+<!-- example: examples/Slope.svelte -->
+
+```svelte
+<script lang="ts">
+	import { SlopePlot } from '@fundar/data-chart-telling';
+	import { AGE_SHARES } from './datasets';
+
+	const censuses = AGE_SHARES.filter(({ year }) => year === 1991 || year === 2022);
+</script>
+
+<!-- Each age group's share of Buenos Aires City's population between two censuses, labelled at both ends. -->
+<SlopePlot
+	width={720}
+	height={400}
+	data={censuses}
+	x="year"
+	y="share"
+	color="ageGroup"
+	styles={{ values: { show: true } }}
+/>
+```
+
+<!-- /example -->
+
+![Slope plot of the share of each age group between two censuses](../../images/slope.png)
+
+- `x` is always a category axis (a point scale, so the first and last positions reach the plot's edges), even for numbers or dates: each distinct value is a position, in the order the data gives them (`scales.x.domain` sets it).
+- `grouping` (or `color`) names the series; the legend toggles them like any other.
+- `styles.values` writes each series' first and last value (`select` picks others: `'first'`, `'last'`, `'min'`, `'max'`). Each label sits out in the margin on a lane, joined to its dot by a connector. The text is `format` of the value and series name.
+- The value axis is hidden, since the labels carry the values; `scales.y.axisDisplay: 'visible'` brings it back. It fits the values without reaching for zero; pin `scales.y.domain` to start it there.
+- The stroke width, dot radius and padding come from `slope` in the [configuration](../../theming.md); `padding` leaves room outside the first and last position. The positions sit at the plot's edges, and the margins grow to fit the labels.
+- `segments` restyle chosen series (`styles: { stroke: { strokeWidth: 4 } }`), as in a line plot.
+- The tooltip reads the position under the pointer, listing every series' value there.

package/docs/plots/evolution/sparkline.md

@@ -0,0 +1,34 @@
+# SparklinePlot
+
+Part of [Plots](../../plots.md).
+
+A small line plot to read a trend at a glance: no axes, no legend, a thin line, and a dot on each series' last point with its value beside it. It is a [`LinePlot`](line.md), so it takes the same data, `segments`, gaps and transforms; with `facet` it draws one sparkline per category, the usual way to use it.
+
+<!-- example: examples/Sparkline.svelte -->
+
+```svelte
+<script lang="ts">
+	import { SparklinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './datasets';
+</script>
+
+<!-- One sparkline per region: monthly inflation as a thin line, with its last value beside a dot. -->
+<SparklinePlot
+	width={360}
+	height={300}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	facet={{ by: 'region', columns: 1, gap: 4 }}
+/>
+```
+
+<!-- /example -->
+
+![Sparklines of monthly inflation by region](../../images/sparkline.png)
+
+- The axes are left out (`scales.x.axisDisplay` and `scales.y.axisDisplay` take `'visible'` back) and so is the legend (`legend: true` shows it). The margins are small; `margins` sets them.
+- The last point's value is `styles.values`: `format` writes its text, `show: false` leaves it out, and `select` labels other points (`'first'`, `'min'`, `'max'`).
+- The y axis fits the values without reaching for zero; pin `scales.y.domain` to compare sparklines on one scale, or share it across facets with `facet.scales: 'shared'`.
+- The line's width and the dot's radius come from `sparkline` in the [configuration](../../theming.md).
+- With a `tooltip` or a `hover` marker the sparkline answers the pointer like a line plot does.

package/docs/plots/ranking/bar.md

@@ -0,0 +1,59 @@
+# BarPlot
+
+Part of [Plots](../../plots.md).
+
+Bars where one axis holds the categories and the other the values. Categories on `x` give vertical bars; categories on `y` give horizontal bars.
+
+<!-- example: examples/GroupedBars.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './datasets';
+</script>
+
+<!-- Vertical bars, grouped by `color`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="province"
+	y="value"
+	color="sex"
+	scales={{ y: { domain: [70, 85] } }}
+/>
+```
+
+<!-- /example -->
+
+![Vertical grouped bars](../../images/grouped-bars.png)
+
+<!-- example: examples/HorizontalBars.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './datasets';
+</script>
+
+<!-- Horizontal bars: the categories go on `y`, the values on `x`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="value"
+	y="province"
+	color="sex"
+	scales={{ x: { domain: [70, 85] } }}
+/>
+```
+
+<!-- /example -->
+
+![Horizontal grouped bars](../../images/horizontal-bars.png)
+
+- Several series sharing a category sit side by side, each in its slice of the category band. The gap between them is `bar.seriesPadding` in the configuration.
+- `transforms={[{ type: 'stackY' }]}` stacks the series instead. Stacking is always `stackY`, also for horizontal bars, because the value channel is the one stacked.
+- `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.

package/docs/plots/ranking/bullet.md

@@ -0,0 +1,37 @@
+# BulletPlot
+
+Part of [Plots](../../plots.md).
+
+Per category, a bar for its value, a tick for its `target` and bands behind it - the `ranges` - that grade it: a compact way to read a measure against a goal. It is a [`BarPlot`](bar.md) with the references drawn around its bars. Categories on `x` stand the plot upright; on `y` they lie sideways.
+
+<!-- example: examples/Bullet.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BulletPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_LIFE } from './datasets';
+</script>
+
+<!-- Female life expectancy at birth by province: the bar, against a target of 80 years, over bands for under 76, 76 to 80 and over 80. -->
+<BulletPlot
+	width={720}
+	height={400}
+	data={PROVINCE_LIFE}
+	x="female"
+	y="province"
+	target={80}
+	ranges={[76, 80, 85]}
+	scales={{ x: { domain: [70, 85] } }}
+	styles={{ values: { show: true } }}
+/>
+```
+
+<!-- /example -->
+
+![Bullet plot of female life expectancy by province](../../images/bullet.png)
+
+- `target` is a field of the row, a function of it, or a number the same for every category. A row whose target is not a number has no tick.
+- `ranges` lists the upper bounds of the bands, each a field, a function or a number, in any order. Each band runs from the baseline to its bound; the smallest is the darkest, and a band is drawn over the larger ones.
+- The value axis reaches the bars, the targets and the largest range; pin `scales.x.domain` (or `y`) to start it elsewhere - the bars and bands start at its nearest end.
+- The bar is `barThickness` pixels thick, the bands `rangeWidth` in the colors of `rangeColors`, and the target tick is `targetLength` by `targetWidth` pixels, all from `bullet` in the [configuration](../../theming.md). `styles.bar` (`thickness`), `styles.ranges` (`colors`, `width`) and `styles.target` (`color`, `width`, `length`) override the bar, the bands and the tick for one plot.
+- It takes what a bar plot takes: `styles.values` writes each value (see [Scales](../../scales.md) for `sort`), `segments` restyle the bars of chosen categories, and the tooltip reads the hovered category. It draws one bar per category: for several series, use `facet`.