@fundar/data-chart-telling 1.0.0 → 1.2.0

package/dist/utils/{symbol.js → SymbolPath.js}

@@ -1,28 +1,4 @@
 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.

package/dist/utils/SymbolScale.d.ts

@@ -0,0 +1,18 @@
+import type { SymbolScaleConfig } from '../types/layout/scales';
+import type { SymbolType } from '../types/plots/constants';
+/** A value of the symbol channel mapped to a shape. */
+export declare class SymbolScale {
+    /**
+     * 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 `OpacityScale.resolve`'s output.
+     * `defaultRange` mirrors `OpacityScale.resolve`'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.
+     */
+    static resolve(config: SymbolScaleConfig | undefined, computedDomain: string[] | undefined, defaultRange: SymbolType[]): (value: unknown) => SymbolType;
+}
+/** The package's public function name, over {@link SymbolScale.resolve}. */
+export declare const resolveSymbolScale: typeof SymbolScale.resolve;

package/dist/utils/SymbolScale.js

@@ -0,0 +1,29 @@
+/** A value of the symbol channel mapped to a shape. */
+export class SymbolScale {
+    /**
+     * 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 `OpacityScale.resolve`'s output.
+     * `defaultRange` mirrors `OpacityScale.resolve`'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.
+     */
+    static resolve(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];
+        };
+    }
+}
+/** The package's public function name, over {@link SymbolScale.resolve}. */
+export const resolveSymbolScale = SymbolScale.resolve;

package/dist/utils/color/ColorRamp.d.ts

@@ -0,0 +1,27 @@
+import type { ColorScaleConfig } from '../../types/layout/scales';
+import type { PlotStylesConfig } from '../../types/configuration/styling';
+/** A value mapped to a color: a continuous ramp between colors, or a color per category. */
+export declare class ColorRamp {
+    /** `{turbo: interpolateTurbo, blues: interpolateBlues, ...}`, built from every `interpolate*` d3-scale-chromatic export. */
+    static readonly NAMED: Readonly<Record<string, (t: number) => string>>;
+    /** Linearly maps `v` from `[min, max]` onto `[0, 1]`, clamped at both ends. */
+    static normalize(v: number, min: number, max: number): number;
+    /** A simple 2-color continuous ramp over `[min, max]`. */
+    static between(min: number, max: number, colorMin: string, colorMax: string): (v: number) => string;
+    /**
+     * Resolves a {@link ColorScaleConfig} into a `value => color` function - the
+     * one shared implementation for every level the config can appear at
+     * (`scales.color`, a `segments` entry, a marker's own `scales`).
+     * `computedDomain` is the fallback when `config.domain` is unset;
+     * `defaultScheme` is used when `config.scheme` is unset - the theme's own
+     * 2-color continuous ramp, or a discrete palette for a categorical domain
+     * (e.g. per-series identity colors).
+     */
+    static resolve(config: ColorScaleConfig | undefined, computedDomain: [number, number] | string[] | undefined, defaultScheme: NonNullable<ColorScaleConfig['scheme']>): (value: unknown) => string;
+    /**
+     * A numeric value as a color, through the configuration's default continuous ramp
+     * (a named `scheme`, else the colors `min` and `max`) unless `own` sets a scheme of its
+     * own. The configuration's `schemeRange` only trims the ramp it names.
+     */
+    static continuous(cfg: Pick<PlotStylesConfig, 'continuous'>, own: ColorScaleConfig | undefined, domain: [number, number]): (value: unknown) => string;
+}

package/dist/utils/color/ColorRamp.js

@@ -0,0 +1,120 @@
+import { interpolateRgb, piecewise } from 'd3-interpolate';
+import * as d3Chromatic from 'd3-scale-chromatic';
+import { CssColor } from './CssColor';
+/** A value mapped to a color: a continuous ramp between colors, or a color per category. */
+export class ColorRamp {
+    /** `{turbo: interpolateTurbo, blues: interpolateBlues, ...}`, built from every `interpolate*` d3-scale-chromatic export. */
+    static NAMED = Object.fromEntries(Object.entries(d3Chromatic)
+        .filter((entry) => entry[0].startsWith('interpolate'))
+        .map(([name, fn]) => [name.slice('interpolate'.length).toLowerCase(), fn]));
+    /** Linearly maps `v` from `[min, max]` onto `[0, 1]`, clamped at both ends. */
+    static normalize(v, min, max) {
+        if (v == null)
+            return 0;
+        const denom = max - min || 1;
+        return Math.max(0, Math.min(1, (v - min) / denom));
+    }
+    /** A simple 2-color continuous ramp over `[min, max]`. */
+    static between(min, max, colorMin, colorMax) {
+        let interpolator;
+        try {
+            interpolator = interpolateRgb(CssColor.resolve(colorMin), CssColor.resolve(colorMax));
+        }
+        catch {
+            return () => '#ccc';
+        }
+        return (v) => {
+            if (v == null)
+                return '#ccc';
+            return interpolator(ColorRamp.normalize(v, min, max));
+        };
+    }
+    /**
+     * Resolves a {@link ColorScaleConfig} into a `value => color` function - the
+     * one shared implementation for every level the config can appear at
+     * (`scales.color`, a `segments` entry, a marker's own `scales`).
+     * `computedDomain` is the fallback when `config.domain` is unset;
+     * `defaultScheme` is used when `config.scheme` is unset - the theme's own
+     * 2-color continuous ramp, or a discrete palette for a categorical domain
+     * (e.g. per-series identity colors).
+     */
+    static resolve(config, computedDomain, defaultScheme) {
+        const domain = config?.domain ?? computedDomain;
+        const scheme = config?.scheme ?? defaultScheme;
+        const unknown = config?.unknown ?? '#ccc';
+        if (!domain || domain.length === 0)
+            return () => unknown;
+        // A category → color map always resolves by direct lookup, regardless of domain shape.
+        if (typeof scheme === 'object' && !Array.isArray(scheme)) {
+            return (v) => (v == null ? unknown : (scheme[String(v)] ?? unknown));
+        }
+        // A named d3-scale-chromatic ramp (e.g. 'turbo') resolves straight to its own interpolator.
+        const namedInterpolator = typeof scheme === 'string' ? ColorRamp.NAMED[scheme.toLowerCase()] : undefined;
+        if (typeof scheme === 'string' && !namedInterpolator)
+            return () => unknown;
+        const [from, to] = config?.schemeRange ?? [0, 1];
+        const named = namedInterpolator && ((t) => namedInterpolator(from + t * (to - from)));
+        const resolvedScheme = namedInterpolator
+            ? undefined
+            : scheme.map(CssColor.resolve);
+        if (resolvedScheme && resolvedScheme.length === 0)
+            return () => unknown;
+        if (resolvedScheme && resolvedScheme.length === 1) {
+            const only = resolvedScheme[0];
+            return () => only;
+        }
+        // Categorical domain (explicit category list): sample the ramp evenly, one stop per category.
+        if (typeof domain[0] === 'string') {
+            const categories = domain;
+            const swatches = resolvedScheme ??
+                categories.map((_, i) => named(categories.length > 1 ? i / (categories.length - 1) : 0));
+            return (v) => {
+                if (v == null)
+                    return unknown;
+                const idx = categories.indexOf(String(v));
+                return idx < 0 ? unknown : swatches[idx % swatches.length];
+            };
+        }
+        // Continuous domain: interpolate smoothly across every scheme stop (or the named ramp directly).
+        const [lo, hi] = domain;
+        let interpolator;
+        if (namedInterpolator) {
+            interpolator = named;
+        }
+        else {
+            try {
+                interpolator = piecewise(interpolateRgb, resolvedScheme);
+            }
+            catch {
+                return () => unknown;
+            }
+        }
+        const pivot = config?.pivot;
+        const stopCount = resolvedScheme?.length ?? Infinity;
+        return (v) => {
+            if (v == null)
+                return unknown;
+            const n = Number(v);
+            if (Number.isNaN(n))
+                return unknown;
+            const t = pivot != null && stopCount >= 3
+                ? n <= pivot
+                    ? 0.5 * ColorRamp.normalize(n, lo, pivot)
+                    : 0.5 + 0.5 * ColorRamp.normalize(n, pivot, hi)
+                : ColorRamp.normalize(n, lo, hi);
+            return interpolator(t);
+        };
+    }
+    /**
+     * A numeric value as a color, through the configuration's default continuous ramp
+     * (a named `scheme`, else the colors `min` and `max`) unless `own` sets a scheme of its
+     * own. The configuration's `schemeRange` only trims the ramp it names.
+     */
+    static continuous(cfg, own, domain) {
+        const { scheme, schemeRange, min, max } = cfg.continuous;
+        const config = own?.scheme === undefined && scheme && schemeRange
+            ? { ...own, schemeRange: own?.schemeRange ?? schemeRange }
+            : own;
+        return ColorRamp.resolve({ ...config, domain }, domain, scheme ?? [min, max]);
+    }
+}

package/dist/utils/color/CssColor.d.ts

@@ -0,0 +1,19 @@
+type Rgb = [number, number, number];
+/** A CSS color string: read into its red, green and blue, and judged against another by WCAG contrast. */
+export declare class CssColor {
+    #private;
+    /** Resolves a `var(--x)` reference to its computed value; any other CSS color string passes through unchanged. */
+    static resolve(color: string): string;
+    /** Parses any CSS color syntax (hex, rgb(), oklch(), named colors, hsl(), ...) into an `[r, g, b]` (0-255) triple, or `null` if it can't be resolved. */
+    static parse(color: string): Rgb | null;
+    /** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
+    static contrastRatio(colorA: string, colorB: string): number;
+    /**
+     * The `candidates` entry with the highest WCAG contrast ratio against
+     * `background`. Defaults to plain white/black; pass a grayscale or other
+     * palette to widen the choice. Falls back to the first candidate when
+     * `background` can't be parsed.
+     */
+    static contrastText(background: string, candidates?: string[]): string;
+}
+export {};

package/dist/utils/color/CssColor.js

@@ -0,0 +1,114 @@
+import { isBrowser } from '../../stores/device';
+/** A CSS color string: read into its red, green and blue, and judged against another by WCAG contrast. */
+export class CssColor {
+    /** Resolves a `var(--x)` reference to its computed value; any other CSS color string passes through unchanged. */
+    static resolve(color) {
+        if (!isBrowser)
+            return color;
+        if (!color.startsWith('var('))
+            return color;
+        const varName = color.slice(4, -1).trim();
+        const value = getComputedStyle(document.documentElement).getPropertyValue(varName).trim();
+        return value || color;
+    }
+    /** Parses any CSS color syntax (hex, rgb(), oklch(), named colors, hsl(), ...) into an `[r, g, b]` (0-255) triple, or `null` if it can't be resolved. */
+    static parse(color) {
+        const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+        if (hex) {
+            const digits = hex[1].length === 3
+                ? hex[1]
+                    .split('')
+                    .map((c) => c + c)
+                    .join('')
+                : hex[1];
+            const num = parseInt(digits, 16);
+            return [(num >> 16) & 255, (num >> 8) & 255, num & 255];
+        }
+        const rgb = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/i.exec(color);
+        if (rgb)
+            return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+        const oklch = CssColor.#parseOklch(color);
+        if (oklch)
+            return oklch;
+        // Named colors, hsl(), and any other CSS color syntax: resolved to
+        // `rgb(...)` via the browser's computed style, then reparsed.
+        if (!isBrowser)
+            return null;
+        const el = document.createElement('div');
+        el.style.color = color;
+        document.body.appendChild(el);
+        const computed = getComputedStyle(el).color;
+        document.body.removeChild(el);
+        if (!computed || computed === color)
+            return null;
+        return CssColor.parse(computed);
+    }
+    /** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
+    static contrastRatio(colorA, colorB) {
+        const a = CssColor.parse(CssColor.resolve(colorA));
+        const b = CssColor.parse(CssColor.resolve(colorB));
+        if (!a || !b)
+            return 1;
+        const lA = CssColor.#luminance(a);
+        const lB = CssColor.#luminance(b);
+        return (Math.max(lA, lB) + 0.05) / (Math.min(lA, lB) + 0.05);
+    }
+    /**
+     * The `candidates` entry with the highest WCAG contrast ratio against
+     * `background`. Defaults to plain white/black; pass a grayscale or other
+     * palette to widen the choice. Falls back to the first candidate when
+     * `background` can't be parsed.
+     */
+    static contrastText(background, candidates = ['#ffffff', '#000000']) {
+        if (candidates.length === 0)
+            return '#000000';
+        let best = candidates[0];
+        let bestRatio = -Infinity;
+        for (const candidate of candidates) {
+            const ratio = CssColor.contrastRatio(background, candidate);
+            if (ratio > bestRatio) {
+                bestRatio = ratio;
+                best = candidate;
+            }
+        }
+        return best;
+    }
+    static #luminance([r, g, b]) {
+        const [rs, gs, bs] = [r, g, b].map((c) => {
+            const s = c / 255;
+            return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+        });
+        return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+    }
+    static #linearToSrgb8(c) {
+        const s = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+        return Math.max(0, Math.min(1, s)) * 255;
+    }
+    /**
+     * Parses `oklch(L C H)` directly instead of round-tripping through the
+     * browser's computed style: Chromium/Firefox serialize computed oklch()
+     * values back as oklch() (not rgb()), so the generic browser-fallback in
+     * {@link CssColor.parse} sees an unchanged string on the second pass and its
+     * infinite-loop guard mistakes that for a parse failure.
+     */
+    static #parseOklch(color) {
+        const match = /^oklch\(\s*([\d.]+)(%)?\s+([\d.]+)\s+([\d.]+)/i.exec(color.trim());
+        if (!match)
+            return null;
+        const L = match[2] ? Number(match[1]) / 100 : Number(match[1]);
+        const C = Number(match[3]);
+        const H = (Number(match[4]) * Math.PI) / 180;
+        const a = C * Math.cos(H);
+        const b = C * Math.sin(H);
+        const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+        const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+        const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+        const l = l_ ** 3;
+        const m = m_ ** 3;
+        const s = s_ ** 3;
+        const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+        const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+        const bl = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+        return [CssColor.#linearToSrgb8(r), CssColor.#linearToSrgb8(g), CssColor.#linearToSrgb8(bl)];
+    }
+}

package/dist/utils/color/Palette.d.ts

@@ -0,0 +1,21 @@
+import type { PaletteInput } from '../../types/configuration/styling';
+/** The categorical palette of a configuration, as a list of colors. */
+export declare class Palette {
+    /** How many colors a palette named after a continuous ramp takes, unless it says. */
+    static readonly COUNT = 8;
+    /** The color at `index` of `palette`, cycling when the index runs past its end: the default color for an unstyled series. */
+    static at(index: number, palette: string[]): string;
+    /**
+     * `input` as a list of colors: a list as it is; a name as the d3-scale-chromatic color list of
+     * that name (`'dark2'`, `'tableau10'`...) or, for a ramp (`'viridis'`, `'blues'`...), colors spread
+     * evenly along it; `{ scheme, count, schemeRange }` the same with its own count and part of the ramp.
+     * `undefined` when the name is not one of those.
+     */
+    static resolve(input: PaletteInput): string[] | undefined;
+    /** `patch` with its `palette` resolved to a list of colors, or left out (with a warning) when it names no scheme. */
+    static resolveIn<T extends {
+        palette?: PaletteInput;
+    } & Record<string, unknown>>(patch: T): Omit<T, 'palette'> & {
+        palette?: string[];
+    };
+}

package/dist/utils/color/Palette.js

@@ -0,0 +1,52 @@
+import * as d3Chromatic from 'd3-scale-chromatic';
+import { ColorRamp } from './ColorRamp';
+/** `{dark2: [...], tableau10: [...], ...}`, from every flat `scheme*` color list d3-scale-chromatic exports. */
+const DISCRETE_SCHEMES = Object.fromEntries(Object.entries(d3Chromatic)
+    .filter((entry) => entry[0].startsWith('scheme') &&
+    Array.isArray(entry[1]) &&
+    entry[1].every((color) => typeof color === 'string'))
+    .map(([name, colors]) => [name.slice('scheme'.length).toLowerCase(), colors]));
+/** The categorical palette of a configuration, as a list of colors. */
+export class Palette {
+    /** How many colors a palette named after a continuous ramp takes, unless it says. */
+    static COUNT = 8;
+    /** The color at `index` of `palette`, cycling when the index runs past its end: the default color for an unstyled series. */
+    static at(index, palette) {
+        if (palette.length === 0)
+            return 'currentColor';
+        return palette[index % palette.length];
+    }
+    /**
+     * `input` as a list of colors: a list as it is; a name as the d3-scale-chromatic color list of
+     * that name (`'dark2'`, `'tableau10'`...) or, for a ramp (`'viridis'`, `'blues'`...), colors spread
+     * evenly along it; `{ scheme, count, schemeRange }` the same with its own count and part of the ramp.
+     * `undefined` when the name is not one of those.
+     */
+    static resolve(input) {
+        if (Array.isArray(input))
+            return [...input];
+        const { scheme, count, schemeRange } = typeof input === 'string' ? { scheme: input } : input;
+        const name = scheme.toLowerCase();
+        const list = DISCRETE_SCHEMES[name];
+        if (list)
+            return count === undefined ? [...list] : list.slice(0, count);
+        const ramp = ColorRamp.NAMED[name];
+        if (!ramp)
+            return undefined;
+        const [from, to] = schemeRange ?? [0, 1];
+        const total = Math.max(1, count ?? Palette.COUNT);
+        return Array.from({ length: total }, (_, index) => ramp(from + (total > 1 ? index / (total - 1) : 0.5) * (to - from)));
+    }
+    /** `patch` with its `palette` resolved to a list of colors, or left out (with a warning) when it names no scheme. */
+    static resolveIn(patch) {
+        const { palette, ...rest } = patch;
+        if (palette === undefined)
+            return rest;
+        const colors = Palette.resolve(palette);
+        if (!colors) {
+            console.warn(`setConfiguration: palette ${JSON.stringify(palette)} is not a list of colors or a d3-scale-chromatic scheme name; the palette is left as it was.`);
+            return rest;
+        }
+        return { ...rest, palette: colors };
+    }
+}

package/dist/utils/color/index.d.ts

@@ -1,3 +1,11 @@
-export { resolveCssColor } from './cssColor';
-export { contrastRatio, contrastTextColor } from './contrast';
-export { normalize, paletteColor, makeColorScale, resolveColorScale } from './ramp';
+export { CssColor } from './CssColor';
+export { ColorRamp } from './ColorRamp';
+export { Palette } from './Palette';
+import { ColorRamp } from './ColorRamp';
+export declare const resolveCssColor: (color: string) => string;
+export declare const contrastRatio: (colorA: string, colorB: string) => number;
+export declare const contrastTextColor: (background: string, candidates?: string[]) => string;
+export declare const normalize: (v: number, min: number, max: number) => number;
+export declare const makeColorScale: (min: number, max: number, colorMin: string, colorMax: string) => (v: number) => string;
+export declare const resolveColorScale: typeof ColorRamp.resolve;
+export declare const paletteColor: (index: number, palette: string[]) => string;

package/dist/utils/color/index.js

@@ -1,3 +1,14 @@
-export { resolveCssColor } from './cssColor';
-export { contrastRatio, contrastTextColor } from './contrast';
-export { normalize, paletteColor, makeColorScale, resolveColorScale } from './ramp';
+export { CssColor } from './CssColor';
+export { ColorRamp } from './ColorRamp';
+export { Palette } from './Palette';
+import { CssColor } from './CssColor';
+import { ColorRamp } from './ColorRamp';
+import { Palette } from './Palette';
+// The package's public function names, over the classes above.
+export const resolveCssColor = (color) => CssColor.resolve(color);
+export const contrastRatio = (colorA, colorB) => CssColor.contrastRatio(colorA, colorB);
+export const contrastTextColor = (background, candidates) => CssColor.contrastText(background, candidates);
+export const normalize = (v, min, max) => ColorRamp.normalize(v, min, max);
+export const makeColorScale = (min, max, colorMin, colorMax) => ColorRamp.between(min, max, colorMin, colorMax);
+export const resolveColorScale = ColorRamp.resolve;
+export const paletteColor = (index, palette) => Palette.at(index, palette);

package/dist/utils/grouping.js

@@ -1,4 +1,4 @@
-import { resolveAccessor } from '../plots/utils/accessors';
+import { resolveAccessor } from './accessors';
 /**
  * Splits rows into ordered groups keyed by the stringified accessor value.
  * Insertion order of first appearance is preserved, which keeps colours stable

package/docs/architecture.md

@@ -127,7 +127,7 @@ The public readers of that state are `useFigure()` and `usePlot()` ([Reading plo
 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).
+4. Export it from `src/lib/index.ts`, add stories under `stories/plots/<kind>/`, tests under `tests/unit/plots/<kind>/`, and a page in `docs/plots/` with a row in the [Plots](plots.md) table.
 
 ## Conventions
 

package/docs/chrome.md

@@ -2,20 +2,30 @@
 
 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 './datasets';
+</script>
+
+<!-- A plot carries its own chrome: title, subtitle, legend and caption. -->
 <LinePlot
-	{width}
-	{height}
-	title="Consumer prices"
-	subtitle="Index by division, December 2016 = 100"
-	caption="Source: national statistics office"
-	data={rows}
+	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="division"
+	color="commodity"
 />
 ```
 
+<!-- /example -->
+
 ![A plot with title, subtitle and caption](images/chrome.png)
 
 | Prop       | Type                    | Meaning                                          |
@@ -55,10 +65,31 @@ A `header` takes the place of `title` and `subtitle`, and a `footer` the place o
 - `'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
-<LinePlot ... order={['title', 'subtitle', 'divider', 'legend', 'plot', 'divider', 'caption']} />
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './datasets';
+</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: [...] } })`.

package/docs/composer.md

@@ -2,20 +2,36 @@
 
 `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_AT_2007 } from './datasets';
+</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={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" />
+	<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_AT_2007} 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`.

package/docs/concepts.md

@@ -2,7 +2,7 @@
 
 ## 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 one graph: axes and marks. Every plot is a component named after what it draws, such as `LinePlot` or `BarPlot` (see [Plots](plots.md) for all of them).
 
 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.