@fundar/data-chart-telling 1.1.0 → 1.2.0

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

@@ -7,7 +7,7 @@ The chrome is everything a figure draws around its plot: title, subtitle, legend
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { PRICES } from './data';
+	import { PRICES } from './datasets';
 </script>
 
 <!-- A plot carries its own chrome: title, subtitle, legend and caption. -->
@@ -70,7 +70,7 @@ A `header` takes the place of `title` and `subtitle`, and a `footer` the place o
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { PRICES } from './data';
+	import { PRICES } from './datasets';
 </script>
 
 <!-- `order` places the chrome blocks; `divider` draws a rule between them. -->

package/docs/composer.md

@@ -7,7 +7,7 @@
 ```svelte
 <script lang="ts">
 	import { PlotComposer, LinePlot, BarPlot, ScatterPlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES, PROVINCE_VALUES, COUNTRIES } from './data';
+	import { REGION_VALUES, PROVINCE_VALUES, COUNTRIES_AT_2007 } from './datasets';
 </script>
 
 <!-- Several plots in one figure, placed on named areas of a grid. -->
@@ -26,7 +26,7 @@
 		x="province"
 		y="value"
 	/>
-	<ScatterPlot area="c" data={COUNTRIES} x="gdp" y="life" />
+	<ScatterPlot area="c" data={COUNTRIES_AT_2007} x="gdp" y="life" />
 </PlotComposer>
 ```
 

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`, `BoxPlot`, `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.
 

package/docs/development.md

@@ -53,7 +53,7 @@ Every option has a story under `stories/`, grouped as Plots, Markers, Transforms
 
 ## Documentation figures
 
-Every screenshot in the docs is an example, rendered by Playwright to `docs/images/<name>.png` in kebab-case (`examples/LineByRegion.svelte` is `line-by-region.png`). The examples and the screenshots share one file of small real datasets, `examples/data.ts`, which names the source of each, and axes are set to English. `docs/images` is left out of the npm package.
+Every screenshot in the docs is an example, rendered by Playwright to `docs/images/<name>.png` in kebab-case (`examples/LineByRegion.svelte` is `line-by-region.png`). The examples and the screenshots share small real datasets, one file each in `examples/datasets/`, which name their source, and axes are set to English. `docs/images` is left out of the npm package. So are the map boundaries the stories draw: the GeoJSON files in `examples/geo/`, and the datasets in `examples/datasets/` that load them (provinces, countries, comunas, partidos), which are not in the `$datasets` barrel - import them as `$datasets/<name>`.
 
 ```bash
 pnpm docs:images                  # regenerate docs/images/*.png

package/docs/facets.md

@@ -7,7 +7,7 @@
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- One panel per region, three columns, sharing scales. A tooltip with `sync` shows in every panel on purpose. -->
@@ -52,7 +52,7 @@ The data phases (grouping, transforms, statistics, shared scales) run once for a
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- A carousel shows `visible` panels at a time, with navigation below. -->
@@ -79,7 +79,7 @@ The data phases (grouping, transforms, statistics, shared scales) run once for a
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 
 	// Each region's value split into two sectors.
 	const SECTORS = [

package/docs/getting-started.md

@@ -18,7 +18,7 @@ pnpm add @fundar/data-chart-telling svelte svelteplot
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- The smallest useful plot: rows, the fields to map and a pixel size. -->
@@ -29,7 +29,7 @@ pnpm add @fundar/data-chart-telling svelte svelteplot
 
 ![A line plot with one line per region](images/first-plot.png)
 
-- `data` is an array of flat rows, here `{ date, region, value }` from [examples/data.ts](../examples/data.ts); `x` and `y` name the fields that position each row.
+- `data` is an array of flat rows, here `{ date, region, value }` from [examples/datasets/inflation-by-region.ts](../examples/datasets/inflation-by-region.ts); `x` and `y` name the fields that position each row.
 - `color="region"` splits the rows into one series per region and gives each its own color.
 - `width` and `height` are pixels.
 

package/docs/legend.md

@@ -6,13 +6,13 @@ A plot builds its legend from what it draws: its series, the scales its channels
 
 `legend` is unset or `true` for the automatic legend, `false` for none. The automatic legend can have these sections:
 
-| Section            | Appears when                    | Content                                    |
-| ------------------ | ------------------------------- | ------------------------------------------ |
-| series (discrete)  | the plot has several series     | one item per series, in its color and mark |
-| color (continuous) | `color` is a continuous value   | a ramp with its min and max                |
-| opacity            | `opacity` is a continuous value | a ramp fading across the opacity range     |
-| size               | `r` is mapped                   | a few dots at representative values        |
-| symbol             | `symbol` is mapped              | each category next to its shape            |
+| Section            | Appears when                    | Content                                                    |
+| ------------------ | ------------------------------- | ---------------------------------------------------------- |
+| series (discrete)  | the plot has several series     | one item per series, in its color and mark                 |
+| color (continuous) | `color` is a continuous value   | a ramp with its min and max                                |
+| opacity            | `opacity` is a continuous value | a bar fading across the opacity range, over a checkerboard |
+| size               | `r` is mapped                   | a few dots at representative values                        |
+| symbol             | `symbol` is mapped              | each category next to its shape                            |
 
 Segments and markers join the series section when they carry a `legend` label:
 
@@ -42,7 +42,7 @@ Items become clickable with `interactive` on the series section. `disabled` says
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 	import LegendReader from './LegendReader.svelte';
 </script>
 
@@ -94,12 +94,12 @@ legend={{
 	series: { title: 'Division', layout: { type: 'flex' } },
 	color: { title: 'Temperature', interactive: { enabled: true } },
 	opacity: { title: 'Confidence' },
-	size: { title: 'Population' },
+	r: { title: 'Population' },
 	symbol: { title: 'Income group' }
 }}
 ```
 
-Each channel key adjusts the section that channel draws: any section field except what the plots compute (items, ranges, domains). An entry with `match` adjusts only the section whose title matches; a list of entries adjusts several.
+Each key is the name of the channel (the plot's own prop: `r` for the size section) and adjusts the section that channel draws: any section field except what the plots compute (items, ranges, domains). An entry with `match` adjusts only the section whose title matches; a list of entries adjusts several.
 
 ## Explicit sections
 
@@ -110,7 +110,7 @@ A list replaces the automatic legend with exactly those sections:
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- An explicit legend: a discrete section of toggles and a continuous ramp. -->
@@ -150,4 +150,6 @@ Section types:
 
 ## Placement and look
 
+An opacity section draws its bar as one color fading over a checkerboard, so it reads as transparency and not as a color ramp; the color is the marker's own when it has one, else `legend.continuous.opacity.color` (black by default), and `legend.continuous.opacity.checker` sets the squares.
+
 The legend is a chrome block: `order` places it (`'legend'`, or in a row with the plot). Its fonts, gaps, swatch size and the continuous bar's geometry are `legend.*` in the [configuration](theming.md). A paginated section's prev/next arrows are replaceable with a `navButton` snippet.