@fundar/data-chart-telling 0.0.63 → 1.0.0

package/docs/theming.md

@@ -0,0 +1,215 @@
+# Theming
+
+The whole package reads its styling - fonts, colors, spacing, the legend, tooltip, axes, plot geometry - from one global, reactive configuration. Changing it re-themes every plot on screen; nothing is passed prop by prop.
+
+```ts
+import {
+	setConfiguration,
+	getConfiguration,
+	resetConfiguration,
+	THEMES
+} from '@fundar/data-chart-telling';
+
+setConfiguration(THEMES.Editorial); // a ready-made theme
+
+setConfiguration({
+	font: '"Inter", sans-serif',
+	palette: ['#4f46e5', '#e6580d', '#16a34a'],
+	legend: { continuous: { label: { size: '0.8125rem', weight: 400 } } }
+});
+
+getConfiguration(); // the live, merged configuration
+resetConfiguration(); // back to the shipped defaults
+```
+
+- `setConfiguration` takes a deep-partial patch and deep-merges it into the current configuration: name only the leaves to change. It is reactive, so mounted plots update.
+- Call it once at startup, or when the theme switches. It is global, not per plot; a plot's own props (`styles`, `scales`, a legend section's `format`, ...) always win over it.
+- The configuration is cloned when stored, so it holds data only: numbers, strings, arrays, objects. Functions belong in plot props such as `format` and `tickFormat`.
+- When `setConfiguration` runs inside an `$effect`, wrap the call in `untrack` so the effect does not re-trigger itself.
+- `THEMES` holds `Default`, `Editorial`, `Dark` and `Compact`; each is a patch for `setConfiguration`.
+- The complete shape is the type `PlotStylesConfig` (patches: `PlotStylesConfigInput`); the shipped values are `DEFAULT_CONFIG`.
+
+## Sections
+
+| Key                                                      | Controls                                                                                                                                                         |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `font`, `color`, `background`                            | Base text of every figure                                                                                                                                        |
+| `palette`                                                | Categorical series colors, in order                                                                                                                              |
+| `symbols`                                                | Shape cycle for the `symbol` channel                                                                                                                             |
+| `continuous`                                             | Default ramp endpoints, label color and opacity range for continuous color and opacity                                                                           |
+| `spacing`, `chrome`                                      | Padding around header, legend and caption; the chrome `order` and `rowGap`                                                                                       |
+| `title`, `subtitle`, `caption`                           | Text blocks: `font`, `size`, `weight`, `color`, `leading`, `spacing`                                                                                             |
+| `divider`                                                | The line a `'divider'` in the chrome `order` draws                                                                                                               |
+| `legend`                                                 | Text, gaps, swatches, `disabledOpacity`, paginated nav buttons, the continuous bar, its handles, ticks and labels, and the `seriesTitle` and `sizeScale` options |
+| `axis`                                                   | Axis color, font and tick sizes, `grid`, and the number locale (below)                                                                                           |
+| `tooltip`                                                | Tooltip background, color, font size, padding, radius, border                                                                                                    |
+| `margins`                                                | Default margin per side (`'auto'` or a number)                                                                                                                   |
+| `line`, `area`, `bar`, `pyramid`, `histogram`, `scatter` | Per-kind defaults: stroke width, dot radius, series padding, gap fills, fill opacity, inset                                                                      |
+| `text`                                                   | `declutter` geometry of value labels and connectors                                                                                                              |
+| `hover`                                                  | Look of the hover marker: `rule`, `dot`, `font`, `area`                                                                                                          |
+| `timeline`                                               | The rule (`rule`) and the player bar (`player`: controls, speeds, `stepDuration`, button, track, thumb, toggle)                                                  |
+| `facet`                                                  | The position badge and prev/next buttons                                                                                                                         |
+| `frameClip`                                              | Tolerance for clipping marks to the plot frame                                                                                                                   |
+
+## Locale
+
+`axis.locale` (default `'es-AR'`) and `axis.compactDisplay` (`'short'` or `'long'`, default `'short'`) set how the automatic tick formatter writes numbers - the one used by any axis without its own `scales.x`/`scales.y.tickFormat`. A legend's size section writes its values the same way. Whether an axis abbreviates at all stays svelteplot's call, based on its value range; these two choose the wording once it does.
+
+```ts
+setConfiguration({ axis: { locale: 'en-US', compactDisplay: 'long' } });
+```
+
+`axis.locale` updates plots already on screen. `axis.compactDisplay` is read when a plot mounts, so a later change shows on the next mount.
+
+## CSS variables
+
+Some fields reach the DOM as CSS custom properties, which every figure sets on its root element and the components read with a fallback. Those can also be overridden with plain CSS on a wrapping element for a one-off, non-reactive tweak:
+
+```css
+.my-dashboard {
+	--dct-tooltip-bg: #0b3d2e;
+	--dct-title-size: 2rem;
+}
+```
+
+The remaining fields are plain values read by plot code (palette, tick sizes, margins, per-kind geometry, hover look); `setConfiguration` is the way to change those.
+
+The text blocks map `title`, `subtitle` and `caption` to `--dct-{block}-{font|size|weight|color|leading|spacing}`. Every other variable and the configuration path it comes from:
+
+### base
+
+| CSS variable | Config path  |
+| ------------ | ------------ |
+| `--dct-font` | `font`       |
+| `--dct-fg`   | `color`      |
+| `--dct-bg`   | `background` |
+
+### spacing
+
+| CSS variable        | Config path              |
+| ------------------- | ------------------------ |
+| `--dct-header-pad`  | `spacing.headerPadding`  |
+| `--dct-legend-pad`  | `spacing.legendPadding`  |
+| `--dct-caption-pad` | `spacing.captionPadding` |
+| `--dct-bleed`       | `spacing.bleed`          |
+
+### divider
+
+| CSS variable           | Config path      |
+| ---------------------- | ---------------- |
+| `--dct-divider-color`  | `divider.color`  |
+| `--dct-divider-width`  | `divider.width`  |
+| `--dct-divider-style`  | `divider.style`  |
+| `--dct-divider-margin` | `divider.margin` |
+
+### chrome
+
+| CSS variable    | Config path     |
+| --------------- | --------------- |
+| `--dct-row-gap` | `chrome.rowGap` |
+
+### legend
+
+| CSS variable                            | Config path                              |
+| --------------------------------------- | ---------------------------------------- |
+| `--dct-legend-font`                     | `legend.font`                            |
+| `--dct-legend-size`                     | `legend.size`                            |
+| `--dct-legend-weight`                   | `legend.weight`                          |
+| `--dct-legend-color`                    | `legend.color`                           |
+| `--dct-legend-title-size`               | `legend.titleSize`                       |
+| `--dct-legend-title-weight`             | `legend.titleWeight`                     |
+| `--dct-legend-gap`                      | `legend.gap`                             |
+| `--dct-legend-swatch`                   | `legend.swatchSize`                      |
+| `--dct-legend-size-gap`                 | `legend.sizeScale.gap`                   |
+| `--dct-legend-nav-bg`                   | `legend.navButton.background`            |
+| `--dct-legend-nav-color`                | `legend.navButton.color`                 |
+| `--dct-legend-nav-size`                 | `legend.navButton.size`                  |
+| `--dct-legend-nav-font-size`            | `legend.navButton.fontSize`              |
+| `--dct-legend-nav-disabled-opacity`     | `legend.navButton.disabledOpacity`       |
+| `--dct-continuous-handle-width`         | `legend.continuous.handle.width`         |
+| `--dct-continuous-handle-height`        | `legend.continuous.handle.height`        |
+| `--dct-continuous-handle-radius`        | `legend.continuous.handle.radius`        |
+| `--dct-continuous-handle-fill`          | `legend.continuous.handle.fill`          |
+| `--dct-continuous-handle-stroke`        | `legend.continuous.handle.stroke`        |
+| `--dct-continuous-handle-stroke-width`  | `legend.continuous.handle.strokeWidth`   |
+| `--dct-continuous-tick-color`           | `legend.continuous.tick.color`           |
+| `--dct-continuous-tick-width`           | `legend.continuous.tick.width`           |
+| `--dct-continuous-tick-length`          | `legend.continuous.tick.length`          |
+| `--dct-continuous-label-rotate`         | `legend.continuous.label.rotate`         |
+| `--dct-continuous-label-size`           | `legend.continuous.label.size`           |
+| `--dct-continuous-label-weight`         | `legend.continuous.label.weight`         |
+| `--dct-continuous-label-overlap-rotate` | `legend.continuous.label.overlap.rotate` |
+
+### axis
+
+| CSS variable       | Config path  |
+| ------------------ | ------------ |
+| `--dct-axis-color` | `axis.color` |
+
+### tooltip
+
+| CSS variable           | Config path          |
+| ---------------------- | -------------------- |
+| `--dct-tooltip-bg`     | `tooltip.background` |
+| `--dct-tooltip-color`  | `tooltip.color`      |
+| `--dct-tooltip-size`   | `tooltip.fontSize`   |
+| `--dct-tooltip-pad`    | `tooltip.padding`    |
+| `--dct-tooltip-radius` | `tooltip.radius`     |
+| `--dct-tooltip-border` | `tooltip.border`     |
+
+### timeline
+
+| CSS variable                       | Config path                               |
+| ---------------------------------- | ----------------------------------------- |
+| `--dct-timeline-axis`              | `timeline.axisColor`                      |
+| `--dct-timeline-active`            | `timeline.activeColor`                    |
+| `--dct-timeline-gap`               | `timeline.gap`                            |
+| `--dct-player-bg`                  | `timeline.player.background`              |
+| `--dct-player-color`               | `timeline.player.color`                   |
+| `--dct-player-radius`              | `timeline.player.radius`                  |
+| `--dct-player-pad`                 | `timeline.player.padding`                 |
+| `--dct-player-gap`                 | `timeline.player.gap`                     |
+| `--dct-player-size`                | `timeline.player.fontSize`                |
+| `--dct-player-weight`              | `timeline.player.fontWeight`              |
+| `--dct-player-value-width`         | `timeline.player.valueWidth`              |
+| `--dct-player-button-size`         | `timeline.player.button.size`             |
+| `--dct-player-button-bg`           | `timeline.player.button.background`       |
+| `--dct-player-button-color`        | `timeline.player.button.color`            |
+| `--dct-player-button-hover-bg`     | `timeline.player.button.hoverBackground`  |
+| `--dct-player-button-radius`       | `timeline.player.button.radius`           |
+| `--dct-player-track-height`        | `timeline.player.track.height`            |
+| `--dct-player-track-color`         | `timeline.player.track.color`             |
+| `--dct-player-track-fill`          | `timeline.player.track.fillColor`         |
+| `--dct-player-track-radius`        | `timeline.player.track.radius`            |
+| `--dct-player-thumb-size`          | `timeline.player.thumb.size`              |
+| `--dct-player-thumb-color`         | `timeline.player.thumb.color`             |
+| `--dct-player-toggle-bg`           | `timeline.player.toggle.background`       |
+| `--dct-player-toggle-color`        | `timeline.player.toggle.color`            |
+| `--dct-player-toggle-active-bg`    | `timeline.player.toggle.activeBackground` |
+| `--dct-player-toggle-active-color` | `timeline.player.toggle.activeColor`      |
+| `--dct-player-toggle-radius`       | `timeline.player.toggle.radius`           |
+| `--dct-player-toggle-size`         | `timeline.player.toggle.fontSize`         |
+| `--dct-player-toggle-pad`          | `timeline.player.toggle.padding`          |
+
+### heatmap ramp
+
+| CSS variable      | Config path             |
+| ----------------- | ----------------------- |
+| `--dct-heat-min`  | `continuous.min`        |
+| `--dct-heat-max`  | `continuous.max`        |
+| `--dct-heat-text` | `continuous.labelColor` |
+
+### facet
+
+| CSS variable                       | Config path                       |
+| ---------------------------------- | --------------------------------- |
+| `--dct-facet-indicator-bg`         | `facet.indicator.background`      |
+| `--dct-facet-indicator-color`      | `facet.indicator.color`           |
+| `--dct-facet-indicator-size`       | `facet.indicator.fontSize`        |
+| `--dct-facet-indicator-pad`        | `facet.indicator.padding`         |
+| `--dct-facet-indicator-radius`     | `facet.indicator.radius`          |
+| `--dct-facet-nav-bg`               | `facet.navButton.background`      |
+| `--dct-facet-nav-color`            | `facet.navButton.color`           |
+| `--dct-facet-nav-btn-size`         | `facet.navButton.size`            |
+| `--dct-facet-nav-font-size`        | `facet.navButton.fontSize`        |
+| `--dct-facet-nav-disabled-opacity` | `facet.navButton.disabledOpacity` |

package/docs/timeline.md

@@ -0,0 +1,94 @@
+# Timeline
+
+`timeline` steps a plot through its data by a field - usually a year or a date. Each step shows the rows of one value of that field. It draws as a **player** by default - a control bar with play, pause and a slider - or as a **rule**, a guide beside the plot that the page drives (`type: 'rule'`).
+
+```svelte
+<BarPlot
+	{width}
+	{height}
+	data={rows}
+	x="region"
+	y="value"
+	scales={{ y: { domain: [0, 100] } }}
+	timeline={{ accessor: 'year' }}
+/>
+```
+
+![A bar plot with a player bar](images/timeline-player.png)
+
+## Options
+
+| Option                             | Meaning                                                                                                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `accessor`                         | Field (or function) giving each row's step - required                                                                                                                                |
+| `type`                             | `'player'` (default) draws a control bar in the chrome; `'rule'` draws a guide with the steps written along it                                                                       |
+| `progress`                         | The position, `0`-`1`. A player keeps its own position from there on, until `progress` changes                                                                                       |
+| `values`                           | The steps, when not every distinct value of `accessor`                                                                                                                               |
+| `filterMode`                       | `'exact'` shows the rows of the current step; `'upTo'` shows every row up to it (a cumulative reveal). `LinePlot` defaults to `'upTo'`                                               |
+| `interpolate`                      | Tween values between steps so a scrub is smooth: `true`, or `{ key, value, create, progressEasing, segmentEasing }`. Line and bar plots default to interpolating their value channel |
+| `scales`                           | `'shared'` (default): axes span every step, so they hold still while scrubbing; `'free'` refits them to each step                                                                    |
+| `onprogress`, `onvalue`            | Called with the new position (`0`-`1`) and with the step it lands on                                                                                                                 |
+| `orientation`, `show`, `thickness` | A rule's direction (`'vertical'` default, beside the plot; `'horizontal'`), visibility and size                                                                                      |
+
+## Player
+
+The player is a bar in the chrome, below the plot by default, placed like any other [chrome block](chrome.md) through `order` (`'timeline'`, or a row such as `'(plot, timeline)'`).
+
+```svelte
+<LinePlot
+	...
+	timeline={{
+		accessor: 'year',
+		player: {
+			controls: ['play', 'value', 'slider', 'speed', 'loop'],
+			autoplay: true,
+			loop: true,
+			speed: 1,
+			speeds: [0.5, 1, 2],
+			stepDuration: 800,
+			format: (year) => `Year ${year}`
+		}
+	}}
+/>
+```
+
+| `player` option               | Meaning                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `controls`                    | The controls drawn, in this order: `'play'`, `'value'`, `'slider'`, `'speed'`, `'loop'`    |
+| `autoplay`                    | Start playing as soon as there are steps                                                   |
+| `loop`, `speed`               | Where the player starts; it keeps them from there and tells `onloop` / `onspeed` on change |
+| `speeds`                      | Speeds the speed control cycles through                                                    |
+| `stepDuration`                | Milliseconds per step at speed `1`                                                         |
+| `format`                      | How the current step reads in the `'value'` control                                        |
+| `onplay`, `onspeed`, `onloop` | Change callbacks                                                                           |
+
+Defaults for `controls`, `speeds` and `stepDuration` come from `timeline.player` in the [configuration](theming.md), together with the bar's colors and sizes.
+
+## Rule
+
+`type: 'rule'` draws a line with its steps written along it, beside the plot. `progress` picks the step, and the page supplies the control (a slider, a button, scroll position):
+
+```svelte
+<script lang="ts">
+	let progress = $state(0);
+</script>
+
+<input type="range" min="0" max="1" step="0.001" bind:value={progress} />
+<LinePlot ... timeline={{ accessor: 'year', type: 'rule', progress }} />
+```
+
+![A line plot revealed up to the current step, with a timeline rule](images/timeline-rule.png)
+
+A rule's look comes from `timeline.rule` in the [configuration](theming.md) (`fontSize`, `activeFontSize`, `axisWidth`, ...) and `--dct-timeline-*` variables.
+
+## Custom controls
+
+`useFigure().timeline` exposes the timeline's state and actions, to build a widget of your own in place of the player: `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`. See [Reading plot state](state.md).
+
+## One timeline for several plots
+
+A [`PlotComposer`](composer.md) with its own `timeline` drives every panel from one control; plots inside it with a `timeline` follow its `progress`.
+
+## Maps
+
+`GeoPlot` slices both its features (reading a field from each feature's `properties`) and its markers' rows; features or rows without the field are drawn in every step.

package/docs/tooltip-and-hover.md

@@ -0,0 +1,80 @@
+# Tooltip and hover
+
+A plot becomes interactive when it is given a `tooltip`, a `{ type: 'hover' }` marker, or both. Hover is shared by every plot in a figure, so it can drive the other panels of a [facet](facets.md) or [composer](composer.md).
+
+## Tooltip
+
+```svelte
+<LinePlot {width} {height} data={rows} x="year" y="value" color="region" tooltip />
+```
+
+![A tooltip and a hover highlight on the hovered point](images/tooltip.png)
+
+`tooltip` is `true` for the defaults, or an options object:
+
+| Option               | Meaning                                                                                                                                                                                       |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strategy`           | How related points are found: `'x'`, `'y'`, `'punctual'` (the exact point) or `'series'` (all points of the hovered series). Defaults per plot kind                                           |
+| `sync`               | Show the highlight in every synced plot too (default `false`)                                                                                                                                 |
+| `format`             | `(row) => string` - the tooltip text for the hovered row (`\n` breaks lines)                                                                                                                  |
+| `content`            | A snippet `{#snippet content({ rows })}` replacing the text with custom markup. It is drawn in a plain card, so the markup brings its own background, colors and spacing                      |
+| `series`             | Only these series appear in the tooltip                                                                                                                                                       |
+| `anchorX`, `anchorY` | Preferred side of the cursor: `'left' \| 'middle' \| 'right'` (default `'right'`) and `'top' \| 'middle' \| 'bottom'` (default `'bottom'`). It moves to the other side when it would overflow |
+
+```svelte
+{#snippet content({ rows })}
+	<TooltipCard
+		heading={String(rows[0].year)}
+		footer="Value by region"
+		entries={rows.map((row) => ({
+			label: row.region,
+			color: colorOf(row.region),
+			value: row.value,
+			display: String(row.value)
+		}))}
+	/>
+{/snippet}
+
+<LinePlot
+	{width}
+	{height}
+	data={rows}
+	x="year"
+	y="value"
+	color="region"
+	tooltip={{ strategy: 'x', content }}
+/>
+```
+
+![A tooltip with custom markup](images/tooltip-content.png)
+
+[examples/CustomTooltip.svelte](../examples/CustomTooltip.svelte) is the runnable version, with the card in [examples/TooltipCard.svelte](../examples/TooltipCard.svelte).
+
+The default strategy follows the plot's axes: it matches along the category (or index) axis - points sharing the hovered `x` when the value axis is vertical, sharing `y` when it is horizontal - and `punctual` (the exact point) on heatmaps and scatter plots.
+
+## In-plot hover
+
+`markers={[{ type: 'hover' }]}` draws a dashed rule, a dot and a value label at the hovered point, inside the SVG. Its look comes from `hover` in the [configuration](theming.md) and can be overridden per marker (`rule`, `dot`, `text`, `area`). On band scales `areaX` / `areaY` highlight the whole band instead of a thin rule.
+
+Use both together for the usual result:
+
+```svelte
+<LinePlot ... tooltip markers={[{ type: 'hover' }]} />
+```
+
+## Bars
+
+On a `BarPlot` a hover candidate is the bar's whole band (or its series' slice, when grouped), so the tooltip triggers anywhere along the column.
+
+## Syncing across plots
+
+- In a [facet](facets.md) or a [`PlotComposer`](composer.md), `tooltip.sync: true` (or `hover.sync` on the composer) shows the hovered point's highlight, and the tooltip, in every panel. That replication is the feature: the same x is highlighted across panels.
+- A composer's `hover={{ strategy, sync }}` sets the strategy and sync for all its panels.
+
+## Maps
+
+`GeoPlot` takes `tooltip` too (the row is the hovered feature) and the `{ type: 'geo-hover' }` marker, which restyles the hovered feature. See [Maps](geo.md).
+
+## Reading hover from code
+
+`useFigure().hover` and `usePlot().hover` expose `activeX`, `activeY`, `activeSeries`, `strategy`, `sync`, `source` and, for a plot, `points`, `activePoint` and `tooltip`. See [Reading plot state](state.md).

package/docs/transforms-and-statistics.md

@@ -0,0 +1,88 @@
+# Transforms and statistics
+
+Both derive rows from the data before drawing. A **transform** reshapes the rows themselves (stack, bin, smooth, sort, filter). A **statistic** computes a summary of the data (regression, moving average, density) and draws it as an extra mark.
+
+## Transforms
+
+`transforms` is an array of flat objects: `type` picks the transform and the other fields are its channels and options, named as in [svelteplot's transforms](https://svelteplot.dev). It exists on a plot (it then runs once over all the plot's series) and on each [marker](markers.md) (over the marker's rows).
+
+```svelte
+<!-- stacked bars -->
+<BarPlot
+	{width}
+	{height}
+	data={rows}
+	x="province"
+	y="value"
+	color="sex"
+	transforms={[{ type: 'stackY' }]}
+/>
+
+<!-- a 6-month moving average, run on the plot's rows -->
+<LinePlot
+	{width}
+	{height}
+	data={rows}
+	x="date"
+	y="index"
+	color="division"
+	transforms={[{ type: 'windowY', k: 6, reduce: 'mean' }]}
+/>
+```
+
+![Stacked bars](images/transforms-stack.png)
+
+![Lines smoothed by a moving average](images/transforms-window.png)
+
+| Family    | `type`                                                                                        | Does                                                                                                                                                                                                                             |
+| --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Stack     | `stackX`, `stackY`, `stackMosaicX`, `stackMosaicY`                                            | Cumulative stacking. Options: `offset` (`'none'`, `'wiggle'`, `'center'`, `'normalize'`, `'diverging'`), `order`, `reverse`                                                                                                      |
+| Bin       | `binX`, `binY`, `bin`                                                                         | Count or reduce rows into bins. Options: `thresholds` (a count, a list, or `'auto'`, `'scott'`, `'sturges'`, `'freedman-diaconis'`), `interval`, `domain`, `cumulative`; reducers by channel (`y: 'count'`, `fill: 'mean'`, ...) |
+| Group     | `groupX`, `groupY`, `groupZ`, `group`                                                         | Reduce rows per category with named reducers (`count`, `sum`, `mean`, `p25`, ...) or functions                                                                                                                                   |
+| Window    | `windowX`, `windowY`                                                                          | Sliding window: `k` (size), `reduce` (`'mean'`, `'median'`, `'sum'`, `'max'`, ...), `anchor`, `strict`                                                                                                                           |
+| Bollinger | `bollingerX`, `bollingerY`                                                                    | Moving average and band: `n`, `k`                                                                                                                                                                                                |
+| Normalize | `normalizeX`, `normalizeY`, `normalizeParallelX`, `normalizeParallelY`                        | Rebase to a reference: `basis` (`'first'`, `'last'`, `'min'`, `'max'`, `'mean'`, `'median'`, `'sum'`, `'deviation'`)                                                                                                             |
+| Map       | `mapX`, `mapY`                                                                                | `map`: `'cumsum'`, `'rank'`, `'quantile'` or a function                                                                                                                                                                          |
+| Interval  | `intervalX`, `intervalY`                                                                      | Turn a value into an `[x1, x2]` interval of a given size                                                                                                                                                                         |
+| Jitter    | `jitterX`, `jitterY`                                                                          | Random offset: `width`, `std`, `distribution` (`'uniform'`, `'normal'`), `seed`                                                                                                                                                  |
+| Shift     | `shiftX`, `shiftY`                                                                            | Move by `by` (a number, or a string offset)                                                                                                                                                                                      |
+| Density   | `densityX`, `densityY`                                                                        | Kernel density estimate: `kernel`, `bandwidth`                                                                                                                                                                                   |
+| Sort      | `sort`, `shuffle`, `reverse`                                                                  | Reorder rows (matters for the path a line takes and which dot lands on top)                                                                                                                                                      |
+| Filter    | `filter`                                                                                      | Keep rows a test holds for                                                                                                                                                                                                       |
+| Select    | `select`, `selectFirst`, `selectLast`, `selectMinX`, `selectMaxX`, `selectMinY`, `selectMaxY` | Keep one row per group, such as each series' last point or peak                                                                                                                                                                  |
+
+Bar stacking is always `stackY`, also for horizontal bars. A transform on a `HistogramPlot` is merged over the plot's default binning, so `{ type: 'binX', thresholds: 20 }` changes the bins and the rest stays.
+
+## Statistics
+
+`statistics` is an array of derived summaries drawn as extra marks. On a plot it computes one per series by default; on a marker it applies to that marker's own rows.
+
+```svelte
+<ScatterPlot
+	{width}
+	{height}
+	data={rows}
+	x="gdp"
+	y="life"
+	statistics={[{ type: 'regression', regressionType: 'linear', confidence: 0.95 }]}
+/>
+```
+
+![A scatter plot with a regression line and confidence band](images/statistics-regression.png)
+
+| `type`          | Draws                                                | Options                                                                                                                                                           |
+| --------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `regression`    | A fitted curve with a confidence band                | `regressionType` (`'linear'`, `'quad'`, `'poly'`, `'exp'`, `'log'`, `'pow'`, `'loess'`), `order`, `base`, `span`, `confidence` (`false` omits the band), `styles` |
+| `movingAverage` | A smoothed line                                      | `k` (required), `reduce`, `styles`                                                                                                                                |
+| `bollinger`     | Moving average and a band of `k` standard deviations | `n`, `k`, `styles`                                                                                                                                                |
+| `density`       | A 1D density curve over `x`                          | `kernel`, `bandwidth`, `styles`                                                                                                                                   |
+| `density2d`     | 2D density contour bands                             | `bandwidth`, `thresholds`, `styles`                                                                                                                               |
+| `box`           | A box plot per category                              | the options of the [`box` marker](markers.md)                                                                                                                     |
+
+Which series a statistic runs over:
+
+- omitted: one statistic per series;
+- `series: ['a', 'b']`: only the named series;
+- `pooled: true`: one statistic over all series combined.
+
+The same summaries are available as markers (`regression`, `bollinger`, `density`, `box`, ...) when more control over the mark is needed.

package/examples/BarValues.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { ROWS } from './data';
+</script>
+
+<!-- Categories on x, values on y. Swap `x` and `y` for horizontal bars. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={ROWS.filter((d) => d.year === 2023)}
+	x="region"
+	y="value"
+	styles={{ values: { show: true, anchor: 'outside' } }}
+/>

package/examples/CustomTooltip.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+	import { LinePlot, getConfiguration, paletteColor } from '@fundar/data-chart-telling';
+	import TooltipCard from './TooltipCard.svelte';
+	import { ROWS, type Row } from './data';
+
+	const { palette } = getConfiguration();
+	const regions = [...new Set(ROWS.map((d) => d.region))];
+</script>
+
+<!--
+	`content` replaces the tooltip text with your own markup, drawn in a plain
+	card: TooltipCard brings its own background, colors and spacing. It is given
+	every row the hover matched; series colors come from the configuration's palette.
+-->
+{#snippet content({ rows }: { rows: Row[] })}
+	<TooltipCard
+		heading={String(rows[0].year)}
+		footer="Value by region"
+		entries={rows.map((row) => ({
+			label: row.region,
+			color: paletteColor(regions.indexOf(row.region), palette),
+			value: row.value,
+			display: String(row.value)
+		}))}
+	/>
+{/snippet}
+
+<LinePlot
+	width={720}
+	height={400}
+	data={ROWS}
+	x="year"
+	y="value"
+	color="region"
+	tooltip={{ strategy: 'x', content }}
+	markers={[{ type: 'hover' }]}
+/>

package/examples/Facets.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { ROWS } from './data';
+</script>
+
+<!-- One panel per region, three columns, sharing scales. A tooltip with `sync` shows in every panel on purpose. -->
+<LinePlot
+	width={900}
+	height={360}
+	data={ROWS}
+	x="year"
+	y="value"
+	facet={{ by: 'region', columns: 3, gap: 12, scales: 'shared' }}
+	tooltip={{ sync: true }}
+/>

package/examples/LegendReader.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+	import { useFigure } from '@fundar/data-chart-telling';
+
+	// Call during component init, below a plot or a PlotComposer.
+	const { legend } = useFigure();
+</script>
+
+<p>Hidden series: {legend?.off.join(', ') || 'none'}</p>

package/examples/LegendToggle.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { ROWS } from './data';
+	import LegendReader from './LegendReader.svelte';
+</script>
+
+<!--
+	The automatic legend can toggle series. `mode: 'omit'` drops a hidden series
+	and refits the axes to what is left; 'dim' and 'hide' keep the axes.
+	Anything inside the figure (here, the footer) reads the toggles through
+	`useFigure().legend` - see LegendReader.
+-->
+<LinePlot
+	width={720}
+	height={400}
+	data={ROWS}
+	x="year"
+	y="value"
+	color="region"
+	legend={{ series: { interactive: { enabled: true, disabled: { mode: 'omit' } } } }}
+>
+	{#snippet footer()}
+		<LegendReader />
+	{/snippet}
+</LinePlot>

package/examples/ResponsiveLine.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { ROWS } from './data';
+
+	// A plot draws at the pixel size it is given. To fill a container (or the
+	// window), bind its size and pass it down.
+	let width = $state(0);
+	let height = $state(0);
+</script>
+
+<div class="fill" bind:clientWidth={width} bind:clientHeight={height}>
+	{#if width > 0 && height > 0}
+		<LinePlot
+			{width}
+			{height}
+			title="Value by region"
+			subtitle="Index, 2016-2023"
+			data={ROWS}
+			x="year"
+			y="value"
+			color="region"
+			scales={{
+				x: { label: 'Year', tickFormat: (d) => String(d) },
+				y: { label: 'Index' }
+			}}
+			styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
+			margins={{ right: 'auto' }}
+		/>
+	{/if}
+</div>
+
+<style>
+	.fill {
+		width: 100%;
+		height: 100vh;
+	}
+</style>

package/examples/Segments.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import type { LineSegmentStyle, SegmentsConfig } from '@fundar/data-chart-telling';
+	import { ROWS } from './data';
+
+	// `segments` maps a series name (or 'default' for all series) to its rules.
+	const segments = {
+		default: [
+			{
+				areas: [{ x: { from: 2020, to: 2023 } }],
+				styles: { stroke: { strokeDasharray: '6 4', strokeOpacity: 0.7 } }
+			}
+		]
+	} satisfies SegmentsConfig<LineSegmentStyle>;
+</script>
+
+<LinePlot width={720} height={400} data={ROWS} x="year" y="value" color="region" {segments} />