@fundar/data-chart-telling 0.0.64 → 1.0.0

package/docs/architecture.md

@@ -0,0 +1,137 @@
+# Architecture
+
+For contributors. A figure is built from a few layers, each knowing only the one below it. A public **plot** (`BarPlot`, `LinePlot`, ...) hands its kind's **defaults** to the generic **`Plot`**; `Plot` frames everything in a **`Figure`** (box, stores and chrome) and slices the data by **timeline** and **facet**. A **`PlotComposer`** reuses the same `Figure` and the same **`Grid`** that facets lay out on, so both share one implementation of the frame (title, legend, caption, theme variables, shared hover and legend toggles), of the grid (pixel tracks, labels, margin alignment) and of the cells.
+
+## Source layout
+
+| Folder (`src/lib/`) | Holds                                                                                                                                                                                                                                      |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `plots/<kind>/`     | `Plot.svelte` (public component), `defaults.ts` (the kind's options for the shared phases), `markers.ts` (the kind's marks)                                                                                                                |
+| `phases/`           | One class per pipeline phase, and `Pipeline`                                                                                                                                                                                               |
+| `layout/`           | `plot` (generic `Plot`, `Core`, `PanelRun`, public context), `figure`, `grid`, `facet`, `timeline`, `composer`, `legend`, `hover`, `tooltip`, `margins`, `coordinates`, `scales`, `styles`, `base` (`BasePlotLayout`, the svelteplot plot) |
+| `markers/`          | One component per marker type                                                                                                                                                                                                              |
+| `configuration/`    | The global config store, defaults and themes                                                                                                                                                                                               |
+| `types/`            | Every type another file imports                                                                                                                                                                                                            |
+| `utils/`            | Color, grouping, merge, interpolation and other helpers                                                                                                                                                                                    |
+
+## How a plot is built
+
+Solid arrows are "renders"; the dotted line is "builds".
+
+```mermaid
+%%{init: {"themeVariables": {"lineColor": "#8a8f98"}}}%%
+flowchart TD
+    Kind["<b>Plot.svelte</b><br/>BarPlot, LinePlot, ..."]
+    Defaults["<b>defaults.ts</b><br/>phase options, markers, hover, timeline"]
+    Plot["<b>Plot</b><br/>builds the Pipeline, one core per slice"]
+    Figure["<b>Figure</b><br/>box or grid cell, hover store, legend toggles"]
+    Chrome["<b>FigureChrome</b><br/>title, legend, caption"]
+    Timeline["<b>TimelineLayout</b>"]
+    PanelRun["<b>PanelRun</b><br/>data phases once, every panel"]
+    Facet["<b>FacetLayout</b>"]
+    Core["<b>Core</b><br/>its panel phases, or every phase"]
+    Base["<b>BasePlotLayout</b><br/>svelteplot Plot, axes, markers"]
+
+    Kind -->|core props + defaults| Plot
+    Kind -.- Defaults
+    Plot --> Figure
+    Figure -->|with chrome| Chrome
+    Figure -->|with a timeline| Timeline
+    Figure -->|without one| Facet
+    Timeline -->|with a facet| PanelRun --> Facet
+    Timeline --> Facet
+    Facet -->|one per slice| Core
+    Core --> Base
+
+    classDef public stroke-width:3px
+    class Kind,Plot public
+    linkStyle default stroke:#8a8f98,stroke-width:2px
+```
+
+1. A kind's `Plot.svelte` splits its props into chrome (`title`, `legend`, ...), `timeline`, `facet` and the core props, and renders the shared `Plot` with its `defaults` builder.
+2. `Plot` builds the kind's **`Pipeline`** once and renders a `Figure` whose body is the `TimelineLayout`, wrapping the `FacetLayout`, wrapping one `Core` per slice. Without a timeline or a facet, the one cell is the whole plot. Each facet's cell gets its scales (shared or free, per `facet.scales`) and whether its axes draw (per `facet.axes` and its edges in the grid).
+3. `FacetLayout` turns the rows into facets - one per `by` value, flowed into `columns`, or one per `rows` x `cols` combination - and places them on a `Grid`, one `GridCell` each. Every plot reports the margins it settled on; once all have, each column and row pins its widest ones, so the plot areas line up.
+4. `Core` runs the pipeline over its props and hands the result to `BasePlotLayout`, which draws the svelteplot plot, the axes and the markers.
+
+## The pipeline
+
+A `Pipeline` is an ordered list of **phase stages**, each a class in `phases/`. A kind's `defaults.ts` supplies the options each stage needs (its marks, its value labels, its hover strategy, its timeline behaviour); `Pipeline.ofAxisKind` assembles the shared stages around them. A kind that is not axis-based (the map) builds a pipeline of its own.
+
+| Phase              | Runs          | Does                                                            |
+| ------------------ | ------------- | --------------------------------------------------------------- |
+| `facet`            | once per plot | Splits rows into panels                                         |
+| `data`             | once per plot | Builds series from `data` or `series`, infers axes (`PlotAxes`) |
+| `mapping`          | once per plot | Resolves channel accessors                                      |
+| `transforms`       | once per plot | Runs the plot's `transforms` over all series                    |
+| `statistics`       | once per plot | Derives markers from `statistics`                               |
+| `sharedScales`     | once per plot | Domains the panels share                                        |
+| `scales`           | per panel     | Final scales, in the panel's box                                |
+| `styles`           | per panel     | `styles`, value labels, segments                                |
+| `markers`          | per panel     | Composes the kind's marks, author markers and value labels      |
+| `tooltip`, `hover` | per panel     | Tooltip text, hover points and strategy                         |
+
+The first six are the **data phases** (`Pipeline.DATA_PHASES`). With a facet, `Plot` runs them once over every row (`PanelRun`, reused for a timeline step or a legend that omits a series), and each panel's `Core` runs only the rest. Without a facet, one `Core` runs every phase. Stages declared out of order still run in phase order, with a warning.
+
+## Facets and the composer share one grid
+
+The dotted arrow is "reads from": each plot reports its margins to its cell and reads back the pinned ones.
+
+```mermaid
+%%{init: {"themeVariables": {"lineColor": "#8a8f98"}}}%%
+flowchart TD
+    Facet["<b>FacetLayout</b><br/>by or rows x cols"]
+    Composer["<b>PlotComposer</b><br/>layout, tags, align"]
+    Figure["<b>Figure</b><br/>its box, or a cell of the grid above"]
+    TimelineFrame["<b>TimelineFrame</b><br/>timeline gutter"]
+    Grid["<b>Grid</b><br/>pixel tracks, labels, margin alignment"]
+    Cell["<b>GridCell</b><br/>slot or inset, label above its box"]
+    Core["<b>Core</b> of each facet"]
+    Any["any plot, or a nested PlotComposer"]
+    Base["<b>BasePlotLayout</b>"]
+
+    Facet -->|grid and paginated modes| Grid
+    Composer --> Figure --> Grid
+    Figure -->|with a timeline| TimelineFrame --> Grid
+    Composer -->|children| Any
+    Any -->|its own Figure takes| Cell
+    Grid -->|places| Cell
+    Cell -->|facet| Core
+    Core --> Base
+    Base -.->|reports margins, reads pinned ones| Cell
+
+    classDef public stroke-width:3px
+    class Composer public
+    linkStyle default stroke:#8a8f98,stroke-width:2px
+```
+
+`PlotComposer` renders a `Figure` around a `Grid` (inside a `TimelineFrame` when it has a `timeline`), laid out by `layout` (`columns` or named `areas`, `widths`/`heights` weights, `gap`). Every plot drawn straight in it - or another `PlotComposer` - takes a cell through its own `Figure`: its `area`, an `inset` over it, or the next free one, with the composer's tag above it, drawn at the cell's size. Anything that is not a plot goes in a `GridCell`, which marks what it draws as placed so a plot inside takes no other cell. `layout.align` turns on the margin alignment facets use; it assumes the panels' plots draw no chrome of their own, since the grid only sees each plot's own margins.
+
+## Context
+
+Dependencies between layers go through Svelte context, so a layer never imports the one that provides what it reads:
+
+| Context         | Provided by                                                         | Read by                                                               |
+| --------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Hover store     | `Figure` (the outermost; nested figures share it)                   | every core's tooltip and hover sync                                   |
+| Legend toggles  | `Figure` (a figure with its own `legend` scopes them)               | legends and every core below                                          |
+| Timeline        | `Figure`                                                            | the plot's timeline layout, the player bar, `useFigure().timeline`    |
+| Shared timeline | `PlotComposer` with a `timeline`                                    | `Plot`, which then draws no control of its own                        |
+| Hover scope     | `GridCell` in a composer's grid, and `HoverScope` around each facet | hover sync, to tell panels and facets apart                           |
+| Grid            | `Grid`                                                              | `GridCell` (registers, gets its box and tag), `Figure` (takes a cell) |
+| Cell alignment  | `GridCell`                                                          | `BasePlotLayout` (pinned margins), `MarginReporter`                   |
+
+The public readers of that state are `useFigure()` and `usePlot()` ([Reading plot state](state.md)).
+
+## Adding a plot kind
+
+1. Define its props and state types under `types/plots/<kind>/`.
+2. Write `plots/<kind>/defaults.ts`: a builder returning the options of each phase it customises (`data`, `mapping`, `scales`, `styles`, `markers`, `hover`, `timeline`, ...).
+3. Write `plots/<kind>/Plot.svelte`: split chrome, `timeline`, `facet` and core props and render the shared `Plot` with the builder.
+4. Export it from `src/lib/index.ts`, add stories under `stories/plots/<kind>/`, tests under `tests/unit/plots/<kind>/`, and a section in [Plots](plots.md).
+
+## Conventions
+
+- A type that another file imports lives under `src/lib/types`, not in its implementation file.
+- Logic that belongs together is a class (`Margins`, `PlotAxes`, `ValueLabels`, `LegendState`), preferred over loose functions.
+- The configuration is data only (it is cloned on write); behaviour is passed through plot props.
+- Names of constructors and derivations use `build*`.

package/docs/chrome.md

@@ -0,0 +1,68 @@
+# Chrome
+
+The chrome is everything a figure draws around its plot: title, subtitle, legend, timeline player, caption. Every plot and every [composer](composer.md) takes the same chrome props.
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	title="Consumer prices"
+	subtitle="Index by division, December 2016 = 100"
+	caption="Source: national statistics office"
+	data={rows}
+	x="date"
+	y="index"
+	color="division"
+/>
+```
+
+![A plot with title, subtitle and caption](images/chrome.png)
+
+| Prop       | Type                    | Meaning                                          |
+| ---------- | ----------------------- | ------------------------------------------------ |
+| `title`    | `string`                | Heading                                          |
+| `subtitle` | `string`                | Line under the title                             |
+| `caption`  | `string`                | Note under the plot                              |
+| `header`   | `Snippet`               | Replaces `title` and `subtitle` with your markup |
+| `footer`   | `Snippet`               | Replaces `caption` with your markup              |
+| `legend`   | see [Legend](legend.md) | The legend                                       |
+| `order`    | `PlotChromeEntry[]`     | Which blocks draw, top to bottom                 |
+
+`header` and `footer` are snippets declared inside the component:
+
+```svelte
+<LinePlot ...>
+	{#snippet header()}
+		<div style="display: flex; justify-content: space-between">
+			<h3>My plot</h3>
+			<img src="/logo.svg" alt="Logo" />
+		</div>
+	{/snippet}
+
+	{#snippet footer()}
+		<small>Source: <a href="...">Dataset</a></small>
+	{/snippet}
+</LinePlot>
+```
+
+A `header` takes the place of `title` and `subtitle`, and a `footer` the place of `caption`; a component sets one or the other of each pair. Components inside the snippets can read the figure with [`useFigure()`](state.md).
+
+## Order
+
+`order` lists the blocks from top to bottom. The blocks are `'header'`, `'title'`, `'subtitle'`, `'legend'`, `'plot'`, `'timeline'` (a player bar, or a horizontal rule), `'caption'`, `'footer'` and `'divider'`.
+
+- A block left out is not drawn - except `'plot'`, which then goes last.
+- `'divider'` draws a line between the two blocks around it, and only when both are drawn. Several dividers may appear.
+- A row puts two or three blocks side by side: `'(plot, timeline)'`, `'(legend, plot)'`. The `plot` takes the width the others leave; a row without `plot` shares its width among the blocks.
+
+```svelte
+<LinePlot ... order={['title', 'subtitle', 'divider', 'legend', 'plot', 'divider', 'caption']} />
+```
+
+![Dividers placed between chrome blocks](images/chrome-order.png)
+
+The default order, from the configuration's `chrome.order`: `header`, `title`, `subtitle`, `divider`, `legend`, `plot`, `timeline`, `footer`, `caption`. It can be changed globally with `setConfiguration({ chrome: { order: [...] } })`.
+
+## Look
+
+Fonts, sizes, colors and spacing of each block come from the [configuration](theming.md): `title`, `subtitle`, `caption`, `legend`, `divider`, `spacing` and `chrome.rowGap`.

package/docs/composer.md

@@ -0,0 +1,53 @@
+# Composer
+
+`PlotComposer` puts several plots in one figure. It is a figure like any plot: it takes the same [chrome](chrome.md) (`title`, `subtitle`, `caption`, `legend`, `order`) and a `width` and `height`, and lays its children out on a grid.
+
+```svelte
+<PlotComposer
+	width={900}
+	height={560}
+	title="Three views, one figure"
+	tags="A"
+	layout={{ areas: ['a a b', 'a a c'] }}
+>
+	<LinePlot area="a" data={series} x="year" y="value" color="metric" tooltip />
+	<BarPlot area="b" data={bars} x="region" y="value" />
+	<ScatterPlot area="c" data={points} x="gdp" y="life" />
+</PlotComposer>
+```
+
+![Three plots in one figure on a named-area layout](images/composer.png)
+
+Plots drawn straight inside the composer take a cell of the grid and draw at the cell's size - they need no `width` or `height`.
+
+## Layout
+
+`layout` arranges the cells:
+
+| Field               | Meaning                                                                                                               |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `columns`           | Flow children into this many columns                                                                                  |
+| `areas`             | Named cells: one string per row, names separated by spaces, `.` for an empty cell (`['a a b', 'a a c']`)              |
+| `widths`, `heights` | Relative track sizes                                                                                                  |
+| `gap`               | Pixels between cells (default 12)                                                                                     |
+| `align`             | Line up every panel's plot area with its row and column, as facets do. Assumes the panels draw no chrome of their own |
+
+## Placing a child
+
+- `area="a"` puts a plot in a named cell of `areas`.
+- `inset={{ left, bottom, right, top }}` floats a plot over its area, as fractions of it (from the left and bottom edges) - a small map over a larger chart, say.
+- With neither, a plot takes the next free cell.
+- Anything that is not a plot goes in a `GridCell`, which takes the same placement (`area`, or `row`/`col` with `rowSpan`/`colSpan`, or `inset`) and a `label`: `<GridCell area="b">{#snippet children({ width, height })}...{/snippet}</GridCell>`.
+- A `PlotComposer` can be nested in a cell.
+
+## Tags
+
+`tags` stamps a label above each panel: `'A'` (A, B, C...), `'a'`, `'1'`, `'I'`, `'i'`, or an explicit list of strings.
+
+## Shared hover, legend and timeline
+
+- `hover={{ strategy, sync }}` sets how hover finds related points and whether one panel's hover shows in the others.
+- The legend toggles are shared: a composer with a `legend` of its own scopes the toggles to it, and turning a series off dims it in every plot.
+- `timeline={{ values, type, player, progress, ... }}` gives every panel one timeline. Plots inside with their own `timeline` follow its `progress`, and the figure draws no per-plot timeline control. The options are those of a [timeline](timeline.md), with `values` required.
+
+Everything inside can read the figure with [`useFigure()`](state.md).

package/docs/concepts.md

@@ -0,0 +1,99 @@
+# Concepts
+
+## Plots and figures
+
+A **plot** is one graph: axes and marks. Every plot is a component named after what it draws - `LinePlot`, `AreaPlot`, `BarPlot`, `HistogramPlot`, `HeatmapPlot`, `PyramidPlot`, `ScatterPlot`, `GeoPlot` (see [Plots](plots.md)).
+
+A plot is drawn inside a **figure**: the box that holds the plot together with its [chrome](chrome.md) (title, subtitle, legend, timeline, caption). Every plot component is a figure, so a plot with a `title` and a `legend` is still one component. A [`PlotComposer`](composer.md) is a figure that holds several plots.
+
+## Rows and series
+
+A plot draws from one of two data shapes, which are mutually exclusive.
+
+**Flat rows** - `data` plus the field for each channel. The plot groups the rows into series itself:
+
+```svelte
+<LinePlot data={rows} x="year" y="value" color="region" {width} {height} />
+```
+
+**Pre-built series** - `series`, an array where each series carries its own name, accessors and rows:
+
+```svelte
+<LinePlot
+	series={[
+		{ name: 'North', x: 'year', y: 'value', data: northRows },
+		{ name: 'South', x: 'year', y: 'value', data: southRows }
+	]}
+	{width}
+	{height}
+/>
+```
+
+A series' `name` is what the legend, the value labels and the tooltip show.
+
+## Channels
+
+A **channel** maps a field of each row to a visual property. Each channel takes a field name (`'region'`) or an accessor function (`(d) => d.region`).
+
+| Channel    | Maps a row to                                               | Configure with         |
+| ---------- | ----------------------------------------------------------- | ---------------------- |
+| `x`, `y`   | Position on the horizontal and vertical axis                | `scales.x`, `scales.y` |
+| `color`    | A color: categorical (one per value) or continuous (a ramp) | `scales.color`         |
+| `grouping` | Which series the row belongs to                             | `scales.grouping`      |
+| `opacity`  | A fill or stroke opacity                                    | `scales.opacity`       |
+| `symbol`   | A marker shape (categorical)                                | `scales.symbol`        |
+| `r`        | A dot radius, scaled so that area follows the value         | `scales.r`             |
+| `length`   | A vector or spike length                                    | `scales.length`        |
+
+`grouping` splits `data` into series. When it is unset, `color` groups too, so one accessor both separates and colors the series - the usual case. Pass both to group by one field and color by another:
+
+```svelte
+<ScatterPlot data={rows} x="gdp" y="life" grouping="country" color="temperature" {width} {height} />
+```
+
+`r` and `length` also accept a literal number, which is then a fixed pixel size and bypasses the scale.
+
+Details for each channel scale are in [Scales](scales.md).
+
+## Props every plot shares
+
+| Prop                                                              | Purpose                                                      | Docs                                                      |
+| ----------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
+| `width`, `height`                                                 | Pixel size of the figure (not needed inside a composer cell) | [Getting started](getting-started.md)                     |
+| `data` / `series`                                                 | The rows                                                     | above                                                     |
+| `x`, `y`, `color`, `grouping`, `opacity`, `symbol`, `r`, `length` | Channels                                                     | above                                                     |
+| `scales`                                                          | Axis and channel scales                                      | [Scales](scales.md)                                       |
+| `styles`                                                          | Value labels, frame, gap filling                             | [Styles and segments](styles-and-segments.md)             |
+| `segments`                                                        | Style ranges of the data                                     | [Styles and segments](styles-and-segments.md)             |
+| `markers`                                                         | Extra marks                                                  | [Markers](markers.md)                                     |
+| `transforms`, `statistics`                                        | Derive rows before drawing                                   | [Transforms and statistics](transforms-and-statistics.md) |
+| `margins`                                                         | Space around the plot area                                   | below                                                     |
+| `tooltip`                                                         | Floating tooltip                                             | [Tooltip and hover](tooltip-and-hover.md)                 |
+| `legend`                                                          | The legend                                                   | [Legend](legend.md)                                       |
+| `timeline`                                                        | Step through the data by a field                             | [Timeline](timeline.md)                                   |
+| `facet`                                                           | Small multiples                                              | [Facets](facets.md)                                       |
+| `title`, `subtitle`, `caption`, `header`, `footer`, `order`       | Chrome                                                       | [Chrome](chrome.md)                                       |
+
+`GeoPlot` takes the same chrome, `tooltip`, `legend`, `styles`, `segments` and `markers`, with GeoJSON in `data` instead of rows and `coordinates` in place of axes (see [Maps](geo.md)).
+
+### Margins
+
+`margins` takes `{ top, right, bottom, left }`. Each side is a number (pixels) or `'auto'`, which fits the side to what is drawn there - tick labels, axis titles, value labels. All sides are `'auto'` by default. `margins` is bindable: `bind:margins` reports the margins the plot settled on.
+
+## What is off until asked for
+
+A plot draws its marks, axes and automatic legend by default. These are switched on by a prop:
+
+| Feature                         | Switch                                                    |
+| ------------------------------- | --------------------------------------------------------- |
+| Tooltip                         | `tooltip` (`true` or an options object)                   |
+| In-plot hover highlight         | a `{ type: 'hover' }` marker                              |
+| Value labels                    | `styles={{ values: { show: true } }}`                     |
+| Toggling series from the legend | `legend={{ series: { interactive: { enabled: true } } }}` |
+| A frame around the plot area    | `styles={{ frame: true }}`                                |
+| Timeline                        | `timeline={{ accessor: 'year' }}`                         |
+| Facets                          | `facet={{ by: 'region' }}`                                |
+
+## Reading the rest of the docs
+
+Every config object is typed, and each field carries a JSDoc comment. The types exported from the package root (`AxisBasedScalesConfig`, `AxisBasedMarkersConfig`, `LegendSection`, ...) are the exact shapes, and using `satisfies` on a config object gives completion while keeping the literal type.

package/docs/development.md

@@ -0,0 +1,94 @@
+# 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, and the links and exports named in `llms.txt` and `llms-full.txt` exist.
+
+## 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 a real component in `scripts/docs-figures/figures/`, type-checked by `pnpm check` and rendered by Playwright:
+
+```bash
+pnpm docs:images               # regenerate docs/images/*.png
+pnpm docs:images tooltip scales   # only these figures
+```
+
+A figure can set `export const meta = { hover: { x, y } }` in a `<script module>` block to rest the pointer before the shot. The data is synthetic and deterministic (`scripts/docs-figures/data.ts`), and axes are set to English. `docs/images` is left out of the npm package.
+
+## 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,69 @@
+# Facets
+
+`facet` splits a plot's rows into small multiples: one panel per value of a field, each drawn with the same plot configuration.
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	data={rows}
+	x="year"
+	y="value"
+	facet={{ by: 'region', columns: 3, gap: 12 }}
+/>
+```
+
+![One panel per region](images/facets-grid.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 |
+
+```svelte
+<BarPlot ... facet={{ by: 'group', columns: 3, mode: 'carousel', visible: 2 }} />
+```
+
+![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.
+
+```svelte
+<LinePlot ... facet={{ rows: 'region', cols: 'sector', scales: 'free' }} />
+```
+
+![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.