@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/utils/merge.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `patch` deep-merged over `base`: plain objects merge key by key, anything
+ * else (arrays included) in `patch` replaces, and an `undefined` in `patch`
+ * leaves `base` as it is. Either side may be absent - the other is returned.
+ */
+export declare function merge<T extends object>(base: T, patch: object | undefined): T;
+export declare function merge<T extends object>(base: T | undefined, patch: T | undefined): T | undefined;

package/dist/utils/merge.js

@@ -0,0 +1,17 @@
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function merge(base, patch) {
+    if (!base)
+        return patch;
+    if (!patch)
+        return base;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        const prev = out[key];
+        out[key] = isPlainObject(prev) && isPlainObject(value) ? merge(prev, value) : value;
+    }
+    return out;
+}

package/dist/utils/opacity.d.ts

@@ -0,0 +1,9 @@
+import type { OpacityScaleConfig } from '../types/layout/scales';
+/**
+ * Resolves an {@link OpacityScaleConfig} into a `value => opacity` function -
+ * mirrors `resolveColorScale`'s shape, but the output is always a number in
+ * roughly `[0,1]` instead of a CSS color string. Callers must apply the
+ * result as a literal constant per mark instance (never a per-row function
+ * handed straight to svelteplot) - see the type's own doc comment for why.
+ */
+export declare function resolveOpacityScale(config: OpacityScaleConfig | undefined, computedDomain: [number, number] | string[] | undefined, defaultRange: [number, number]): (value: unknown) => number;

package/dist/utils/opacity.js

@@ -0,0 +1,38 @@
+import { normalize } from './color';
+/**
+ * Resolves an {@link OpacityScaleConfig} into a `value => opacity` function -
+ * mirrors `resolveColorScale`'s shape, but the output is always a number in
+ * roughly `[0,1]` instead of a CSS color string. Callers must apply the
+ * result as a literal constant per mark instance (never a per-row function
+ * handed straight to svelteplot) - see the type's own doc comment for why.
+ */
+export function resolveOpacityScale(config, computedDomain, defaultRange) {
+    const domain = config?.domain ?? computedDomain;
+    const range = config?.range ?? defaultRange;
+    const unknown = config?.unknown ?? 1;
+    if (!domain || domain.length === 0)
+        return () => unknown;
+    if (typeof range === 'object' && !Array.isArray(range)) {
+        return (v) => (v == null ? unknown : (range[String(v)] ?? unknown));
+    }
+    if (typeof domain[0] === 'string') {
+        const categories = domain;
+        const [lo, hi] = range;
+        return (v) => {
+            if (v == null)
+                return unknown;
+            const idx = categories.indexOf(String(v));
+            if (idx < 0)
+                return unknown;
+            return categories.length > 1 ? lo + ((hi - lo) * idx) / (categories.length - 1) : lo;
+        };
+    }
+    const [dLo, dHi] = domain;
+    const [rLo, rHi] = range;
+    return (v) => {
+        if (v == null)
+            return unknown;
+        const t = normalize(Number(v), dLo, dHi);
+        return rLo + (rHi - rLo) * t;
+    };
+}

package/dist/utils/symbol.d.ts

@@ -0,0 +1,31 @@
+import type { SymbolScaleConfig } from '../types/layout/scales';
+import type { SymbolType } from '../types/plots/constants';
+/**
+ * Resolves a {@link SymbolScaleConfig} into a `value => shape` function -
+ * always a discrete category lookup, unlike every other channel here (there's
+ * no continuous case for a shape). Resolves to a plain shape-name string,
+ * which svelteplot recognizes as a literal and renders as-is - safe to hand
+ * straight to a per-row accessor, unlike `resolveOpacityScale`'s output.
+ * `defaultRange` mirrors `resolveOpacityScale`'s own required (not defaulted)
+ * parameter - callers pass the theme's own `cfg.symbols` rather than this
+ * module hardcoding a second copy of the default cycle.
+ */
+export declare function resolveSymbolScale(config: SymbolScaleConfig | undefined, computedDomain: string[] | undefined, defaultRange: SymbolType[]): (value: unknown) => SymbolType;
+/**
+ * A symbol's SVG path, as svelteplot's `dot` mark draws it: the same
+ * d3-shape symbol, sized to the area of a circle of the given radius.
+ */
+export declare class SymbolPath {
+    #private;
+    private constructor();
+    /** The path of `symbol` at `radius`, centred on the origin. */
+    static of(symbol: SymbolType, radius: number): string;
+    /** The path of `symbol`, scaled to fit and centred in a `size`-wide square from the origin. */
+    static fitted(symbol: SymbolType, size: number): string;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    closePath(): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    /** Only the full circle d3-shape's `circle` draws, from its rightmost point. */
+    arc(x: number, y: number, r: number): void;
+}

package/dist/utils/symbol.js

@@ -0,0 +1,92 @@
+import { maybeSymbol } from 'svelteplot/helpers/symbols.js';
+/**
+ * Resolves a {@link SymbolScaleConfig} into a `value => shape` function -
+ * always a discrete category lookup, unlike every other channel here (there's
+ * no continuous case for a shape). Resolves to a plain shape-name string,
+ * which svelteplot recognizes as a literal and renders as-is - safe to hand
+ * straight to a per-row accessor, unlike `resolveOpacityScale`'s output.
+ * `defaultRange` mirrors `resolveOpacityScale`'s own required (not defaulted)
+ * parameter - callers pass the theme's own `cfg.symbols` rather than this
+ * module hardcoding a second copy of the default cycle.
+ */
+export function resolveSymbolScale(config, computedDomain, defaultRange) {
+    const domain = config?.domain ?? computedDomain ?? [];
+    const range = config?.range ?? defaultRange;
+    const unknown = config?.unknown ?? 'circle';
+    if (typeof range === 'object' && !Array.isArray(range)) {
+        return (v) => (v == null ? unknown : (range[String(v)] ?? unknown));
+    }
+    return (v) => {
+        if (v == null || !domain.length)
+            return unknown;
+        const idx = domain.indexOf(String(v));
+        return idx < 0 ? unknown : range[idx % range.length];
+    };
+}
+/**
+ * A symbol's SVG path, as svelteplot's `dot` mark draws it: the same
+ * d3-shape symbol, sized to the area of a circle of the given radius.
+ */
+export class SymbolPath {
+    #d = '';
+    #bounds = { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity };
+    #k;
+    #dx;
+    #dy;
+    constructor(k = 1, dx = 0, dy = 0) {
+        this.#k = k;
+        this.#dx = dx;
+        this.#dy = dy;
+    }
+    /** The path of `symbol` at `radius`, centred on the origin. */
+    static of(symbol, radius) {
+        return SymbolPath.#draw(symbol, radius, new SymbolPath()).#d;
+    }
+    /** The path of `symbol`, scaled to fit and centred in a `size`-wide square from the origin. */
+    static fitted(symbol, size) {
+        const { x0, y0, x1, y1 } = SymbolPath.#draw(symbol, 1, new SymbolPath()).#bounds;
+        const k = size / Math.max(x1 - x0, y1 - y0);
+        const fit = new SymbolPath(k, size / 2 - (k * (x0 + x1)) / 2, size / 2 - (k * (y0 + y1)) / 2);
+        return SymbolPath.#draw(symbol, 1, fit).#d;
+    }
+    static #draw(symbol, radius, path) {
+        maybeSymbol(symbol === 'line' ? 'circle' : symbol).draw(path, radius ** 2 * Math.PI);
+        return path;
+    }
+    moveTo(x, y) {
+        this.#d += `M${this.#point(x, y)}`;
+    }
+    lineTo(x, y) {
+        this.#d += `L${this.#point(x, y)}`;
+    }
+    closePath() {
+        this.#d += 'Z';
+    }
+    rect(x, y, w, h) {
+        this.moveTo(x, y);
+        this.lineTo(x + w, y);
+        this.lineTo(x + w, y + h);
+        this.lineTo(x, y + h);
+        this.closePath();
+    }
+    /** Only the full circle d3-shape's `circle` draws, from its rightmost point. */
+    arc(x, y, r) {
+        this.#point(x, y - r);
+        this.#point(x, y + r);
+        const kr = this.#k * r;
+        const left = this.#point(x - r, y);
+        const right = this.#point(x + r, y);
+        this.#d += `A${kr},${kr},0,1,1,${left}A${kr},${kr},0,1,1,${right}`;
+    }
+    /** `x`,`y` in the output's coordinates, widening the drawn bounds. */
+    #point(x, y) {
+        const b = this.#bounds;
+        [b.x0, b.y0, b.x1, b.y1] = [
+            Math.min(b.x0, x),
+            Math.min(b.y0, y),
+            Math.max(b.x1, x),
+            Math.max(b.y1, y)
+        ];
+        return `${this.#k * x + this.#dx},${this.#k * y + this.#dy}`;
+    }
+}

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,99 @@
+# 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.
+
+<!-- example: examples/Chrome.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- A plot carries its own chrome: title, subtitle, legend and caption. -->
+<LinePlot
+	width={720}
+	height={440}
+	title="Commodity prices"
+	subtitle="Price index, January 2021 = 100"
+	caption="Source: IMF, Primary Commodity Prices"
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+/>
+```
+
+<!-- /example -->
+
+![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.
+
+<!-- example: examples/ChromeOrder.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- `order` places the chrome blocks; `divider` draws a rule between them. -->
+<LinePlot
+	width={720}
+	height={460}
+	title="Commodity prices"
+	subtitle="Price index"
+	caption="Source: IMF, Primary Commodity Prices"
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+	order={['title', 'subtitle', 'divider', 'legend', 'plot', 'divider', 'caption']}
+/>
+```
+
+<!-- /example -->
+
+![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,69 @@
+# 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.
+
+<!-- example: examples/Composer.svelte -->
+
+```svelte
+<script lang="ts">
+	import { PlotComposer, LinePlot, BarPlot, ScatterPlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES, PROVINCE_VALUES, COUNTRIES } from './data';
+</script>
+
+<!-- Several plots in one figure, placed on named areas of a grid. -->
+<PlotComposer
+	width={900}
+	height={560}
+	title="Three views, one figure"
+	legend={false}
+	tags="A"
+	layout={{ areas: ['a a b', 'a a c'] }}
+>
+	<LinePlot area="a" data={REGION_VALUES} x="date" y="value" color="region" tooltip />
+	<BarPlot
+		area="b"
+		data={PROVINCE_VALUES.filter((row) => row.sex === 'female').slice(0, 3)}
+		x="province"
+		y="value"
+	/>
+	<ScatterPlot area="c" data={COUNTRIES} x="gdp" y="life" />
+</PlotComposer>
+```
+
+<!-- /example -->
+
+![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`, `BoxPlot`, `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.