@fundar/data-chart-telling 0.0.64 → 1.1.0

package/docs/development.md

@@ -0,0 +1,103 @@
+# Development
+
+The repository uses [pnpm](https://pnpm.io).
+
+```bash
+pnpm install
+```
+
+## Checks
+
+| Command                   | Does                                                             |
+| ------------------------- | ---------------------------------------------------------------- |
+| `pnpm check`              | `svelte-check` over `src/`, `stories/`, `tests/` and `examples/` |
+| `pnpm lint`               | Prettier check and ESLint                                        |
+| `pnpm check:unused-types` | Finds exported types nothing uses                                |
+| `pnpm build`              | Packages the library into `dist/` with `svelte-package`          |
+
+## Git hooks
+
+[Husky](https://typicode.github.io/husky) installs the hooks on `pnpm install`:
+
+- `pre-commit` runs `pnpm lint` (Prettier check and ESLint over the whole project) and `pnpm check`.
+- `pre-push` runs `pnpm test`, the node and browser suites.
+
+`git commit --no-verify` and `git push --no-verify` skip them. `pnpm format` fixes what the Prettier check reports.
+
+## Tests
+
+```bash
+pnpm test                              # node unit tests and real-browser component tests
+pnpm vitest run --project=unit         # node only: pure logic, no browser
+pnpm vitest run --project=browser      # browser only: components in Chromium via Playwright
+pnpm test:stories                      # every story as a test (boots Storybook internally)
+```
+
+- Component tests must end in `.svelte.test.ts`; that suffix is what routes a file to the browser project.
+- Browser tests render with `vitest-browser-svelte`. A dot renders as a `<path>`, not a `<circle>`; styles live in the `style` attribute.
+- `tests/unit/docs` and `tests/unit/examples.svelte.test.ts` guard the LLM-facing docs: every example mounts, the links and exports named in `llms.txt` and `llms-full.txt` exist, and the example snippets in the Markdown match their files.
+
+## Storybook
+
+```bash
+pnpm storybook         # http://localhost:6006
+pnpm build-storybook   # static build
+```
+
+Every option has a story under `stories/`, grouped as Plots, Markers, Transforms, Channels, Layout, Composition and Configuration. A story that calls `setConfiguration` runs in its own iframe on docs pages (`docs.story.inline: false`) so it does not leak into its neighbours.
+
+## Examples and LLM docs
+
+- `examples/` holds small runnable components that import from the package name (aliased to `src/lib/index.ts` in `tsconfig.json` and `vite.config.ts`). They are type-checked by `pnpm check` and shipped in the package.
+- `llms.txt` is the index and `llms-full.txt` the single-file guide, both shipped. Update them, and add an example, when a public prop is added or changed.
+
+## Documentation figures
+
+Every screenshot in the docs is an example, rendered by Playwright to `docs/images/<name>.png` in kebab-case (`examples/LineByRegion.svelte` is `line-by-region.png`). The examples and the screenshots share one file of small real datasets, `examples/data.ts`, which names the source of each, and axes are set to English. `docs/images` is left out of the npm package.
+
+```bash
+pnpm docs:images                  # regenerate docs/images/*.png
+pnpm docs:images tooltip scales   # only these
+```
+
+`scripts/docs-figures/figures.json` lists the examples that get no screenshot (`skip`) and where the pointer rests before a shot (`meta`, e.g. `{ "hover": { "x": 330, "y": 160 } }`). The maps are the exception: their GeoJSON is too large to ship in `examples/`, so they are components of their own in `scripts/docs-figures/figures/`, importing it from `stories/`, and their snippets in `geo.md` and `styles-and-segments.md` are written by hand.
+
+The Markdown shows each example's source between `<!-- example: examples/Name.svelte -->` and `<!-- /example -->`:
+
+```bash
+pnpm docs:examples           # copy each example's source into README.md and docs/*.md
+pnpm docs:examples --check   # fail when a block is out of date
+```
+
+`tests/unit/docs/examples-sync.test.ts` runs the check, so a snippet never drifts from its example or its screenshot.
+
+## Continuous integration
+
+GitHub Actions runs on every pull request and on pushes to `main`:
+
+- `CI` lints, type-checks and builds, then runs the node and browser suites with coverage. The coverage summary is commented on the pull request, or shown in the workflow summary when it is too long, and the raw reports are uploaded as the `coverage` artifact.
+- `CodeQL` scans the code for security issues, and also runs weekly.
+
+`main` is protected: changes land through a pull request with the `CI` checks passing.
+
+## Publishing
+
+Releases are published to npm by the `Release` workflow, with [trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored in the repository.
+
+1. In a branch, bump the version and update `CHANGELOG.md`:
+
+   ```bash
+   pnpm version <major|minor|patch> --no-git-tag-version
+   ```
+
+2. Open a pull request, wait for the checks and merge it.
+3. Create a GitHub Release on `main` with the tag `v<version>`.
+
+Publishing the release runs the `Release` workflow: it checks that the tag matches `version` in `package.json`, runs lint, type check and tests, and publishes. `prepack` runs `svelte-package` and `publint`, so a publish always ships a clean build. The package ships `dist/`, `examples/`, `llms.txt` and `llms-full.txt`.
+
+To inspect what would be uploaded without publishing:
+
+```bash
+pnpm build
+pnpm pack
+```

package/docs/facets.md

@@ -0,0 +1,123 @@
+# Facets
+
+`facet` splits a plot's rows into small multiples: one panel per value of a field, each drawn with the same plot configuration.
+
+<!-- example: examples/Facets.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './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={REGION_VALUES}
+	x="date"
+	y="value"
+	facet={{ by: 'region', columns: 3, gap: 12, scales: 'shared' }}
+	tooltip={{ sync: true }}
+/>
+```
+
+<!-- /example -->
+
+![One panel per region](images/facets.png)
+
+The data phases (grouping, transforms, statistics, shared scales) run once for all panels; each panel then lays itself out in its own box. Panels share legend toggles and hover, so one legend controls them all.
+
+## One facet per value
+
+`{ by }` makes one panel per distinct value of the `by` field.
+
+| Option                   | Meaning                                                                                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `by`                     | Field (or function) to split by                                                                                                                 |
+| `values`                 | The facet values to show, in order. Default: every value, in data order                                                                         |
+| `columns`                | Panels per row: a number, or `{ desktop, mobile }`                                                                                              |
+| `mode`                   | `'grid'` (all at once, default), `'carousel'` (a few at a time with prev/next) or `'paginated'` (pages). Also `{ desktop, mobile }`             |
+| `visible`                | Carousel: how many panels show at once                                                                                                          |
+| `pageSize`               | Paginated: panels per page                                                                                                                      |
+| `navLayout`              | `'overlay'` or `'below'` the navigation buttons                                                                                                 |
+| `formatIndicator`        | `(current, total) => string` for the position badge                                                                                             |
+| `indicator`, `navButton` | Snippets replacing the badge and the buttons                                                                                                    |
+| `gap`                    | Pixels between panels                                                                                                                           |
+| `scales`                 | `'shared'` (default), `'free'`, `'free-x'`, `'free-y'`                                                                                          |
+| `axes`                   | `'all'` (default) draws every panel's axes; `'outer'` draws only the left column's y and the bottom row's x, with panels resized to equal boxes |
+
+<!-- example: examples/FacetsCarousel.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- A carousel shows `visible` panels at a time, with navigation below. -->
+<LinePlot
+	width={720}
+	height={340}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	facet={{ by: 'region', columns: 3, mode: 'carousel', visible: 2, navLayout: 'below' }}
+/>
+```
+
+<!-- /example -->
+
+![A carousel showing two panels at a time](images/facets-carousel.png)
+
+## Rows by columns
+
+`{ rows, cols }` makes one panel per combination of a row field and a column field, with each value labelled. Combinations without data stay empty. `rowValues` and `colValues` choose and order the values. A free `x` scale is shared down each column and a free `y` along each row.
+
+<!-- example: examples/FacetsRowsCols.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+
+	// Each region's value split into two sectors.
+	const SECTORS = [
+		{ sector: 'Goods', share: 0.8 },
+		{ sector: 'Services', share: 1.4 }
+	];
+	const rows = REGION_VALUES.flatMap((row) =>
+		SECTORS.map(({ sector, share }) => ({ ...row, sector, value: row.value * share }))
+	);
+</script>
+
+<!-- One panel per region and sector; `scales: 'free'` fits each panel to its own data. -->
+<LinePlot
+	width={720}
+	height={420}
+	data={rows}
+	x="date"
+	y="value"
+	facet={{ rows: 'region', cols: 'sector', scales: 'free' }}
+/>
+```
+
+<!-- /example -->
+
+![Panels for each combination of region and sector](images/facets-rows-cols.png)
+
+## Alignment
+
+Panels line up: each plot reports the margins it settled on, and once all have, every column and row pins its widest ones, so the plot areas align whatever their tick labels need.
+
+## Hover and tooltips
+
+`tooltip={{ sync: true }}` shows the hovered point in every panel, a feature for comparing the same x across panels. See [Tooltip and hover](tooltip-and-hover.md).
+
+## Facets with a timeline
+
+`facet` and [`timeline`](timeline.md) combine: each step shows its rows split into panels.
+
+## Maps
+
+`GeoPlot` takes `facet` and reads the field from each feature's `properties` (and from each marker row); features without the field are drawn in every panel.

package/docs/geo.md

@@ -0,0 +1,151 @@
+# Maps
+
+`GeoPlot` draws GeoJSON or TopoJSON as a map. It shares chrome, `tooltip`, `legend`, `segments`, `markers`, `timeline`, `facet` and `margins` with the other plots; instead of `x`/`y` axes it has a projection (`coordinates`).
+
+```svelte
+<GeoPlot
+	{width}
+	{height}
+	data={provinces}
+	featureId={(f) => String(f.properties?.nombre)}
+	color={(f) => Number(f.properties?.population)}
+	scales={{ color: { scheme: 'blues' } }}
+	coordinates={{ projection: { type: argentinaBicontinental } }}
+	tooltip={{ format: (f) => String(f.properties?.nombre) }}
+/>
+```
+
+![A choropleth map](images/plots-geo.png)
+
+## Data
+
+| Prop           | Meaning                                                                                                                                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `data`         | A GeoJSON `FeatureCollection`, an array of `Feature`s, or a TopoJSON `Topology`                                                                                                                              |
+| `object`       | Required for a `Topology`: the key under `topology.objects` to draw. Needs the optional `topojson-client` package                                                                                            |
+| `featureId`    | Accessor for each feature's stable id. Default: `feature.id ?? properties.id ?? properties.name`. It is the key of `segments`, and identifies features in hover and click                                    |
+| `color`        | `(feature) => number \| undefined` - the value of a choropleth. Features without one use `styles.fill` or their `segments`                                                                                   |
+| `excludeParts` | `(part, feature) => boolean`, where `part` is `{ centroid, geometry }` - drops geometry parts from drawing and hover (a distant territory drawn in an inset instead). `segments` still apply to what remains |
+
+## Styles
+
+`styles` for a map:
+
+| Field                   | Meaning                                                                                                                            |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `fill`, `fillOpacity`   | Base fill of features with no choropleth value or segment                                                                          |
+| `stroke`, `strokeWidth` | Base outline                                                                                                                       |
+| `tileLayer`             | A raster basemap under the features: `{ url, attribution, opacity, minZoom, maxZoom, tileSize }`. Mercator-family projections only |
+| `onFeatureClick`        | `(feature, event) => void`                                                                                                         |
+| `frame`                 | A border around the map                                                                                                            |
+
+## Scales
+
+`scales.color` configures the choropleth (domain, scheme, pivot, unknown - see [Scales](scales.md#color)); `scales.length` configures `vector` markers. A map has no `x`/`y`.
+
+## Segments
+
+Per-feature styling, keyed by feature id, with `'default'` as the baseline for every feature:
+
+```svelte
+<GeoPlot
+	...
+	segments={{
+		default: [{ styles: { fillOpacity: 0.7 } }],
+		argentina: [{ styles: { fill: '#3b82f6' } }]
+	}}
+/>
+```
+
+Style fields: `fill`, `fillOpacity`, `stroke`, `strokeWidth`.
+
+## Coordinates
+
+`coordinates` bundles the projection and the gestures.
+
+| Field        | Meaning                                                                                                                                                                                                                                                                                                                       |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `projection` | A name - `'equal-earth'` (default), `'mercator'`, `'orthographic'`, `'albers'`, `'albers-usa'`, `'azimuthal-equal-area'`, `'conic-conformal'`, `'equirectangular'`, `'stereographic'`, `'transverse-mercator'` and the other svelteplot projections - or an object `{ type, rotate, center, parallels, inset, clip, domain }` |
+| `zoom`       | `true` or `{ min, max, initial }`: wheel and pinch zoom                                                                                                                                                                                                                                                                       |
+| `pan`        | `true`: drag to pan a flat projection                                                                                                                                                                                                                                                                                         |
+| `rotate`     | `true`: drag to spin an `'orthographic'` globe                                                                                                                                                                                                                                                                                |
+| `camera`     | A declarative viewpoint (below)                                                                                                                                                                                                                                                                                               |
+
+`projection.type` can also be a custom factory. The package ships `argentinaBicontinental`, a projection fitted to Argentina's full territory (the mainland, the Antarctic sector and the islands):
+
+```svelte
+<GeoPlot ... coordinates={{ projection: { type: argentinaBicontinental } }} />
+```
+
+`projection.domain` fits the projection to a GeoJSON object (`'data'` fits to the plot's own `data`); it is also what sizes `'identity'` projections.
+
+### Camera
+
+`coordinates.camera` frames a target and animates to a new one when it changes:
+
+```svelte
+<GeoPlot
+	...
+	coordinates={{
+		projection: 'mercator',
+		camera: {
+			target: { features: ['Neuquén', 'Río Negro', 'Chubut'] },
+			zoom: 1,
+			anchor: 'middle-middle',
+			padding: 24,
+			transition: { duration: 750, easing: 'cubicOut' }
+		}
+	}}
+/>
+```
+
+![The camera framing three provinces](images/geo-camera.png)
+
+- `target`: `{ features: [ids] }`, `{ center: [lon, lat] }` or `{ bounds: geoJsonObject }`.
+- `zoom`: multiplier on the tight fit (for `center`, the pixel scale itself).
+- `anchor` and `padding`: where the framed target lands in the plot, as for insets.
+- `transition`: `duration` (ms), `easing`, a live `progress` (`0`-`1`) to drive it yourself, and `direction` (`'shortest'` or `'longest'` rotation, orthographic only).
+
+## Markers
+
+Map markers go in `markers`, like on other plots. `dot` and `text` work as on any plot; the map-specific ones:
+
+| `type`          | Draws                                                                                                                                                           |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `graticule`     | Longitude and latitude gridlines: `step`, `stepX`, `stepY`, `behind`                                                                                            |
+| `sphere`        | The globe outline (for `'orthographic'`): `styles`, `behind`                                                                                                    |
+| `vector`        | Arrows or spikes at points: `data`, `x`, `y`, `length`, `rotate`, `shape` (`'arrow'`, `'spike'`, `'arrow-filled'`), `anchor`                                    |
+| `link`          | Lines between point pairs: `data`, `x1`, `y1`, `x2`, `y2`, `curve` (`'auto'` traces great-circle arcs, `'linear'`)                                              |
+| `contour`       | Contour lines of a scalar field: `data` with `x`, `y`, `value`, or a sampler function; `thresholds`, `fill`, `stroke`, `clip` (`'land'` or `'ocean'`), `behind` |
+| `inset`         | A small, separately projected map anchored to an edge of the plot (see below)                                                                                   |
+| `geo-hover`     | Restyles the hovered feature: `styles` (an area style)                                                                                                          |
+| `geo-component` | Your own Svelte component                                                                                                                                       |
+
+### Insets
+
+An `inset` draws part of the map (or other data) in its own small panel, such as an island or a distant territory:
+
+```svelte
+<GeoPlot
+	...
+	excludeParts={(part) => part.centroid[0] > 100}
+	markers={[
+		{
+			type: 'inset',
+			location: 'bottom-right',
+			features: ['hawaii'],
+			projection: 'mercator',
+			width: 0.25,
+			height: 0.25,
+			margin: 8,
+			tooltip: { format: (f) => String(f.properties.name) }
+		}
+	]}
+/>
+```
+
+`location` is one of the 17 anchors (`'top-left'`, `'bottom-right'`, `'middle-left'`, ...); `features` filters by id from the plot's `data` (or give the inset its own `data`); `featurePartsFilter` narrows to geometry parts; `width` and `height` are fractions of the plot; an inset always fits its own content.
+
+## Tooltip and hover
+
+`tooltip` works as on other plots with the hovered feature as the row (`format: (feature) => string`, or a `content` snippet). Add `{ type: 'geo-hover' }` for an in-map highlight. Hover matches the browser's own SVG hit-testing, so a feature is hovered where it is drawn.

package/docs/getting-started.md

@@ -0,0 +1,78 @@
+# Getting started
+
+## Install
+
+```bash
+pnpm add @fundar/data-chart-telling svelte svelteplot
+```
+
+- `svelte` ^5 and `svelteplot` ^0.14 are peer dependencies.
+- `topojson-client` is an optional peer, needed only to feed [GeoPlot](geo.md) a TopoJSON `Topology`.
+- The package ships `.svelte` files, so the app builds with `@sveltejs/vite-plugin-svelte` or SvelteKit.
+- Import everything from the package root: `import { LinePlot } from '@fundar/data-chart-telling'`.
+
+## A first plot
+
+<!-- example: examples/FirstPlot.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- The smallest useful plot: rows, the fields to map and a pixel size. -->
+<LinePlot width={720} height={400} data={REGION_VALUES} x="date" y="value" color="region" />
+```
+
+<!-- /example -->
+
+![A line plot with one line per region](images/first-plot.png)
+
+- `data` is an array of flat rows, here `{ date, region, value }` from [examples/data.ts](../examples/data.ts); `x` and `y` name the fields that position each row.
+- `color="region"` splits the rows into one series per region and gives each its own color.
+- `width` and `height` are pixels.
+
+Everything else is an optional prop: `title`, `subtitle`, `caption`, `legend`, `tooltip`, `scales`, `styles`, `markers`, `timeline`, `facet`. See [Concepts](concepts.md) for the full picture.
+
+## Sizing a plot to its container
+
+A plot draws at the pixel size it is given. To fill a container or the window, bind the container's size and render the plot once both are known:
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+
+	let { rows } = $props();
+	let width = $state(0);
+	let height = $state(0);
+</script>
+
+<div style="width: 100%; height: 100vh" bind:clientWidth={width} bind:clientHeight={height}>
+	{#if width > 0 && height > 0}
+		<LinePlot {width} {height} data={rows} x="year" y="value" color="region" />
+	{/if}
+</div>
+```
+
+The runnable version is [examples/ResponsiveLine.svelte](../examples/ResponsiveLine.svelte). Inside a [composer](composer.md) cell, a plot takes the cell's size and needs no `width` or `height`.
+
+## Getting data in
+
+A plot reads plain JavaScript values. Load a CSV or JSON with whatever the app already uses, convert dates to `Date` objects (UTC midnight avoids timezone shifts) and numbers to `number`, then pass the rows:
+
+```ts
+const rows = parsed.map((r) => ({
+	date: new Date(Date.UTC(r.year, r.month - 1, 1)),
+	division: r.division,
+	index: Number(r.index)
+}));
+```
+
+Sort rows by their x field when a line should connect them in order, or add a `sort` [transform](transforms-and-statistics.md).
+
+## Next steps
+
+- [Concepts](concepts.md) - how rows, series and channels fit together.
+- [Plots](plots.md) - pick the plot kind.
+- [examples/](../examples/) - small runnable components for the common cases.

package/docs/legend.md

@@ -0,0 +1,153 @@
+# Legend
+
+A plot builds its legend from what it draws: its series, the scales its channels use, and the segments and markers that name themselves. Nothing needs configuring for the common case.
+
+## The automatic legend
+
+`legend` is unset or `true` for the automatic legend, `false` for none. The automatic legend can have these sections:
+
+| Section            | Appears when                    | Content                                    |
+| ------------------ | ------------------------------- | ------------------------------------------ |
+| series (discrete)  | the plot has several series     | one item per series, in its color and mark |
+| color (continuous) | `color` is a continuous value   | a ramp with its min and max                |
+| opacity            | `opacity` is a continuous value | a ramp fading across the opacity range     |
+| size               | `r` is mapped                   | a few dots at representative values        |
+| symbol             | `symbol` is mapped              | each category next to its shape            |
+
+Segments and markers join the series section when they carry a `legend` label:
+
+```svelte
+<LinePlot
+	...
+	segments={{
+		default: [
+			{
+				areas: [{ x: { from: 2020 } }],
+				styles: { stroke: { strokeDasharray: '4 4' } },
+				legend: 'Projection'
+			}
+		]
+	}}
+/>
+```
+
+`legend` on a segment or marker is a string, or `{ label, color, symbol, lineStyle, filled, opacity }` to override how the item looks.
+
+## Toggling series
+
+Items become clickable with `interactive` on the series section. `disabled` says what a hidden series becomes:
+
+<!-- example: examples/LegendToggle.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } 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={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	legend={{ series: { interactive: { enabled: true, disabled: { mode: 'omit' } } } }}
+>
+	{#snippet footer()}
+		<LegendReader />
+	{/snippet}
+</LinePlot>
+```
+
+<!-- /example -->
+
+![Legend items as toggles](images/legend-toggle.png)
+
+| `disabled.mode`   | A hidden series...                                                                    |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `'dim'` (default) | stays, faded (`style` sets how: opacity, fill, ...; default `legend.disabledOpacity`) |
+| `'hide'`          | becomes transparent, the axes keep its range                                          |
+| `'omit'`          | is removed and the axes refit to the rest                                             |
+
+`interactive.legendStyle` is `'badge'` (default: pills filled with the series color and an eye toggle) or `'basic'` (swatches). `showIcon` toggles the symbol in a badge.
+
+A continuous section narrows with `interactive: { enabled: true, mode: 'filter' | 'rescale' }`: drag handles trim the range, `'filter'` hides what lies outside, `'rescale'` refits the ramp.
+
+Series can be toggled from code too: `useFigure().legend` has `off`, `isOff(name)`, `toggle`, `turnOff`, `turnOn` (see [Reading plot state](state.md)).
+
+## Adjusting the automatic legend
+
+An object adjusts the automatic legend while keeping what the plots read:
+
+```ts
+legend={{
+	items: [{ name: 'Target', color: '#000', symbol: 'line' }], // appended to the series section
+	sections: [/* extra sections after the automatic ones */],
+	series: { title: 'Division', layout: { type: 'flex' } },
+	color: { title: 'Temperature', interactive: { enabled: true } },
+	opacity: { title: 'Confidence' },
+	size: { title: 'Population' },
+	symbol: { title: 'Income group' }
+}}
+```
+
+Each channel key adjusts the section that channel draws: any section field except what the plots compute (items, ranges, domains). An entry with `match` adjusts only the section whose title matches; a list of entries adjusts several.
+
+## Explicit sections
+
+A list replaces the automatic legend with exactly those sections:
+
+<!-- example: examples/LegendSections.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- An explicit legend: a discrete section of toggles and a continuous ramp. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	legend={[
+		{
+			type: 'discrete',
+			title: 'Region',
+			interactive: { enabled: true },
+			items: [
+				{ name: 'GBA', color: '#4f46e5', symbol: 'line' },
+				{ name: 'Cuyo', color: '#e6580d', symbol: 'line' },
+				{ name: 'Northwest', color: '#16a34a', symbol: 'line' }
+			]
+		},
+		{ type: 'continuous', title: 'Share', min: 0, max: 100, scheme: 'blues' }
+	]}
+/>
+```
+
+<!-- /example -->
+
+![A legend of explicit sections: discrete items and a continuous ramp](images/legend-sections.png)
+
+Section types:
+
+- `discrete` - `items` (`name`, `label`, `color`, `symbol`, `filled`, `opacity`, `lineStyle`), `columns`, `layout` (`{ type: 'vertical' }`, `{ type: 'horizontal', maxRows }` paginated, `{ type: 'flex' }`), `interactive`, `navButton`.
+- `continuous` - `min`, `max`, `colorMin`, `colorMax`, `scheme`, `pivot`, `opacity`, `ticks`, `width`, `format`, `interactive`.
+- `size` - `domain`, `range`, `values`, `color`, `filled`, `symbol`, `format`.
+- `symbol` - `items` of `{ name, symbol }`, `color`, `filled`, `layout`.
+
+## Placement and look
+
+The legend is a chrome block: `order` places it (`'legend'`, or in a row with the plot). Its fonts, gaps, swatch size and the continuous bar's geometry are `legend.*` in the [configuration](theming.md). A paginated section's prev/next arrows are replaceable with a `navButton` snippet.