@motionscript/charts 0.1.0 → 0.1.1-alpha.1

package/dist/bar-chart/bar-chart.js

@@ -1,102 +1,84 @@
-import { Rect, Types, component2d, easeOut, } from "@motionscript/sdk";
+import { Rect, 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 { cartesianFrame, chartViews, columnGhost, 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 { clampUnit, formatMarker, lerpAxisDomain, lerpAxisEntry, markerStep, markerValues, num, resolveAxisDomain, settleAxisDomain, } from "../kit/shared.js";
-import { CategoryAxis } from "./category-axis.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, niceTicks, num, 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 { CategoryAxis, slotCentre } from "./category-axis.js";
 import { ChartBars } from "./chart-bars.js";
-import { DEFAULT_BAR_CHART_THEME, barCategories, barSpans, lerpBarChartTheme, resolveBarChartTheme, resolveBarFill, resolveBarScale, stackCapIndex, } from "./shared.js";
-/** The argument every per-series command takes: an index into `series`, offered by name. */
-const SERIES_ARG = Types.custom(0, { kind: "series", min: 0, step: 1 });
-/** How far the legend starts below its slot when it enters, in px. */
-const LEGEND_SLIDE = 20;
-/** Fallback marker count when the value axis states no ticks. */
-const DEFAULT_MARKERS = 5;
-/**
- * How `enter` divides its duration between its three beats: the axes arriving,
- * the columns rising, and the legend coming up. Shares of the whole, so they
- * must sum to 1.
- */
-const AXES_SHARE = 0.35;
-const BARS_SHARE = 0.5;
-const LEGEND_SHARE = 0.15;
-/** The value axis with its range and ticks resolved: the explicit ones, else five across the scale. */
+import { BAR_LABELS, BAR_MARKS, barCategories, barSpans, resolveBarScale, } from "./shared.js";
+const BAR_STYLE = Types.style(CHART_STYLE_FAMILY, { colors: CHART_COLORS, text: CHART_TEXT, grid: CARTESIAN_GRID, marks: BAR_MARKS, labels: BAR_LABELS, legend: CHART_LEGEND }, { presets: CHART_STYLE_PRESETS });
 function drawnValue(s, domain) {
     const divisions = (domain.ticks?.length ?? DEFAULT_MARKERS) - 1;
-    const range = resolveBarScale(s.data, s.series, s.stacked, domain.range, divisions);
-    return { ...domain, range, ticks: domain.ticks ?? markerValues(range, DEFAULT_MARKERS - 1) };
+    const range = resolveBarScale(s.data, s.series, s.stack, domain.range, divisions);
+    const even = domain.range !== undefined || s.stack === "percent";
+    return { ...domain, range, ticks: domain.ticks ?? (even ? markerValues(range, DEFAULT_MARKERS - 1) : niceTicks(range, DEFAULT_MARKERS - 1)) };
 }
-/** The last domain worked out from each data array, and what else it was read from. */
+/** The last domain worked out from each data array, and what it was read from. */
 const domainsDrawn = new WeakMap();
-/** The value axis as a bar chart draws it now, an auto range or tick row read back as itself. */
+/** The value axis as drawn now. A series being hidden keeps its room, so the ticks hold still while it goes. */
 export function barChartDomain(s) {
-    const { data, series, stacked, valueAxis } = s;
-    const kept = domainsDrawn.get(data);
-    if (kept && kept.series === series && kept.stacked === stacked && kept.valueAxis === valueAxis)
+    const key = [s.series, s.stack, s.valueAxis];
+    const kept = domainsDrawn.get(s.data);
+    if (kept && kept.key.every((value, i) => value === key[i]))
         return kept.domain;
-    const domain = settleAxisDomain(valueAxis, (d) => drawnValue(s, d));
-    domainsDrawn.set(data, { series, stacked, valueAxis, domain });
+    const domain = settleAxisDomain(s.valueAxis, (d) => drawnValue(s, d));
+    domainsDrawn.set(s.data, { key, domain });
     return domain;
 }
-/**
- * A value written down as this chart's value axis says: the ticks and the
- * figures printed on the columns both read through here, so the two cannot
- * disagree about what a number looks like.
- */
+/** Ticks and the figures printed by bars both read through here, so they cannot disagree about how a number looks. */
 function valueLabel(s, domain, value) {
     const pattern = s.valueAxis.format;
-    return pattern === undefined ? formatMarker(value, markerStep(domain.ticks)) : formatNumber(value, pattern);
+    if (pattern !== undefined)
+        return formatNumber(value, pattern);
+    const text = formatMarker(value, markerStep(domain.ticks));
+    return s.stack === "percent" ? `${text}%` : text;
 }
-/** A value on the plot's **centred** pixel space (origin at its centre, y-up). */
-function valueToY(domain, plot, value) {
+/** A value along the value axis, a run of `length` px centred on 0. */
+function valueToPx(domain, length, value) {
     const [min, max] = domain.range;
-    if (max <= min)
-        return -plot.height / 2;
-    return ((value - min) / (max - min) - 0.5) * plot.height;
+    if (max === min)
+        return -length / 2;
+    return ((value - min) / (max - min) - 0.5) * length;
 }
-/**
- * Pixel y of the line every column grows from: zero clamped onto the scale, so
- * a cropped axis grows its columns from the plot floor.
- */
-function baselinePx(domain, plot) {
-    const [min, max] = domain.range;
-    return valueToY(domain, plot, Math.min(Math.max(0, min), max));
+/** Where bars grow from: zero held on the scale, so a cropped axis grows them from the plot's edge. */
+function baselineValue(domain) {
+    const [lo, hi] = domain.range;
+    return clamp(0, Math.min(lo, hi), Math.max(lo, hi));
 }
-/** Series `i`'s live share of the slot; 0 once it has been hidden. */
 function weightAt(s, index) {
     return Math.max(0, s.weights[index] ?? 1);
 }
-/** `row` with each series' value scaled by its live weight: what the stacked spans are measured from. */
-function weightedRow(s, row) {
-    const scaled = { ...row };
-    s.series.forEach((series, i) => {
-        const value = row[series.field];
-        if (typeof value === "number")
-            scaled[series.field] = value * weightAt(s, i);
-    });
-    return scaled;
+/** The plot's run along the value axis and across the categories. */
+function runs(s, plot) {
+    return s.orientation === "horizontal" ? { along: plot.width, across: plot.height } : { along: plot.height, across: plot.width };
+}
+/** Category `row`'s slot centre across the plot: left to right, or top to bottom. */
+function slotAt(s, row, across) {
+    const centre = slotCentre(row, s.data.length, across);
+    return s.orientation === "horizontal" ? -centre : centre;
 }
 /**
- * Series `index`'s columns, mapped into the plot's centred pixel space. A
- * grouped series divides the slot with its siblings by their live weights, a
- * stacked one takes the whole slot and runs from the running total below it,
- * so hiding a series reflows rather than punching a hole.
+ * Series `index`'s bars in centred pixel space. Side by side, a series divides
+ * the slot with its siblings by live weight; stacked, it takes the whole slot
+ * and its weight scales its length, so hiding a series reflows rather than
+ * punching a hole.
  */
-function seriesBars(s, index, plot, captioned) {
+function seriesBars(s, index, plot) {
     const series = s.series[index];
     if (!series)
         return [];
     const domain = barChartDomain(s);
+    const { along, across } = runs(s, plot);
     const n = s.data.length;
-    const slotWidth = n > 0 ? plot.width / n : 0;
-    const slotCenter = (i) => -plot.width / 2 + slotWidth * (i + 0.5);
-    const inner = slotWidth * clampUnit(s.theme.bar.slotFill);
-    const gap = s.theme.bar.groupGap;
+    const slot = n > 0 ? across / n : 0;
+    const inner = slot * clamp(s.style.barWidth, 0, 1);
+    const stacked = s.stack !== "none";
     let total = 0;
     for (let i = 0; i < s.series.length; i++)
         total += weightAt(s, i);
@@ -105,66 +87,56 @@ function seriesBars(s, index, plot, captioned) {
     let before = 0;
     for (let i = 0; i < index; i++)
         before += weightAt(s, i);
+    const gap = s.series.length > 1 ? s.style.barGap : 0;
+    const values = s.style.values;
     return s.data.map((row, rowIndex) => {
-        // The stack is built from the *live* contributions, so a series fading out
-        // lowers the segments above it as it goes.
-        const spans = barSpans(s.stacked ? weightedRow(s, row) : row, s.series, s.stacked);
-        const span = spans[index] ?? { from: 0, to: 0, value: 0 };
-        const cap = s.stacked ? stackCapIndex(row, s.series) : index;
-        const slotLeft = slotCenter(rowIndex) - inner / 2;
-        const x = s.stacked ? slotCenter(rowIndex) : slotLeft + unit * before + (unit * weight) / 2;
-        const width = s.stacked ? inner : Math.max(0, unit * weight - (s.series.length > 1 ? gap : 0));
-        // The figure printed is the row's own value, not the weighted one.
-        const value = num(row, series.field);
+        // Built from live contributions, so a fading series lowers the segments beyond it.
+        const spans = barSpans(row, s.series, s.stack, s.weights);
+        const span = spans[index] ?? { from: 0, to: 0, value: 0, outer: false };
+        const centre = slotAt(s, rowIndex, across);
+        const offset = -inner / 2 + unit * before + (unit * weight) / 2;
+        let caption = "";
+        if (values !== "none" && span.value !== 0) {
+            if (!stacked || values === "inside" || s.stack === "percent")
+                caption = valueLabel(s, domain, stacked ? span.value : num(row, series.field));
+            else if (span.outer)
+                caption = valueLabel(s, domain, span.to);
+        }
         return {
-            x,
-            width,
-            from: valueToY(domain, plot, span.from),
-            to: valueToY(domain, plot, span.to),
-            round: cap === index,
-            value,
-            ...(captioned && { caption: valueLabel(s, domain, value) }),
+            center: stacked ? centre : centre + (s.orientation === "horizontal" ? -offset : offset),
+            thickness: stacked ? inner : Math.max(0, unit * weight - gap),
+            from: valueToPx(domain, along, span.from),
+            to: valueToPx(domain, along, span.to),
+            round: span.outer,
+            caption,
         };
     });
 }
-/**
- * How far each category is dimmed by the spotlight, one entry per row: 1 while
- * nothing is spotlit, falling to the theme's `dimOpacity` for every category but
- * the chosen one as the reveal climbs.
- */
+/** Per-row opacity: 1 while nothing is spotlit, falling to {@link SPOTLIGHT_DIM} for all but the chosen category. */
 function categoryDims(s) {
-    const focus = clampUnit(s.spotlightReveal);
-    const dim = s.theme.spotlight.dimOpacity;
+    const focus = clamp(s.spotlightReveal, 0, 1);
     const chosen = s.spotlight;
-    return s.data.map((_, i) => (focus <= 0 || chosen === i ? 1 : 1 - (1 - dim) * focus));
+    return s.data.map((_, i) => (focus <= 0 || chosen === i ? 1 : 1 - (1 - SPOTLIGHT_DIM) * focus));
 }
 /** The parts a bar chart's commands drive, found through its children. */
 function partsOf(children) {
-    const frame = cartesianViews(children);
-    if (!frame)
-        return null;
-    const cAxis = frame.below.find(CategoryAxis.is);
-    if (!VerticalAxis.is(frame.axis) || !cAxis)
-        return null;
+    const views = chartViews(children);
     return {
-        vAxis: frame.axis,
-        cAxis,
-        bars: frame.plot.filter(ChartBars.is),
-        legend: frame.below.find(ChartLegend.is) ?? null,
+        valueAxis: views.find((view) => VerticalAxis.is(view) || HorizontalAxis.is(view)) ?? null,
+        categoryAxis: views.find(CategoryAxis.is) ?? null,
+        bars: views.filter(ChartBars.is),
+        legend: views.find(ChartLegend.is) ?? null,
     };
 }
 /**
- * Move series `index`'s slot share to `target` with its legend entry, the group
- * reflowing. Its columns are drawn for every frame the move covers, and switch
- * off only once a hide has landed, so arriving at a time backwards shows what
- * arriving forwards does.
+ * Move series `index`'s share to `target` with its legend entry. Its bars stay
+ * drawn for every frame the move covers and switch off only once a hide has
+ * landed, so arriving at a time backwards matches arriving forwards.
  */
 function toggling(timeline, state, children, index, target) {
     const parts = partsOf(children);
-    if (!parts || !parts.bars[index])
+    if (!parts.bars[index])
         return timeline.wait(timeline.duration);
-    // Read through `weightAt`, so a chart whose stored weights are short still
-    // tweens from the 1 it is drawing at.
     const from = state.series.map((_, i) => weightAt(state, i));
     const start = from[index] ?? 1;
     const showing = state.series.map((s, i) => state.showing[i] ?? (s.enabled ?? true));
@@ -180,61 +152,42 @@ function toggling(timeline, state, children, index, target) {
     ]);
 }
 /**
- * A grouped or stacked bar chart, the sibling of the line chart and built the
- * same way, out of several of the same pieces:
- *
- * - `ChartCanvas` — the plot panel with a horizontal grid, under everything.
- * - `VerticalAxis` — the numeric value markers, staggering in bottom-to-top.
- * - {@link CategoryAxis} — the row of names beneath the baseline, one per row.
- * - {@link ChartBars} (one per series) — that series' column in every category,
- *   plus the figures printed on them.
- * - `ChartLegend` — a row of entries below the chart, one per series.
+ * A bar chart, vertical or horizontal, its series side by side, stacked, or
+ * stacked as shares of 100. Built like the line chart from `ChartCanvas`, a
+ * value axis, a {@link CategoryAxis}, one {@link ChartBars} per series and
+ * `ChartLegend`. Zero is always on the scale and bars grow about it, so a
+ * negative value draws the other way from the same `growth` signal.
  *
- * Every part reads the chart's entries through bindings, and the columns map
- * across the plot panel's own laid-out box, so a column's end lands exactly on
- * its marker. **Zero is always on the scale**, and the columns grow about it, so
- * a negative value draws downward out of the same `growth` signal.
- *
- * **Resting state is the finished chart**; `enter` arms every part on its first
- * frame. `showSeries`/`hideSeries`/`spotlightSeries` pick out a *series* (hiding
- * one reflows the group), `spotlightCategory`/`clearCategory` a *column of the
- * table*. A `to` of the value axis's `range` or `ticks` tweens from the domain
- * as drawn, so an auto axis rescales the columns continuously.
+ * Resting state is the finished chart; `enter` arms every part on its first
+ * frame. A `to` of the value axis's `range` or `ticks` tweens from the domain as
+ * drawn, so an auto axis rescales the bars continuously.
  */
 export const BarChart = component2d({
     key: "barChart",
     state: {
-        data: fresh(() => []),
+        data: fresh(() => [], { kind: "dataset" }),
+        // Names a column, not a value, like the line chart's `xField`.
         categoryField: "",
-        series: fresh(() => []),
-        stacked: false,
+        series: fresh(() => [], { kind: "series" }),
+        /** `vertical`: columns rise from a row of categories; `horizontal`: bars grow right from a column of them. */
+        orientation: Types.oneOf(["vertical", "horizontal"], { animatable: false }),
+        /** `stacked`: each series sits on the sum of those before it; `percent`: every category reads as shares of 100. */
+        stack: Types.oneOf(["none", "stacked", "percent"]),
         valueAxis: Types.custom({}, { resolve: resolveAxisDomain, lerp: lerpAxisEntry }),
         categoryAxis: Types.custom({}, { resolve: resolveAxisDomain, lerp: lerpAxisDomain }),
-        theme: Types.custom(DEFAULT_BAR_CHART_THEME, { resolve: resolveBarChartTheme, lerp: lerpBarChartTheme }),
-        /**
-         * Global rise of every column in `[0, 1]`, measured about the baseline: 0
-         * collapses them all onto it, 1 draws them at full length.
-         */
+        style: BAR_STYLE,
+        /** Rise of every bar about the baseline, `[0, 1]`: 0 collapses them onto it. */
         growth: 1,
-        /**
-         * How much of the slot each series claims, one entry per series: a weight
-         * rather than a switch, so hiding one is the others widening into the space.
-         * Seeded from each series' `enabled`.
-         */
-        weights: fresh(() => []),
-        /** The category spotlit, or `null` for none. The choice snaps; `spotlightReveal` is the animation. */
+        /** The category spotlit, or `null`. The choice snaps; `spotlightReveal` animates it. */
         spotlight: Types.custom(null),
-        /** How far the category spotlight is drawn in, `[0, 1]`. */
         spotlightReveal: 0,
-        /** Read as the chart is built: the legend is a part the chart builds or doesn't. */
-        showLegend: Types.boolean(true, { animatable: false }),
-        /** Read as the chart is built: whether each column prints the figure it plots. */
-        showValues: Types.boolean(false, { animatable: false }),
-        /** Whether each series' columns are drawn: on for every frame a show or hide covers, off once a hide lands. */
+        /** Each series' share of the slot, seeded from `enabled`: a weight rather than a switch, so hiding one widens the others. */
+        weights: Types.custom([], { private: true }),
+        /** Whether each series' bars are drawn: on for every frame a show or hide covers, off once a hide lands. */
         showing: Types.custom([], { private: true }),
     },
     defaults: {
-        // Its parts fill it; a node made of them would hug them.
+        // A node made of parts that fill would otherwise hug them.
         width: "fill",
         height: "fill",
         weights: (state) => state.series.map((s) => ((s.enabled ?? true) ? 1 : 0)),
@@ -242,162 +195,184 @@ export const BarChart = component2d({
     },
     allowedChildren: [],
     children: (state) => {
-        const theme = () => state.theme;
+        const style = () => state.style;
         const domain = () => barChartDomain(state);
         let plot;
-        // Before the panel is built or laid out it has no size, and the columns map onto nothing.
         const plotSize = () => laidOutSize(plot);
-        const captioned = state.showValues === true;
-        const vAxis = new VerticalAxis({
-            range: () => domain().range,
-            markers: () => domain().ticks,
-            captions: () => {
-                const d = domain();
-                return d.ticks.map((value) => valueLabel(state, d, value));
-            },
-            axis: () => theme().yAxis,
-            label: state.valueAxis.label ?? "",
-            width: "hug",
-            height: "fill",
-        });
-        const cAxis = new CategoryAxis({
-            categories: barCategories(state.data, state.categoryField),
-            axis: () => theme().xAxis,
-            label: state.categoryAxis.label ?? "",
-            dims: () => categoryDims(state),
-            width: "fill",
-            height: "hug",
-        });
+        const built = state.style;
+        const horizontal = state.orientation === "horizontal";
+        const categories = barCategories(state.data, state.categoryField);
+        const valueConfig = () => axisConfigOf(style(), horizontal ? "x" : "y");
+        const categoryConfig = () => axisConfigOf(style(), horizontal ? "y" : "x");
+        const valueCaptions = () => {
+            const d = domain();
+            return d.ticks.map((value) => valueLabel(state, d, value));
+        };
+        const showValue = horizontal ? built.showXAxis : built.showYAxis;
+        const showCategory = horizontal ? built.showYAxis : built.showXAxis;
+        const valueAxis = showValue
+            ? (horizontal
+                ? new HorizontalAxis({
+                    range: () => domain().range,
+                    markers: () => domain().ticks,
+                    captions: valueCaptions,
+                    axis: valueConfig,
+                    label: state.valueAxis.label ?? "",
+                    overhang: () => ({ left: overhang(style()), right: overhang(style()) }),
+                    width: "fill",
+                    height: "hug",
+                })
+                : new VerticalAxis({
+                    range: () => domain().range,
+                    markers: () => domain().ticks,
+                    captions: valueCaptions,
+                    axis: valueConfig,
+                    label: state.valueAxis.label ?? "",
+                    width: "hug",
+                    height: "fill",
+                }))
+            : undefined;
+        const categoryAxis = showCategory
+            ? new CategoryAxis({
+                categories,
+                axis: categoryConfig,
+                label: state.categoryAxis.label ?? "",
+                orientation: horizontal ? "vertical" : "horizontal",
+                dims: () => categoryDims(state),
+                width: horizontal ? "hug" : "fill",
+                height: horizontal ? "fill" : "hug",
+            })
+            : undefined;
+        const left = horizontal ? categoryAxis : valueAxis;
+        const bottom = horizontal ? valueAxis : categoryAxis;
+        const leftConfig = horizontal ? categoryConfig : valueConfig;
+        const ghost = left && bottom
+            ? columnGhost({
+                captions: horizontal ? () => categories : valueCaptions,
+                count: horizontal ? categories.length : barChartDomain(state).ticks.length,
+                text: () => leftConfig().labelStyle,
+                title: (horizontal ? state.categoryAxis.label : state.valueAxis.label) ?? "",
+                titleText: () => leftConfig().titleStyle,
+                tickPad: () => axisPads(leftConfig(), "right").tick,
+                titlePad: () => axisPads(leftConfig(), "right").title,
+            })
+            : undefined;
         const barSets = state.series.map((s, i) => new ChartBars({
-            bars: () => seriesBars(state, i, plotSize(), captioned),
-            baseline: () => baselinePx(domain(), plotSize()),
-            fill: () => resolveBarFill(theme().seriesFills, s, i),
-            barStroke: () => theme().bar.stroke,
-            barShadow: () => theme().bar.shadow,
-            cornerRadius: () => theme().bar.cornerRadius,
+            bars: () => seriesBars(state, i, plotSize()),
+            baseline: () => valueToPx(domain(), runs(state, plotSize()).along, baselineValue(domain())),
+            horizontal,
+            fill: () => seriesFill(style(), s, i),
+            cornerRadius: () => style().barRadius,
             growth: () => state.growth,
             dims: () => categoryDims(state),
-            showValues: captioned,
-            valueStyle: state.theme.valueStyle,
+            // A figure past a stack's end prints the stack's total; a percent stack has none worth printing, so prints its shares inside.
+            values: () => (built.values === "end" && state.stack === "percent" ? "inside" : built.values),
+            valueStyle: () => ({ ...valueText(style()), fontSize: Math.round(style().fontSize * 0.85) }),
             enabled: () => state.showing[i] ?? (s.enabled ?? true),
         }));
-        const below = [cAxis];
-        if (state.showLegend !== false) {
-            below.push(new ChartLegend({
+        const legendAt = built.legend;
+        const legend = legendAt !== "none"
+            ? new ChartLegend({
                 series: state.series,
-                swatches: () => state.series.map((s, i) => resolveBarFill(theme().seriesFills, 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,
-            }));
-        }
+                swatches: () => state.series.map((s, i) => seriesFill(style(), s, i)),
+                legend: () => legendConfigOf(style()),
+                flow: legendAt === "right" ? "vertical" : "horizontal",
+            })
+            : undefined;
+        const n = state.data.length;
+        // Category lines fall between the slots, never through a bar.
+        const boundaries = () => Array.from({ length: Math.max(0, n - 1) }, (_, i) => i + 1);
+        const slots = () => [0, Math.max(1, n)];
         plot = new Rect({
-            clip: true,
             children: [
                 new ChartCanvas({
-                    fill: () => theme().plotArea.fill,
-                    shadow: () => theme().plotArea.shadow,
-                    xGridStroke: () => theme().xAxis.lineStyle,
-                    yGridStroke: () => theme().yAxis.lineStyle,
-                    // No vertical rules: the horizontal axis is categorical, so there is no
-                    // numeric position along it for a grid line to mark.
-                    xMarkers: [],
-                    yMarkers: () => domain().ticks,
-                    xExtent: () => [0, 1],
-                    yExtent: () => domain().range,
+                    fill: () => style().background,
+                    xGridStroke: () => style().verticalGrid,
+                    yGridStroke: () => style().horizontalGrid,
+                    xMarkers: horizontal ? () => domain().ticks : boundaries,
+                    yMarkers: horizontal ? boundaries : () => domain().ticks,
+                    xExtent: horizontal ? () => domain().range : slots,
+                    yExtent: horizontal ? slots : () => domain().range,
+                    axisStroke: () => style().axisStroke,
+                    xAxisAt: () => (horizontal ? 0 : baselineValue(domain())),
+                    yAxisAt: () => (horizontal ? baselineValue(domain()) : 0),
                 }),
                 ...barSets,
-                new ChartBorder({ stroke: () => theme().plotArea.stroke }),
             ],
         });
-        const gutter = new VerticalAxis({
-            opacity: 0,
-            range: () => domain().range,
-            markers: () => domain().ticks,
-            axis: () => theme().yAxis,
-            label: state.valueAxis.label ?? "",
-            width: "hug",
-            height: 0,
-        });
-        return asParts([cartesianFrame({ axis: vAxis, plot, gutter, below })]);
+        return asParts([
+            cartesianFrame({
+                left,
+                ghost,
+                plot,
+                bottom,
+                legend,
+                legendAt,
+                gap: () => frameGap(style()),
+                padding: () => ({
+                    top: headroom(style()),
+                    right: horizontal && bottom ? overhang(style()) : 0,
+                    left: horizontal && bottom && !left ? overhang(style()) : 0,
+                    bottom: 0,
+                }),
+            }),
+        ]);
     },
     commands: {
-        /**
-         * Animate the whole chart in: the two axes stagger their markers and
-         * captions in, the columns rise from the baseline, and the legend fades up
-         * last. Its first frame arms every part: markers and captions shifted and
-         * transparent, columns collapsed, the legend dropped and transparent.
-         * `duration` is the **whole** entrance; the beats are shares of it.
-         */
+        /** Axes stagger in, bars rise from the baseline, the legend fades up last. `duration` is the whole entrance. */
         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) => {
+            run: (timeline, state, children) => {
                 const parts = partsOf(children);
-                if (!parts)
-                    return timeline.wait(timeline.duration);
                 const duration = timeline.duration;
-                const axes = duration * AXES_SHARE;
-                const rise = duration * BARS_SHARE;
+                const axes = duration * ENTER_SHARE.axes;
+                const rise = duration * ENTER_SHARE.marks;
                 const { legend } = parts;
                 const at0 = (piece) => ({ at: 0, duration: 0, piece });
-                // Without a legend the beat is still its share of the whole.
                 return beats(timeline, [
                     at0(timeline.animate(() => ({ growth: 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.cAxis.run("enter", { slide: 24 }) },
+                    ...(legend ? [at0(legend.to({ opacity: 0, ...legendAway(state.style.legend) }))] : []),
+                    ...(parts.valueAxis ? [{ at: 0, duration: axes, piece: parts.valueAxis.run("enter", { slide: 24 }) }] : []),
+                    ...(parts.categoryAxis ? [{ at: 0, duration: axes, piece: parts.categoryAxis.run("enter", { slide: 24 }) }] : []),
                     // No priming to 0 first: the value at `t` is a function of `t`.
                     { at: axes, duration: rise, piece: timeline.animate((t) => ({ growth: t })) },
-                    ...(legend ? [{ at: axes + rise, duration: duration * LEGEND_SHARE, piece: legend.to({ opacity: 1, y: 0 }) }] : []),
+                    ...(legend ? [{ at: axes + rise, duration: duration * ENTER_SHARE.legend, piece: legend.to({ opacity: 1, x: 0, y: 0 }) }] : []),
                 ]);
             },
         },
-        /** Show series `index`: its columns come back, the group reflowing to make room, with its legend entry. */
+        /** Bring series `index` back, the group reflowing to make room, with its legend entry. */
         showSeries: {
             args: { seriesIndex: SERIES_ARG },
             easing: easeOut(),
             run: (timeline, state, children) => toggling(timeline, state, children, timeline.args.seriesIndex, 1),
         },
-        /**
-         * Hide series `index`: its columns narrow away (or, stacked, sink out of the
-         * stack) while the rest of the group widens into the space — the mirror of
-         * `showSeries`.
-         */
+        /** The mirror of `showSeries`: bars narrow away (stacked, sink out) while the rest widen into the space. */
         hideSeries: {
             args: { seriesIndex: SERIES_ARG },
             easing: easeOut(),
             run: (timeline, state, children) => toggling(timeline, state, children, timeline.args.seriesIndex, 0),
         },
-        /**
-         * Fade every other series — its columns **and its legend entry** — to focus
-         * on `index`, which comes back to full. Nothing moves, so the group doesn't
-         * reflow.
-         */
+        /** Fade every other series, bars and legend entry, to focus on `index`. Nothing moves, so the group does not reflow. */
         spotlightSeries: {
             args: { seriesIndex: SERIES_ARG },
             easing: easeOut(),
-            run: (timeline, state, children) => {
+            run: (timeline, _state, children) => {
                 const parts = partsOf(children);
-                if (!parts)
-                    return timeline.wait(timeline.duration);
                 const index = timeline.args.seriesIndex;
-                const dim = state.theme.spotlight.dimOpacity;
                 return timeline.together([
-                    ...parts.bars.map((bars, i) => bars.to({ opacity: i === index ? 1 : dim })),
+                    ...parts.bars.map((bars, i) => bars.to({ opacity: i === index ? 1 : SPOTLIGHT_DIM })),
                     ...(parts.legend ? [parts.legend.run("spotlightSeries", { index })] : []),
+                    timeline.wait(timeline.duration),
                 ]);
             },
         },
         /**
-         * Spotlight one **category**: every other category's columns and caption
-         * fade to the theme's `dimOpacity`. Called while another is lit, the focus
-         * moves directly: only the dimming changes, so nothing retracts first. A
-         * category that is not there takes its slot and changes nothing.
+         * Fade every other category's bars and caption to {@link SPOTLIGHT_DIM}. While
+         * another is lit the focus moves directly. A missing category takes its slot
+         * and changes nothing.
          */
         spotlightCategory: {
             args: { categoryIndex: Types.number(0, { min: 0, step: 1 }) },
@@ -410,11 +385,7 @@ export const BarChart = component2d({
                 return timeline.animate((t) => ({ spotlight: index, spotlightReveal: from + (1 - from) * t }));
             },
         },
-        /**
-         * Drop the category spotlight, every category back to full. The lit
-         * category is held until the fade lands; a no-op when nothing is lit, which
-         * still takes its slot.
-         */
+        /** Every category back to full; the lit one is held until the fade lands. A no-op when nothing is lit, which still takes its slot. */
         clearCategory: {
             args: {},
             easing: easeOut(),