@fundar/data-chart-telling 0.0.64 → 1.1.0

package/docs/markers.md

@@ -0,0 +1,117 @@
+# Markers
+
+`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 './data';
+</script>
+
+<!-- Markers add marks to a plot: a hover highlight, a reference rule and a delta between two series. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={LIFE}
+	x="year"
+	y="value"
+	color="sex"
+	scales={{ x: { edgeTicks: true } }}
+	markers={[
+		{ type: 'hover' },
+		{ type: 'rule', axis: 'x', value: 2001, styles: { stroke: '#999', strokeDasharray: '4 4' } },
+		{
+			type: 'delta',
+			axis: 'x',
+			at: 1980,
+			from: { type: 'series', series: 'female' },
+			to: { type: 'series', series: 'male' },
+			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.
+
+## Fields every marker shares
+
+| 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                                                                                                                                     |
+| `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                                                                                                                                                                        |
+| `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)                                                                        |
+
+## Hover highlight
+
+`{ type: 'hover' }` draws a crosshair, a dot and a label at the hovered point. It makes the plot hoverable on its own; add `tooltip` for a floating box too. Fields: `strategy`, `sync`, `ruleX`, `ruleY`, `areaX`, `areaY` (a band highlight on band scales), `showLabels`, `format`, and the styles `rule`, `area`, `dot`, `text`. See [Tooltip and hover](tooltip-and-hover.md).
+
+## Custom components
+
+`{ type: 'component', component: MyMark, props: { ... } }` mounts a Svelte component inside the plot's SVG. It can read the plot it is in with [`usePlot()`](state.md), so it can draw from the plot's scales, margins, hover and rows.
+
+```svelte
+<!-- HoverReadout.svelte -->
+<script lang="ts">
+	import { usePlot } from '@fundar/data-chart-telling';
+	const plot = usePlot();
+	const point = $derived(plot.hover.activePoint);
+</script>
+
+<text x={plot.margins.left + 8} y={plot.margins.top + 16}>
+	{point ? `${point.series} at ${point.x}: ${point.label}` : 'Hover the plot'}
+</text>
+```
+
+```svelte
+<LinePlot
+	...
+	tooltip
+	markers={[{ type: 'hover' }, { type: 'component', component: HoverReadout }]}
+/>
+```
+
+## Markers on maps
+
+`GeoPlot` accepts `dot` and `text` plus map-specific markers: `graticule`, `sphere`, `vector`, `link`, `contour`, `inset`, `geo-hover` and `geo-component`. They are described in [Maps](geo.md#markers).

package/docs/plots.md

@@ -0,0 +1,284 @@
+# Plots
+
+Nine plot kinds share one set of props (see [Concepts](concepts.md)). They differ in what they draw, which channels they need and how they hover.
+
+| Plot                              | Draws                                   | Needs                                           |
+| --------------------------------- | --------------------------------------- | ----------------------------------------------- |
+| [`LinePlot`](#lineplot)           | A line per series                       | `x`, `y`                                        |
+| [`AreaPlot`](#areaplot)           | A filled area per series                | `x`, `y`                                        |
+| [`BarPlot`](#barplot)             | Bars, grouped, stacked or horizontal    | a category channel and a value channel          |
+| [`HistogramPlot`](#histogramplot) | Counts of a numeric field in bins       | `x` or `y`                                      |
+| [`BoxPlot`](#boxplot)             | The distribution of values per category | a category channel and a value channel          |
+| [`HeatmapPlot`](#heatmapplot)     | A grid of colored cells                 | `x`, `y`, `color`                               |
+| [`PyramidPlot`](#pyramidplot)     | Two series mirrored around zero         | a category channel, a value channel, two series |
+| [`ScatterPlot`](#scatterplot)     | A point per row                         | `x`, `y`                                        |
+| [`GeoPlot`](#geoplot)             | A map from GeoJSON or TopoJSON          | `data` (see [Maps](geo.md))                     |
+
+All of them accept `data` with `grouping`/`color`, or pre-built `series`.
+
+## LinePlot
+
+One line per series. Rows with a missing value (`null`, `undefined`, `NaN`) break the line; `styles.gaps` can [bridge the break](styles-and-segments.md#gaps).
+
+<!-- example: examples/LineDates.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- A line per commodity over a date axis, with end-of-line labels. -->
+<LinePlot
+	width={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.
+- Hover finds the points sharing the hovered `x`.
+- With a [`timeline`](timeline.md), the line reveals itself up to the current step and interpolates `y` between steps.
+- `segments` style ranges of a line; `markers` add `delta`, `rule`, `text` and the rest (see [Markers](markers.md)).
+
+## AreaPlot
+
+One filled area per series, under the line from `y` to the baseline. Default fill opacity comes from `area.fillOpacity` in the configuration.
+
+<!-- example: examples/StackedArea.svelte -->
+
+```svelte
+<script lang="ts">
+	import { AreaPlot } from '@fundar/data-chart-telling';
+	import { AGE_SHARES } from './data';
+</script>
+
+<!-- Each age group's share of the population, stacked with `stackY` so the bands add up to 100%. -->
+<AreaPlot
+	width={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.
+
+## BarPlot
+
+Bars where one axis holds the categories and the other the values. Categories on `x` give vertical bars; categories on `y` give horizontal bars.
+
+<!-- example: examples/GroupedBars.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './data';
+</script>
+
+<!-- Vertical bars, grouped by `color`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="province"
+	y="value"
+	color="sex"
+	scales={{ y: { domain: [70, 85] } }}
+/>
+```
+
+<!-- /example -->
+
+![Vertical grouped bars](images/grouped-bars.png)
+
+<!-- example: examples/HorizontalBars.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './data';
+</script>
+
+<!-- Horizontal bars: the categories go on `y`, the values on `x`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="value"
+	y="province"
+	color="sex"
+	scales={{ x: { domain: [70, 85] } }}
+/>
+```
+
+<!-- /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.
+
+## HistogramPlot
+
+Bins the rows of each series along one axis and draws the count per bin. Give `x` alone for vertical bars or `y` alone for horizontal bars.
+
+<!-- example: examples/Histogram.svelte -->
+
+```svelte
+<script lang="ts">
+	import { HistogramPlot } from '@fundar/data-chart-telling';
+	import { HEIGHTS } from './data';
+</script>
+
+<!-- Two overlapping distributions, one per `grouping` value. -->
+<HistogramPlot
+	width={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.
+
+## BoxPlot
+
+Summarizes the values of each series per category as a box: it spans the middle half of the values (25th to 75th percentile), the line across it is the median, the whiskers reach the farthest values within 1.5 times the box's height, and dots mark the values past them. String values on `x` stand the boxes upright; on `y` they lie sideways.
+
+<!-- example: examples/Box.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BoxPlot } from '@fundar/data-chart-telling';
+	import { HEIGHTS } from './data';
+</script>
+
+<!-- One box per group: quartiles, median, whiskers and outliers of each height distribution. -->
+<BoxPlot width={720} height={400} data={HEIGHTS} x="group" y="height" color="group" />
+```
+
+<!-- /example -->
+
+![Box plots of two height distributions](images/box.png)
+
+- `grouping` (or `color`) draws one box per group and category. Groups that share categories draw their boxes on top of each other, so split them with `facet` instead, or color by the category field itself.
+- Categories keep the order the data gives them; `scales.x.domain` (or `y`) orders them.
+- The value axis fits the values without reaching for zero; pin `scales.y.domain` to start it at zero.
+- `scales.x.paddingInner` / `paddingOuter` set how wide the boxes are; the defaults come from `box` in the [configuration](theming.md).
+- The tooltip reads one box at a time, not every value inside it: the hovered row carries `category`, `min`, `p25`, `median`, `p75`, `max`, `count` and `outliers`.
+- `segments` restyle whole categories (`areas: [{ x: { from: 'Bus', to: 'Bus' } }]`). A segment that splits one category's values draws two boxes.
+
+## HeatmapPlot
+
+A grid of cells, `x` and `y` being the categories of the columns and rows and `color` the value that colors each cell.
+
+<!-- example: examples/Heatmap.svelte -->
+
+```svelte
+<script lang="ts">
+	import { HeatmapPlot } from '@fundar/data-chart-telling';
+	import { HOUSEHOLDS } from './data';
+</script>
+
+<!-- One cell per number of rooms and of people, colored by the share of households. -->
+<HeatmapPlot width={560} height={360} data={HOUSEHOLDS} x="rooms" y="people" color="share" />
+```
+
+<!-- /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.
+
+## PyramidPlot
+
+Two series mirrored around a shared zero baseline, such as a population pyramid. Categories on `y` give horizontal bars; categories on `x` give vertical ones.
+
+<!-- example: examples/Pyramid.svelte -->
+
+```svelte
+<script lang="ts">
+	import { PyramidPlot } from '@fundar/data-chart-telling';
+	import { AGES } from './data';
+</script>
+
+<!-- A population pyramid: one side per `color` value. -->
+<PyramidPlot width={720} height={400} data={AGES} x="share" y="ageGroup" color="sex" />
+```
+
+<!-- /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.
+
+## ScatterPlot
+
+A dot per row.
+
+<!-- example: examples/Scatter.svelte -->
+
+```svelte
+<script lang="ts">
+	import { ScatterPlot } from '@fundar/data-chart-telling';
+	import { COUNTRIES } from './data';
+</script>
+
+<!-- Points sized by `r`, colored by `color` and shaped by `symbol`. -->
+<ScatterPlot
+	width={720}
+	height={420}
+	data={COUNTRIES}
+	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.
+
+## GeoPlot
+
+Draws GeoJSON or TopoJSON as a map: base features, a choropleth through `color`, per-feature `segments`, projections, camera and map-specific markers. It has its own page: [Maps](geo.md).

package/docs/scales.md

@@ -0,0 +1,95 @@
+# Scales
+
+`scales` configures how data values become positions and visual properties. It has one entry per channel.
+
+<!-- example: examples/Scales.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- Axis labels, a fixed domain with gridlines and a color per series. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+	scales={{
+		x: { label: 'Month' },
+		y: { label: 'Index (Jan 2021 = 100)', domain: [0, 600], grid: true },
+		color: {
+			scheme: {
+				'Brent oil': '#1b9e77',
+				'Natural gas': '#d95f02',
+				Coal: '#7570b3',
+				Wheat: '#e7298a'
+			}
+		}
+	}}
+/>
+```
+
+<!-- /example -->
+
+![A line plot with a labelled axis, gridlines and custom colors](images/scales.png)
+
+## Axes: `x` and `y`
+
+Each axis takes an `AxisScale`.
+
+| Field                                                                        | Meaning                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`                                                                       | `'auto'` (default), `'linear'`, `'pow'`, `'sqrt'`, `'log'`, `'symlog'`, `'time'`, `'utc'`, `'band'`, `'point'`, `'ordinal'`, `'categorical'` and the color-oriented types (`'sequential'`, `'diverging'`, `'threshold'`, ...)                                                                                                                                                                   |
+| `domain`, `range`                                                            | Explicit input and output extent                                                                                                                                                                                                                                                                                                                                                                |
+| `reverse`, `nice`, `zero`, `clamp`, `round`, `percent`                       | Direction, rounding and baseline behaviour                                                                                                                                                                                                                                                                                                                                                      |
+| `niceTolerance`                                                              | How far past a tick, as a share of the step, a domain the plot nices itself still ends on it (default `0.05`), so parts adding up to `100.2` stay at `100`. Applies to stacked and ranged axes, axes grown to cover markers or a transform's output, a bar plot's value axis and shared facet/timeline domains; `0` rounds like d3                                                              |
+| `edgeTicks`                                                                  | Ticks at the data's first and last values beside the nice ones. `false` turns them off, `true` on, `{ collision: 'drop-nice' \| 'drop-edge' \| 'extend' }` picks what happens when one crowds a nice tick. Defaults to `axis.edgeTicks.x` / `.y` in the [configuration](theming.md#edge-ticks) (on for x, off for y); ignored when the axis sets `ticks`, `tickSpacing`, `interval` or `domain` |
+| `label`, `labelAnchor`, `labelOrientation`, `labelPosition`, `titleFontSize` | The axis title (`label: false` hides it)                                                                                                                                                                                                                                                                                                                                                        |
+| `ticks`, `tickSpacing`, `tickSize`, `tickPadding`, `tickRotate`              | Tick placement and size                                                                                                                                                                                                                                                                                                                                                                         |
+| `tickFormat`                                                                 | `false`, an `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions` object, or `(d, index, ticks) => string`                                                                                                                                                                                                                                                                                  |
+| `grid`                                                                       | `true` or a stroke style for gridlines                                                                                                                                                                                                                                                                                                                                                          |
+| `axisDisplay`                                                                | `'visible'` (default), `'hidden'` (keeps the space, so aligned panels stay aligned) or `'none'`                                                                                                                                                                                                                                                                                                 |
+| `padding`, `paddingInner`, `paddingOuter`, `align`                           | Band and point spacing                                                                                                                                                                                                                                                                                                                                                                          |
+| `insetLeft`, `insetRight`, `insetTop`, `insetBottom`                         | Pixels kept free at each end                                                                                                                                                                                                                                                                                                                                                                    |
+| `interval`, `base`, `constant`, `sort`                                       | Time/discrete intervals, log base, symlog constant, category order                                                                                                                                                                                                                                                                                                                              |
+
+Number and date text defaults follow `axis.locale` and `axis.compactDisplay` in the [configuration](theming.md#locale).
+
+## Color
+
+`scales.color` configures the `color` channel (and a choropleth on a map).
+
+| Field     | Meaning                                                                                                                                                                                        |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `domain`  | `[min, max]` for a continuous value, or the list of categories                                                                                                                                 |
+| `scheme`  | A named [d3-scale-chromatic](https://d3js.org/d3-scale-chromatic) ramp (`'turbo'`, `'blues'`, `'rdylbu'`, case-insensitive), two or more colors to interpolate, or a `Record<category, color>` |
+| `pivot`   | Splits an array `scheme` into two halves meeting at this value (a diverging ramp)                                                                                                              |
+| `unknown` | Color of a value outside the mapping (default `#ccc`)                                                                                                                                          |
+
+A continuous ramp is set with `scheme: [colorA, colorB]`. Categorical colors come from the configuration's `palette` unless `scheme` is a category-to-color record.
+
+A marker can carry its own `scales.color`, independent of the plot's, so two ramps can coexist in one plot.
+
+## Grouping
+
+`scales.grouping.reverse` flips which group sorts first, such as which side of a [pyramid](plots.md#pyramidplot) a series sits on.
+
+## Opacity
+
+`scales.opacity` maps a value to an opacity: `domain` (`[min, max]` or categories), `range` (`[minOpacity, maxOpacity]` or a category-to-opacity record), `unknown`.
+
+## Symbol
+
+`scales.symbol` maps categories to shapes: `domain`, `range` (a list of `SymbolType` cycled in order, or a record), `unknown`. The default shape cycle is `symbols` in the configuration.
+
+## Radius and length
+
+`scales.r` (dot radius) and `scales.length` (vector length) take `domain: [min, max]` and `range: [minPx, maxPx]`. The radius scale is a square-root scale, so a dot's area follows its value; hand it raw values, not pre-scaled radii.
+
+## Shared and free scales
+
+[Facets](facets.md) and [timelines](timeline.md) share scales across panels or steps by default so panels stay comparable; each has an option to refit per panel or step.

package/docs/state.md

@@ -0,0 +1,71 @@
+# Reading plot state
+
+A plot's state - its hover, legend, timeline, margins, scales, rows and size - can be read from anything drawn with it, to build custom UI. Both hooks are read-only, except for the legend (series can be turned on and off) and the timeline (it can be played and moved). Call them while a component initializes; outside a plot or a figure they throw.
+
+## `useFigure()`
+
+Works anywhere inside a figure, including the `header`, `footer` and `content` snippets of a plot or composer. It returns:
+
+- `hover` - `activeX`, `activeY`, `activeSeries`, `strategy`, `sync`, `source` (the id of the plot owning the hover).
+- `legend` (or `null`) - `entries`, `range`, `off` (names of hidden series), `isOff(name)`, `turnOff(name, action)`, `turnOn(name)`, `toggle(name, action)`. `action` is `{ mode: 'dim' | 'hide' | 'omit' }`; `'omit'` removes the series and refits the axes.
+- `timeline` (or `null`) - `enabled`, `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, `controls`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`. On a timeline of dates, `steps` and `value` are `Date`s and `seekValue` takes a `Date` or a date string.
+
+A footer that toggles series through the legend:
+
+```svelte
+<!-- FigureReadout.svelte -->
+<script lang="ts">
+	import { useFigure } from '@fundar/data-chart-telling';
+
+	const figure = useFigure();
+	const series = $derived(
+		(figure.legend?.entries ?? []).flatMap((e) => (e.type === 'series' ? [e] : []))
+	);
+</script>
+
+{#each series as entry (entry.name)}
+	<button onclick={() => figure.legend?.toggle(entry.name, { mode: 'omit' })}>
+		{figure.legend?.isOff(entry.name) ? 'Show' : 'Hide'}
+		{entry.name}
+	</button>
+{/each}
+```
+
+```svelte
+{#snippet footer()}<FigureReadout />{/snippet}
+<LinePlot data={rows} x="year" y="value" color="sex" tooltip {footer} />
+```
+
+## `usePlot()`
+
+Works inside a plot - in a [`component` marker](markers.md#custom-components), which is mounted in the plot's SVG. It returns everything `useFigure()` does, plus:
+
+- `hover.points`, `hover.activePoint`, `hover.tooltip` (`visible`, `position`, `rows`) for this plot;
+- `margins`, `scales`, `axes`, `data`, `width`, `height`;
+- `svelteplot` - svelteplot's own `usePlot()` state for this plot.
+
+```svelte
+<!-- HoverReadout.svelte -->
+<script lang="ts">
+	import { usePlot } from '@fundar/data-chart-telling';
+
+	const plot = usePlot();
+	const point = $derived(plot.hover.activePoint);
+</script>
+
+<text x={plot.margins.left + 8} y={plot.margins.top + 16}>
+	{point ? `${point.series} at ${point.x}: ${point.label}` : 'Hover the plot'}
+</text>
+```
+
+```svelte
+<LinePlot
+	...
+	tooltip
+	markers={[{ type: 'hover' }, { type: 'component', component: HoverReadout }]}
+/>
+```
+
+## When to use them
+
+Reach for these instead of re-implementing a legend, a timeline control or a hover readout beside the plot: the figure already holds that state, and a widget reading it stays in step with the plot. [examples/LegendReader.svelte](../examples/LegendReader.svelte) is a runnable reader, and the Storybook group _Configuration / State_ has both patterns.