@motionscript/charts 0.1.0 → 0.1.1-alpha.1

package/dist/line-chart/line-chart.js

@@ -1,23 +1,19 @@
-import { Rect, Types, component2d, easeOut, } from "@motionscript/sdk";
+import { Rect, Text, Types, clamp, component2d, easeOut, } from "@motionscript/sdk";
 import { formatNumber } from "@motionscript/sdk/component";
-import { cartesianFrame, cartesianViews, laidOutSize } from "../kit/cartesian.js";
-import { ChartBorder } from "../kit/chart-border.js";
+import { boundText, cartesianFrame, chartViews, columnGhost, fade, frameGap, headroom, laidOutSize, overhang } from "../kit/cartesian.js";
 import { ChartCanvas } from "../kit/chart-canvas.js";
 import { ChartLegend } from "../kit/chart-legend.js";
-import { asParts, fresh } from "../kit/entries.js";
-import { beats } from "../kit/motion.js";
-import { VerticalAxis } from "../kit/vertical-axis.js";
-import { SPOTLIGHT_DIM, formatMarker, lerpAxisDomain, lerpAxisEntry, markerStep, markerValues, resolveAxisDomain, resolveSeriesFill, resolveSeriesStroke, settleAxisDomain, } from "../kit/shared.js";
-import { ChartLine } from "./chart-line.js";
+import { SERIES_ARG, asParts, fresh } from "../kit/entries.js";
+import { HorizontalAxis } from "../kit/horizontal-axis.js";
+import { DEFAULT_MARKERS, ENTER_SHARE, beats, legendAway } from "../kit/motion.js";
+import { SPOTLIGHT_DIM, formatMarker, lerpAxisDomain, lerpAxisEntry, markerStep, markerValues, niceRange, niceTicks, resolveAxisDomain, settleAxisDomain, } from "../kit/shared.js";
+import { CARTESIAN_GRID, CHART_COLORS, CHART_LEGEND, CHART_STYLE_FAMILY, CHART_STYLE_PRESETS, CHART_TEXT, axisConfigOf, legendConfigOf, seriesFill, valueText, } from "../kit/style.js";
+import { VerticalAxis, axisPads } from "../kit/vertical-axis.js";
+import { ChartArea, ChartLine, traceX } from "./chart-line.js";
 import { ChartRegion } from "./chart-region.js";
-import { HorizontalAxis } from "./horizontal-axis.js";
-import { DEFAULT_CHART_THEME, lerpChartTheme, resolveChartTheme, resolveRegionBox, resolveYScale, seriesPoints, } from "./shared.js";
+import { LINE_LABELS, LINE_MARKS, resolveRegionBox, stackExtent, stackSeries, } from "./shared.js";
 import { resolveXScale } from "./x-scale.js";
-/**
- * The argument every per-series command takes: an index into `series`. Its own
- * kind rather than `number` so a host can offer the series by name.
- */
-const SERIES_ARG = Types.custom(0, { kind: "series", min: 0, step: 1 });
+const LINE_STYLE = Types.style(CHART_STYLE_FAMILY, { colors: CHART_COLORS, text: CHART_TEXT, grid: CARTESIAN_GRID, marks: LINE_MARKS, labels: LINE_LABELS, legend: CHART_LEGEND }, { presets: CHART_STYLE_PRESETS });
 /** One argument, two controls: the commands take a `PlotRegion`, so the x and y spans a host draws are declared inside it. */
 const REGION_ARG = Types.custom(undefined, {
     kind: "region",
@@ -26,355 +22,424 @@ const REGION_ARG = Types.custom(undefined, {
         y: { kind: "range", default: false, defaultMin: 0, defaultMax: 100 },
     },
 });
-/** How far the legend starts below its slot when it enters, in px. */
-const LEGEND_SLIDE = 20;
-/** Fallback marker count when neither axis's ticks are given. */
-const DEFAULT_MARKERS = 5;
-/**
- * How `enter` divides its duration between its three beats: the axes arriving,
- * the lines tracing, and the legend coming up. Shares of the whole, so they must
- * sum to 1 — the entrance takes exactly the time it was given.
- */
-const AXES_SHARE = 0.35;
-const LINES_SHARE = 0.5;
-const LEGEND_SHARE = 0.15;
-/**
- * What the x column *is* — a number, an instant, or a place in the file — and
- * with it how each row is positioned, ticked and captioned. See `x-scale.ts`.
- */
+/** The share of the y axis a percent stack reads to. */
+const PERCENT = [0, 100];
+/** What the x column is (a number, an instant, or a place in the file), and so how rows are positioned, ticked and captioned. */
 function columnOf(s, format = s.xAxis.format) {
     return resolveXScale(s.data, s.xField, format);
 }
-/**
- * The horizontal axis with its range and ticks resolved: the explicit ones, else
- * the column's extent and five ticks across it, asked of the column because only
- * a numeric one has round numbers between its samples.
- */
+/** Every series as drawn; `weighted` false reads each at full share, as the scale does so the ticks hold still while a series sinks out. */
+function stacksOf(s, weighted = true) {
+    return stackSeries(s.data, columnOf(s), s.series, s.stack, weighted ? s.weights : undefined);
+}
+/** The explicit range and ticks, else the column's extent and ticks: only a numeric column has round numbers between its samples. */
 function drawnX(s, domain) {
     const column = columnOf(s, domain.format);
     const range = domain.range ?? column.extent;
     return { ...domain, range, ticks: domain.ticks ?? column.ticks(range, DEFAULT_MARKERS - 1) };
 }
-/**
- * The vertical axis with its range and ticks resolved. Auto-ranging steps into
- * one fewer segment than the intended marker count, so the tidy bounds frame the
- * ticks the axis draws.
- */
+/** The y range the data asks for: a percent stack reads to 100; areas and stacks keep zero on the scale. */
+function autoY(s, divisions) {
+    const [lo, hi] = stackExtent(stacksOf(s, false));
+    if (s.stack === "percent" && lo >= 0)
+        return PERCENT;
+    const zero = s.stack !== "none" || (s.style?.area ?? "none") !== "none";
+    return niceRange(zero ? [Math.min(0, lo), Math.max(0, hi)] : [lo, hi], divisions);
+}
+/** Auto-ranging steps into one fewer segment than the marker count, so the tidy bounds frame the ticks drawn. */
 function drawnY(s, domain) {
     const divisions = (domain.ticks?.length ?? DEFAULT_MARKERS) - 1;
-    const range = resolveYScale(s.data, s.series, domain.range, divisions);
-    return { ...domain, range, ticks: domain.ticks ?? markerValues(range, DEFAULT_MARKERS - 1) };
+    const range = domain.range ?? autoY(s, divisions);
+    const even = domain.range !== undefined || (s.stack === "percent" && range === PERCENT);
+    return { ...domain, range, ticks: domain.ticks ?? (even ? markerValues(range, DEFAULT_MARKERS - 1) : niceTicks(range, DEFAULT_MARKERS - 1)) };
 }
 /** The last domains worked out from each data array, and what else they were read from. */
 const domainsDrawn = new WeakMap();
-/** Both axes as a line chart draws them now, an auto range or tick row read back as itself. */
+/** Both axes as drawn now. */
 export function lineChartDomains(s) {
-    const { data, xField, xAxis, yAxis, series } = s;
-    const kept = domainsDrawn.get(data);
-    if (kept && kept.xField === xField && kept.xAxis === xAxis && kept.yAxis === yAxis && kept.series === series) {
+    const key = [s.xField, s.xAxis, s.yAxis, s.series, s.stack, s.style?.area];
+    const kept = domainsDrawn.get(s.data);
+    if (kept && kept.key.every((value, i) => value === key[i]))
         return kept.domains;
-    }
     const domains = {
-        x: settleAxisDomain(xAxis, (d) => drawnX(s, d)),
-        y: settleAxisDomain(yAxis, (d) => drawnY(s, d)),
+        x: settleAxisDomain(s.xAxis, (d) => drawnX(s, d)),
+        y: settleAxisDomain(s.yAxis, (d) => drawnY(s, d)),
     };
-    domainsDrawn.set(data, { xField, xAxis, yAxis, series, domains });
+    domainsDrawn.set(s.data, { key, domains });
     return domains;
 }
-/**
- * Map one series' data points into the plot's **centred** pixel space (origin at
- * the plot centre, y-up): x runs `[-w/2, +w/2]`, y runs `[-h/2, +h/2]`.
- */
-function seriesPixels(s, domains, index, plot) {
-    const series = s.series[index];
-    if (!series)
-        return [];
-    const points = seriesPoints(s.data, columnOf(s), series);
-    if (points.length === 0)
-        return [];
-    const { width: w, height: h } = plot;
+/** Data to the plot's centred pixel space (origin at its centre, y-up). */
+function mapper(domains, plot) {
     const [xMin, xMax] = domains.x.range;
     const [yMin, yMax] = domains.y.range;
-    const xToPx = (x) => (xMax <= xMin ? 0 : ((x - xMin) / (xMax - xMin) - 0.5) * w);
-    const yToPx = (y) => (yMax <= yMin ? 0 : ((y - yMin) / (yMax - yMin) - 0.5) * h);
-    // `seriesPoints` already sorted them along x.
-    return points.map(([x, y]) => ({ x: xToPx(x), y: yToPx(y) }));
+    return {
+        x: (x) => (xMax <= xMin ? 0 : ((x - xMin) / (xMax - xMin) - 0.5) * plot.width),
+        y: (y) => (yMax === yMin ? 0 : ((y - yMin) / (yMax - yMin) - 0.5) * plot.height),
+    };
+}
+const NO_PIXELS = { points: [], base: [], values: [] };
+/** Series `index` in the plot's centred pixel space. */
+function seriesPixels(s, domains, index, plot) {
+    const stack = stacksOf(s)[index];
+    if (!stack)
+        return NO_PIXELS;
+    const map = mapper(domains, plot);
+    const toPx = ([x, y]) => ({ x: map.x(x), y: map.y(y) });
+    return {
+        points: stack.points.map(toPx),
+        base: stack.base ? stack.base.map(toPx) : [],
+        values: stack.points.map(([, y], k) => y - (stack.base?.[k]?.[1] ?? 0)),
+    };
+}
+/** Where the areas fill down to: zero, held inside the scale. */
+function baselineValue(domains) {
+    const [lo, hi] = domains.y.range;
+    return clamp(0, Math.min(lo, hi), Math.max(lo, hi));
 }
-/** `region` mapped into the plot's centred pixel space, against the live scales, so it travels with a zoom. */
+/** Whether anything plotted runs past the scale, so the plot clips it: a zoom, or an author's range narrower than the data. */
+function overflows(s, domains) {
+    const [ylo, yhi] = stackExtent(stacksOf(s, false));
+    const [xlo, xhi] = columnOf(s).extent;
+    const within = (v, [a, b]) => v >= Math.min(a, b) - 1e-9 && v <= Math.max(a, b) + 1e-9;
+    return !(within(ylo, domains.y.range) && within(yhi, domains.y.range) && within(xlo, domains.x.range) && within(xhi, domains.x.range));
+}
+/** `region` in centred pixel space against the live scales, so it travels with a zoom. */
 function regionBox(s, domains, plot) {
     const { width: w, height: h } = plot;
     return resolveRegionBox(s.region, { left: -w / 2, right: w / 2, bottom: -h / 2, top: h / 2 }, domains.x.range, domains.y.range);
 }
-/**
- * Whether a call-out is authored at all. Not whether it resolves to pixels: a
- * command is built before the first layout, and a region on a chart not yet
- * measured is a real one. A region bounding neither axis is none, as `null` is.
- */
+/** Whether a call-out is authored, not whether it resolves to pixels: a command is built before the first layout. A region bounding neither axis is none. */
 function hasCallout(s) {
     const region = s.region;
     return region != null && (region.x !== undefined || region.y !== undefined);
 }
-/** The `region` a document handed a command, or `{}`: a command is added before its arguments are filled in. */
+/** The `region` argument, or `{}`: a command is added before its arguments are filled in. */
 function regionArg(region) {
     return region != null && typeof region === "object" ? region : {};
 }
-/** A range read as a span, whichever way round the author wrote it. */
+/** A range ordered low to high. */
 function span([a, b]) {
     return a <= b ? [a, b] : [b, a];
 }
-/**
- * Rescale an axis to `range`, keeping the tick *count* it already has, so each
- * marker slides from its old value to its new one instead of the row popping.
- */
+/** Rescale to `range` keeping the tick count, so each marker slides rather than the row popping. */
 function rescale(range, ticks) {
     const to = span(range);
     return { range: to, ticks: markerValues(to, Math.max(2, ticks.length) - 1) };
 }
-/** The axis writes of a move from `from` toward `to` at `t`. */
 function axesAt(from, to, t) {
     return {
         ...(to.x && { xAxis: lerpAxisDomain(from.x, to.x, t) }),
         ...(to.y && { yAxis: lerpAxisDomain(from.y, to.y, t) }),
     };
 }
+/** A value as the y axis writes it: the author's pattern, a share in a percent stack, else the bare reading at the ticks' precision. */
+function yLabel(s, value, ticks) {
+    const format = s.yAxis.format;
+    if (format !== undefined)
+        return formatNumber(value, format);
+    const text = formatMarker(value, markerStep(ticks));
+    return s.stack === "percent" ? `${text}%` : text;
+}
+function weightOf(s, index) {
+    return Math.max(0, s.weights[index] ?? 1);
+}
 /** The parts a line chart's commands drive, found through its children. */
 function partsOf(children) {
-    const frame = cartesianViews(children);
-    if (!frame)
-        return null;
-    const hAxis = frame.below.find(HorizontalAxis.is);
-    if (!VerticalAxis.is(frame.axis) || !hAxis)
-        return null;
+    const views = chartViews(children);
     return {
-        vAxis: frame.axis,
-        hAxis,
-        lines: frame.plot.filter(ChartLine.is),
-        legend: frame.below.find(ChartLegend.is) ?? null,
+        vAxis: views.find(VerticalAxis.is) ?? null,
+        hAxis: views.find(HorizontalAxis.is) ?? null,
+        lines: views.filter(ChartLine.is),
+        legend: views.find(ChartLegend.is) ?? null,
     };
 }
-/** Drop the call-out: the rules retract, the wash fades, and every series comes back to full. */
 function clearing(timeline, state) {
     const from = state.regionReveal;
     const region = state.region;
-    // Nothing to retract, but the call still takes its slot on the timeline.
+    // Nothing to retract, but the call still takes its slot.
     if (from === 0)
         return timeline.animate(() => ({ region: null, regionReveal: 0 }), { eased: false });
     // `region` is held until the retraction lands, or there would be nothing left to retract.
     return timeline.animate((t) => (t >= 1 ? { region: null, regionReveal: 0 } : { region, regionReveal: from * (1 - t) }));
 }
-/** Trace series `index`'s line in (`show`) or back out, in lockstep with its legend entry. */
-function toggling(timeline, children, index, show) {
+/**
+ * Show or hide series `index` with its legend entry. Apart, the line retraces;
+ * in a stack it sinks into the series below as its share falls to nothing, so
+ * the ones above settle rather than leaving a gap.
+ */
+function toggling(timeline, state, children, index, show) {
     const parts = partsOf(children);
-    const line = parts?.lines[index];
-    if (!parts || !line)
+    const line = parts.lines[index];
+    if (!line)
         return timeline.wait(timeline.duration);
+    const legend = parts.legend ? [parts.legend.run(show ? "showSeries" : "hideSeries", { index })] : [];
+    if (state.stack === "none") {
+        return timeline.together([line.run("enter", show ? { from: 0, to: 1 } : { from: 1, to: 0 }), ...legend]);
+    }
+    const from = state.series.map((_, i) => weightOf(state, i));
+    const start = from[index] ?? 1;
+    const target = show ? 1 : 0;
     return timeline.together([
-        line.run("enter", show ? { from: 0, to: 1 } : { from: 1, to: 0 }),
-        ...(parts.legend ? [parts.legend.run(show ? "showSeries" : "hideSeries", { index })] : []),
+        timeline.animate((t) => {
+            const weights = [...from];
+            weights[index] = start + (target - start) * timeline.ease(t);
+            return { weights };
+        }, { eased: false }),
+        line.run("hold", { shown: show }),
+        ...legend,
     ]);
 }
 /**
- * A multi-series line chart, composed from five independent parts rather than
- * one monolithic draw:
- *
- * - {@link ChartCanvas} — the plot panel with a two-way grid, under everything.
- * - {@link VerticalAxis} / {@link HorizontalAxis} — columns/rows of real text
- *   markers that stagger in, each carrying its own axis caption.
- * - {@link ChartRegion} — the optional call-out marking a spotlit slice of the
- *   plot: dashed rules on its bounded edges, and every series faded outside it.
- * - {@link ChartLine} (one per series) — the traced polylines over the canvas.
- * - {@link ChartLegend} — a row of entries below the chart, one per series.
+ * A multi-series line or area chart composed of {@link ChartCanvas}, the value
+ * and x axes, {@link ChartRegion}, a {@link ChartArea} and a {@link ChartLine}
+ * per series, and {@link ChartLegend}. Every part reads the chart's entries
+ * through bindings and maps against the plot panel's own laid-out box.
  *
- * Every part reads the chart's entries through bindings, and the lines, the
- * region and the grid all map against the plot panel's own laid-out box, so
- * points land exactly on their markers and the chart re-flows if its box
- * changes.
- *
- * **Resting state is the finished chart**: an editor paints a node's Initial
- * state on a paused canvas. `enter` arms every part on its first frame.
- *
- * Past the entrance, `showSeries`/`hideSeries`/`spotlightSeries` pick out a
- * *series*, `spotlightRegion` marks a *slice of the plot* without changing the
- * scale, and `zoomTo` rescales the axes so a slice fills the plot. A spotlit
- * region resolves against the live scales, so it travels with a zoom. A `to` of
- * an axis `range` or `ticks` tweens from the domain as drawn (see
- * {@link lerpAxisEntry}), so an auto axis rescales continuously.
+ * Resting state is the finished chart; `enter` arms every part on its first
+ * frame. A `to` of an axis `range` or `ticks` tweens from the domain as drawn
+ * (see {@link lerpAxisEntry}), so an auto axis rescales continuously.
  */
 export const LineChart = component2d({
     key: "lineChart",
     state: {
         data: fresh(() => [], { kind: "dataset" }),
+        // Not `x`: every node already has an `x`, its position.
         xField: "",
         series: fresh(() => [], { kind: "series" }),
+        /** `stacked`: each series sits on the sum of those before it; `percent`: every row reads as shares of 100. */
+        stack: Types.oneOf(["none", "stacked", "percent"]),
         xAxis: Types.custom({}, { resolve: resolveAxisDomain, lerp: lerpAxisEntry }),
         yAxis: Types.custom({}, { resolve: resolveAxisDomain, lerp: lerpAxisEntry }),
-        theme: Types.custom(DEFAULT_CHART_THEME, { resolve: resolveChartTheme, lerp: lerpChartTheme }),
-        /**
-         * The spotlit slice of the plot in data units, or `null` for none. The box
-         * snaps; the animation is {@link regionReveal} drawing the rules on.
-         */
+        style: LINE_STYLE,
+        /** The spotlit slice in data units, or `null`. The box snaps; {@link regionReveal} animates it. */
         region: Types.custom(null),
-        /**
-         * How far the `region` call-out is drawn in, `[0, 1]`: the rules grow out and
-         * the wash fades up as it climbs, while every line's out-of-region stretch
-         * fades to the theme's `region.dimOpacity`.
-         */
+        /** How far the `region` call-out is drawn in, `[0, 1]`: rules grow, wash fades up, out-of-region stretches fade. */
         regionReveal: 0,
-        /** Read as the chart is built: the legend is a part the chart builds or doesn't. */
-        showLegend: Types.boolean(true, { animatable: false }),
-        /**
-         * The domain `zoomTo` first left, so `resetZoom` restores the chart as it
-         * stood, auto-derived ticks included. Cleared by `resetZoom`, so the next zoom
-         * remembers wherever the chart rests then.
-         */
+        /** The domain `zoomTo` first left, so `resetZoom` restores it, auto-derived ticks included. */
         home: Types.custom(null, { private: true }),
+        /** Each series' share of a stack, seeded from `enabled`: a weight rather than a switch, so a hidden series sinks out. */
+        weights: Types.custom([], { private: true }),
+        /** Whether the plot clips its marks, from a zoom's first frame until a reset lands. */
+        clipped: Types.boolean(false, { private: true }),
+    },
+    // A node made of parts that fill would otherwise hug them.
+    defaults: {
+        width: "fill",
+        height: "fill",
+        weights: (state) => state.series.map((s) => ((s.enabled ?? true) ? 1 : 0)),
     },
-    // Its parts fill it; a node made of them would hug them.
-    defaults: { width: "fill", height: "fill" },
     allowedChildren: [],
     children: (state) => {
-        const theme = () => state.theme;
+        const style = () => state.style;
         const domains = () => lineChartDomains(state);
         let plot;
         const plotSize = () => laidOutSize(plot);
+        const pixels = (i) => seriesPixels(state, domains(), i, plotSize());
         const enabled = state.series.map((s) => s.enabled ?? true);
+        const built = state.style;
+        const yConfig = () => axisConfigOf(style(), "y");
+        const xConfig = () => axisConfigOf(style(), "x");
+        const yCaptions = () => {
+            const ticks = domains().y.ticks;
+            return ticks.map((value) => yLabel(state, value, ticks));
+        };
         // Bound, not snapshotted, so a rescale re-labels and re-places the row as it
         // tweens. The marker *count* is read once, which is why `zoomTo` keeps it.
-        const vAxis = new VerticalAxis({
-            range: () => domains().y.range,
-            markers: () => domains().y.ticks,
-            // The y axis is always numbers, so its format is simply the pattern.
-            captions: () => {
-                const markers = domains().y.ticks;
-                const format = state.yAxis.format;
-                return markers.map((value) => (format === undefined ? formatMarker(value, markerStep(markers)) : formatNumber(value, format)));
-            },
-            axis: () => theme().yAxis,
-            label: state.yAxis.label ?? "",
-            width: "hug",
-            height: "fill",
-        });
-        const hAxis = new HorizontalAxis({
-            range: () => domains().x.range,
-            markers: () => domains().x.ticks,
-            // A tick on a month or category column is captioned with the cell it came
-            // out of — `Jan`, not the instant it parsed to.
-            captions: () => {
-                const column = columnOf(state);
-                return domains().x.ticks.map((value) => column.label(value));
-            },
-            axis: () => theme().xAxis,
-            label: state.xAxis.label ?? "",
-            width: "fill",
-            height: "hug",
-        });
+        const vAxis = built.showYAxis
+            ? new VerticalAxis({
+                range: () => domains().y.range,
+                markers: () => domains().y.ticks,
+                captions: yCaptions,
+                axis: yConfig,
+                label: state.yAxis.label ?? "",
+                width: "hug",
+                height: "fill",
+            })
+            : undefined;
+        const hAxis = built.showXAxis
+            ? new HorizontalAxis({
+                range: () => domains().x.range,
+                markers: () => domains().x.ticks,
+                // A month or category tick is captioned with its cell (`Jan`), not the instant it parsed to.
+                captions: () => {
+                    const column = columnOf(state);
+                    return domains().x.ticks.map((value) => column.label(value));
+                },
+                axis: xConfig,
+                label: state.xAxis.label ?? "",
+                overhang: () => ({ left: overhang(style()), right: overhang(style()) }),
+                width: "fill",
+                height: "hug",
+            })
+            : undefined;
+        const ghost = vAxis && hAxis
+            ? columnGhost({
+                captions: yCaptions,
+                count: lineChartDomains(state).y.ticks.length,
+                text: () => yConfig().labelStyle,
+                title: state.yAxis.label ?? "",
+                titleText: () => yConfig().titleStyle,
+                tickPad: () => axisPads(yConfig(), "right").tick,
+                titlePad: () => axisPads(yConfig(), "right").title,
+            })
+            : undefined;
+        const spotlight = () => regionBox(state, domains(), plotSize());
+        const dimOpacity = () => 1 - (1 - SPOTLIGHT_DIM) * state.regionReveal;
         const lines = state.series.map((s, i) => new ChartLine({
-            points: () => seriesPixels(state, domains(), i, plotSize()),
-            stroke: () => resolveSeriesStroke(theme().seriesStyles, s, i),
+            points: () => pixels(i).points,
+            curve: () => style().curve,
+            stroke: () => ({ weight: style().strokeWidth, fill: seriesFill(style(), s, i), align: "center", cap: "round", join: "round" }),
+            dotSize: () => (style().dots ? style().dotSize : 0),
+            dotFill: () => seriesFill(style(), s, i),
             enabled: enabled[i],
-            // Each line clips itself against the box the rules are drawn from, so
-            // the dim/bright boundary can't drift from the dashes.
-            spotlight: () => regionBox(state, domains(), plotSize()),
-            // Ramped by the reveal that draws the rules: one signal, both halves.
-            dimOpacity: () => 1 - (1 - theme().region.dimOpacity) * state.regionReveal,
+            spotlight,
+            dimOpacity,
         }));
-        const below = [hAxis];
-        if (state.showLegend !== false) {
-            below.push(new ChartLegend({
-                series: state.series,
-                // The legend paints a swatch, not a line, so it is handed the colour each
-                // stroke resolves to rather than the stroke itself.
-                swatches: () => state.series.map((s, i) => resolveSeriesFill(theme().seriesStyles, s, i)),
-                legend: () => theme().legend,
-                // The row's spacing is the theme's as the chart was built, like the
-                // entries' type and chips: a theme tween re-paints the swatches only.
-                gap: state.theme.legend.itemGap,
-                padding: state.theme.legend.padding,
-            }));
+        const areas = state.series.map((s, i) => new ChartArea({
+            points: () => pixels(i).points,
+            base: () => pixels(i).base,
+            baseline: () => mapper(domains(), plotSize()).y(baselineValue(domains())),
+            curve: () => style().curve,
+            area: () => style().area,
+            fill: () => seriesFill(style(), s, i),
+            areaOpacity: () => style().areaOpacity,
+            // The line's own trace, switch and fade, so the two arrive, leave and dim as one.
+            progress: () => lines[i].progress,
+            enabled: () => lines[i].enabled,
+            opacity: () => lines[i].opacity,
+            spotlight,
+            dimOpacity,
+        }));
+        const labels = [];
+        if (built.values !== "none") {
+            const below = built.values === "below";
+            state.series.forEach((_, i) => {
+                state.data.forEach((_row, k) => {
+                    const line = lines[i];
+                    const label = new Text({
+                        ...boundText(() => ({ ...valueText(style()), fontSize: Math.round(style().fontSize * 0.8) })),
+                        text: () => {
+                            const value = pixels(i).values[k];
+                            return value === undefined ? "" : yLabel(state, value, domains().y.ticks);
+                        },
+                        // Held inside the plot, so a figure on an end point does not run into the axis beside it.
+                        x: () => {
+                            const half = (plotSize().width - label.layoutBounds.width) / 2;
+                            return clamp(pixels(i).points[k]?.x ?? 0, -Math.max(0, half), Math.max(0, half));
+                        },
+                        y: () => {
+                            const point = pixels(i).points[k];
+                            const clear = label.layoutBounds.height / 2 + (style().dots ? style().dotSize / 2 : style().strokeWidth / 2) + Math.round(style().fontSize * 0.25);
+                            return (point?.y ?? 0) + (below ? -clear : clear);
+                        },
+                        // In once the trace has passed its point.
+                        opacity: () => {
+                            const point = pixels(i).points[k];
+                            if (!line.enabled || !point)
+                                return 0;
+                            const reach = traceX(pixels(i).points, line.progress);
+                            return line.opacity * (reach === Infinity ? 1 : clamp((reach - point.x) / 24, 0, 1));
+                        },
+                    });
+                    labels.push(label);
+                });
+            });
         }
+        const legendAt = built.legend;
+        const legend = legendAt !== "none"
+            ? new ChartLegend({
+                series: state.series,
+                swatches: () => state.series.map((s, i) => seriesFill(style(), s, i)),
+                legend: () => legendConfigOf(style()),
+                flow: legendAt === "right" ? "vertical" : "horizontal",
+            })
+            : undefined;
         plot = new Rect({
-            clip: true,
+            clip: () => state.clipped || overflows(state, domains()),
             children: [
                 new ChartCanvas({
-                    fill: () => theme().plotArea.fill,
-                    shadow: () => theme().plotArea.shadow,
-                    xGridStroke: () => theme().xAxis.lineStyle,
-                    yGridStroke: () => theme().yAxis.lineStyle,
-                    // A grid line under every axis marker; the canvas skips the edges.
+                    fill: () => style().background,
+                    xGridStroke: () => style().verticalGrid,
+                    yGridStroke: () => style().horizontalGrid,
                     xMarkers: () => domains().x.ticks,
                     yMarkers: () => domains().y.ticks,
                     xExtent: () => domains().x.range,
                     yExtent: () => domains().y.range,
+                    axisStroke: () => style().axisStroke,
+                    xAxisAt: () => baselineValue(domains()),
+                    yAxisAt: () => domains().x.range[0],
                 }),
-                // Over the grid, under the lines, so a spotlit stretch of a series isn't
-                // tinted by the highlight meant to pick it out.
+                // Under the marks, so the highlight does not tint the stretch it picks out.
                 new ChartRegion({
-                    box: () => regionBox(state, domains(), plotSize()),
-                    stroke: () => theme().region.stroke,
-                    fill: () => theme().region.fill,
+                    box: spotlight,
+                    stroke: () => ({ weight: 2, fill: fade(style().foreground, 0.7), dash: [14, 12], cap: "butt", align: "center" }),
+                    fill: () => fade(style().foreground, 0.06),
                     reveal: () => state.regionReveal,
                 }),
+                ...areas,
                 ...lines,
-                new ChartBorder({ stroke: () => theme().plotArea.stroke }),
+                ...labels,
             ],
         });
-        const gutter = new VerticalAxis({
-            opacity: 0,
-            range: () => domains().y.range,
-            markers: () => domains().y.ticks,
-            axis: () => theme().yAxis,
-            label: state.yAxis.label ?? "",
-            width: "hug",
-            height: 0,
-        });
-        return asParts([cartesianFrame({ axis: vAxis, plot, gutter, below })]);
+        return asParts([
+            cartesianFrame({
+                left: vAxis,
+                ghost,
+                plot,
+                bottom: hAxis,
+                legend,
+                legendAt,
+                gap: () => frameGap(style()),
+                padding: () => ({
+                    top: headroom(style()),
+                    right: hAxis ? overhang(style()) : 0,
+                    left: hAxis && !vAxis ? overhang(style()) : 0,
+                    bottom: 0,
+                }),
+            }),
+        ]);
     },
     commands: {
         /**
-         * Animate the whole chart in: the two axes stagger their markers in, the
-         * series lines trace left to right, and the legend fades up last. Its first
-         * frame arms every part: markers shifted and transparent, lines untraced,
-         * the legend dropped and transparent.
-         *
-         * `duration` is the **whole** entrance; the beats are shares of it. A chart
-         * authored with a `region` lands its call-out last, in the final quarter.
+         * Axes stagger in, lines (and their areas) trace left to right, the legend
+         * fades up last. `duration` is the whole entrance; a chart with a `region`
+         * lands its call-out in the final quarter.
          */
         enter: {
             args: {},
-            // Held from the chart's arrival, so it never shows finished ahead of its draw.
+            // Held from arrival, so it never shows finished ahead of its draw.
             entrance: true,
             easing: easeOut(),
             run: (timeline, state, children) => {
                 const parts = partsOf(children);
-                if (!parts)
-                    return timeline.wait(timeline.duration);
                 const duration = timeline.duration;
                 const revealing = hasCallout(state) && state.regionReveal === 0;
                 const body = revealing ? duration * 0.75 : duration;
-                const axes = body * AXES_SHARE;
-                const traced = body * LINES_SHARE;
+                const axes = body * ENTER_SHARE.axes;
+                const traced = body * ENTER_SHARE.marks;
                 const { legend } = parts;
                 const at0 = (piece) => ({ at: 0, duration: 0, piece });
+                const away = legendAway(state.style.legend);
                 // The first frame arms what every later beat moves: a beat ahead of the
                 // playhead writes nothing. A beat with nothing to do still takes its share.
                 return beats(timeline, [
                     ...(revealing ? [at0(timeline.animate(() => ({ regionReveal: 0 })))] : []),
                     ...parts.lines.map((line) => at0(line.to({ progress: 0 }))),
-                    ...(legend ? [at0(legend.to({ opacity: 0, y: -LEGEND_SLIDE }))] : []),
-                    { at: 0, duration: axes, piece: parts.vAxis.run("enter", { slide: 24 }) },
-                    { at: 0, duration: axes, piece: parts.hAxis.run("enter", { slide: 24 }) },
+                    ...(legend ? [at0(legend.to({ opacity: 0, ...away }))] : []),
+                    ...(parts.vAxis ? [{ at: 0, duration: axes, piece: parts.vAxis.run("enter", { slide: 24 }) }] : []),
+                    ...(parts.hAxis ? [{ at: 0, duration: axes, piece: parts.hAxis.run("enter", { slide: 24 }) }] : []),
                     ...parts.lines.map((line) => ({ at: axes, duration: traced, piece: line.run("enter") })),
-                    ...(legend ? [{ at: axes + traced, duration: body * LEGEND_SHARE, piece: legend.to({ opacity: 1, y: 0 }) }] : []),
+                    ...(legend ? [{ at: axes + traced, duration: body * ENTER_SHARE.legend, piece: legend.to({ opacity: 1, x: 0, y: 0 }) }] : []),
                     ...(revealing ? [{ at: body, duration: duration * 0.25, piece: timeline.animate((t) => ({ regionReveal: t })) }] : []),
+                    // Takes the whole slot even with no parts to move.
+                    { at: 0, duration, piece: timeline.wait(duration) },
                 ]);
             },
         },
         /**
-         * Spotlight a rectangular slice of the plot given in **data units**: dashed
-         * rules draw onto each bounded edge while every series fades outside the box.
-         * Either axis alone is a band; both are a box. Called while another region is
-         * up, the old call-out retracts over the first half and the new one draws in
-         * over the second, each half eased on its own.
+         * Spotlight a slice of the plot in data units; either axis alone is a band.
+         * Over a region already up, the old one retracts in the first half and the
+         * new one draws in over the second, each half eased on its own.
          */
         spotlightRegion: {
             args: { region: REGION_ARG },
@@ -394,18 +459,13 @@ export const LineChart = component2d({
                     : { region, regionReveal: timeline.ease(t * 2 - 1) }), { eased: false });
             },
         },
-        /** Drop the region call-out. A no-op when nothing is spotlit, which still takes its slot. */
+        /** Drop the call-out. A no-op when nothing is spotlit, which still takes its slot. */
         clearRegion: {
             args: {},
             easing: easeOut(),
             run: (timeline, state) => clearing(timeline, state),
         },
-        /**
-         * Zoom the plot to a slice of itself, given in **data units**: the named axes
-         * rescale so that slice fills the plot, the grid, both marker rows and every
-         * series following. An omitted axis is left as it is. The first zoom
-         * remembers the domain it left, for `resetZoom`.
-         */
+        /** Rescale the named axes so a slice (data units) fills the plot; an omitted axis is left. The first zoom remembers the domain for `resetZoom`. */
         zoomTo: {
             args: { region: REGION_ARG },
             easing: easeOut(),
@@ -419,10 +479,10 @@ export const LineChart = component2d({
                     ...(region.x && { x: { ...from.x, ...rescale(region.x, from.x.ticks) } }),
                     ...(region.y && { y: { ...from.y, ...rescale(region.y, from.y.ticks) } }),
                 };
-                return timeline.animate((t) => ({ home, ...axesAt(from, to, t) }));
+                return timeline.animate((t) => ({ home, clipped: true, ...axesAt(from, to, t) }));
             },
         },
-        /** Pull back out to the domain the first zoom left — the mirror of `zoomTo`, and a hold if it never zoomed. */
+        /** Back to the domain the first zoom left; a hold if it never zoomed. */
         resetZoom: {
             args: {},
             easing: easeOut(),
@@ -431,40 +491,32 @@ export const LineChart = component2d({
                 if (!home)
                     return timeline.wait(timeline.duration);
                 const from = lineChartDomains(state);
-                return timeline.animate((t) => ({ home: null, ...axesAt(from, home, t) }));
+                return timeline.animate((t) => ({ home: null, clipped: t < 1, ...axesAt(from, home, t) }));
             },
         },
-        /**
-         * Show series `index`: **trace** its line in left to right, in lockstep with
-         * its legend entry growing in.
-         */
+        /** Bring series `index` in, with its legend entry growing in: traced, or in a stack risen out of the series below. */
         showSeries: {
             args: { seriesIndex: SERIES_ARG },
             easing: easeOut(),
-            run: (timeline, _state, children) => toggling(timeline, children, timeline.args.seriesIndex, true),
+            run: (timeline, state, children) => toggling(timeline, state, children, timeline.args.seriesIndex, true),
         },
-        /** Hide series `index`: **retrace** its line back out as its legend entry shrinks away. */
+        /** The mirror of `showSeries`. */
         hideSeries: {
             args: { seriesIndex: SERIES_ARG },
             easing: easeOut(),
-            run: (timeline, _state, children) => toggling(timeline, children, timeline.args.seriesIndex, false),
+            run: (timeline, state, children) => toggling(timeline, state, children, timeline.args.seriesIndex, false),
         },
-        /**
-         * Fade every other series — each line **and its legend entry** — to focus on
-         * `index`, which comes back to full. The legend dims in place, so the row
-         * doesn't reflow.
-         */
+        /** Fade every other series, line, area and legend entry, to focus on `index`. The legend dims in place, so the row does not reflow. */
         spotlightSeries: {
             args: { seriesIndex: SERIES_ARG },
             easing: easeOut(),
             run: (timeline, _state, children) => {
                 const parts = partsOf(children);
-                if (!parts)
-                    return timeline.wait(timeline.duration);
                 const index = timeline.args.seriesIndex;
                 return timeline.together([
                     ...parts.lines.map((line, i) => line.to({ opacity: i === index ? 1 : SPOTLIGHT_DIM })),
                     ...(parts.legend ? [parts.legend.run("spotlightSeries", { index })] : []),
+                    timeline.wait(timeline.duration),
                 ]);
             },
         },