@motionscript/charts 0.1.0-alpha.3 → 0.1.0-alpha.5

package/src/bar-chart/bar-chart.ts

@@ -1,814 +1,820 @@
-import {
-  command,
-  node,
-  Node2D,
-  Rect,
-  easeOut,
-  property,
-  type CommandArgs,
-  type DataRecord,
-  type Command,
-  type EasingFunction,
-  type NodeConfig,
-  type Node2DProps,
-} from "@motionscript/sdk"
-
-import { ChartBorder } from "../kit/chart-border"
-import { ChartCanvas } from "../kit/chart-canvas"
-import { ChartLegend } from "../kit/chart-legend"
-import { VerticalAxis } from "../kit/vertical-axis"
-import {
-  clampUnit,
-  formatMarker,
-  lerpAxisDomain,
-  markerValues,
-  num,
-  resolveAxisDomain,
-  type AxisDomainConfig,
-  type Range,
-} from "../kit/shared"
-import { formatNumber } from "@motionscript/sdk/component"
-import {
-  asCommand,
-  drive,
-  hold,
-  sequence as sequenceOf,
-  together,
-  type Seekable,
-} from "@motionscript/sdk/component"
-import { CategoryAxis } from "./category-axis"
-import { ChartBars, type BarGeometry } from "./chart-bars"
-import {
-  DEFAULT_BAR_CHART_THEME,
-  barCategories,
-  barSpans,
-  lerpBarChartTheme,
-  resolveBarChartTheme,
-  resolveBarFill,
-  resolveBarScale,
-  stackCapIndex,
-  type BarChartConfig,
-  type BarChartTheme,
-  type BarSeries,
-} from "./shared"
-
-export interface BarChartProps extends Node2DProps {
-  /** One row per category — a plain record of field name to value. */
-  data: DataRecord[]
-  /**
-   * Key into each row for its category caption, drawn beneath the baseline.
-   * Named `categoryField` rather than `category` for the same reason the line
-   * chart's is `xField`: it names a *column*, not a value.
-   */
-  categoryField: string
-  /** One entry per bar series: which column it plots, its `label`, its `fill`. */
-  series: BarSeries[]
-  /**
-   * When `true` every category's series stack into one column; when `false`
-   * (the default) each series gets its own bar, grouped side by side within the
-   * category's slot.
-   */
-  stacked?: boolean
-  /** The value axis's domain: caption, scale range, and tick placement. */
-  valueAxis?: AxisDomainConfig
-  /** The category axis's domain. Only its `label` is read — the slots are the rows. */
-  categoryAxis?: AxisDomainConfig
-  /**
-   * The chart's visual theme — bar palette and geometry, axis furniture, plot
-   * panel paint, legend, value figures. Every branch is optional and deep-merged
-   * onto {@link DEFAULT_BAR_CHART_THEME}.
-   */
-  theme?: BarChartTheme
-  /** Whether the legend row below the plot is drawn at all. */
-  showLegend?: boolean
-  /** Whether each column prints the figure it plots. */
-  showValues?: boolean
-}
-
-/**
- * Layout constants for the composition, all in px — the line chart's, so the two
- * sit at the same size in the same box and a scene can swap one for the other
- * without re-tuning its layout.
- */
-/** Left gutter reserved for the value axis markers. */
-const Y_AXIS_GUTTER = 64
-/** Bottom gutter (within the chart area) reserved for the category captions. */
-const X_AXIS_GUTTER = 40
-/** Height reserved below the chart area for the legend row. */
-const LEGEND_GUTTER = 56
-/** Extra left/bottom room when an axis caption is shown. */
-const Y_LABEL_GUTTER = 34
-const X_LABEL_GUTTER = 30
-/** Headroom above the plot, so a column reaching the top marker isn't flush to it. */
-const TOP_HEADROOM = 24
-/** Right gutter so the last slot isn't flush with the box edge. */
-const RIGHT_GUTTER = 20
-
-/** How far the legend starts below its slot when it enters, in px. */
-const LEGEND_SLIDE = 20
-
-/**
- * How {@link BarChart.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 — the entrance takes exactly the time it was
- * given, for the reason spelt out on `LineChart.enter`.
- */
-/**
- * The signals the bar chart's own commands move, as props types.
- *
- * Written out rather than reusing `BarChartProps` because these are signals of
- * the chart's own — how far the columns have risen, and which category is lit —
- * rather than part of what an author states about it. Same reason the line chart
- * types its `RegionState` separately.
- */
-type CategorySpotlight = { spotlight: number | null; spotlightReveal: number }
-type BarGrowth = { growth: number }
-
-const AXES_SHARE = 0.35
-const BARS_SHARE = 0.5
-const LEGEND_SHARE = 0.15
-
-/**
- * A grouped or stacked bar chart, composed from independent parts rather than
- * one monolithic draw — the sibling of the {@link LineChart} family, built the
- * same way and 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 of
- *   the data, staggering in left-to-right.
- * - {@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.
- *
- * The parts are laid out from this node's `layoutBounds` exactly as the line
- * chart's are: a left gutter for the value axis, a bottom gutter for the
- * captions, the plot filling what's left, and the legend row beneath the whole
- * thing. Every child's position and size is bound reactively, so the chart
- * re-flows if its box changes, and the bars read the same resolved scale the
- * axis does, so a column's end lands exactly on its marker.
- *
- * **Resting state is the finished chart** — the same bargain the line chart
- * makes: the studio paints a node's Initial state on a paused canvas, so a chart
- * that only appeared once a command had run would be edited blind. {@link enter}
- * arms every part back to its pre-entrance state before animating.
- *
- * **Zero is always on the scale** (see `barValueExtent`), and the columns
- * grow about it rather than about the plot floor, so a negative value draws
- * downward out of the same `growth` signal that draws a positive one up.
- *
- * Past the entrance, two things move the chart:
- * {@link showSeries}/{@link hideSeries}/{@link spotlightSeries} pick out a
- * *series* — and hiding one **reflows the group**, the remaining columns
- * widening into the space as it goes, rather than leaving a hole where it was —
- * while {@link spotlightCategory}/{@link clearCategory} pick out a *column of
- * the table*, dimming every other category and its caption with it.
- */
-@node({
-  key: "barChart",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    defaultWidthMode: "fixed",
-    defaultHeightMode: "fixed",
-    acceptsChildren: true,
-  },
-  seed: {
-    width: 760,
-    height: 460,
-  },
-})
-export class BarChart extends Node2D<BarChartProps> {
-  @property({ default: () => [] as DataRecord[] }) declare data: DataRecord[]
-  @property({ default: "" }) declare categoryField: string
-  @property({ default: () => [] as BarSeries[] }) declare series: BarSeries[]
-  @property({ default: false }) declare stacked: boolean
-  /**
-   * The value axis's domain (label/range/ticks), tweenable and mappable exactly
-   * as the line chart's axes are: the mapper merges a partial input onto the
-   * previous resolved domain and the tween interpolates numerically, so
-   * `chart.to({ data: { valueAxis: { range: [0, 10] } }, duration: 1 })` smoothly
-   * rescales every column. The axis *label* text is captured once at construction.
-   */
-  @property({
-    default: {},
-    mapper: resolveAxisDomain,
-    tween: lerpAxisDomain,
-  })
-  declare valueAxis: AxisDomainConfig
-  @property({
-    default: {},
-    mapper: resolveAxisDomain,
-    tween: lerpAxisDomain,
-  })
-  declare categoryAxis: AxisDomainConfig
-  @property({
-    default: DEFAULT_BAR_CHART_THEME,
-    mapper: resolveBarChartTheme,
-    tween: lerpBarChartTheme,
-  })
-  declare theme: BarChartTheme
-
-  /**
-   * Global rise of every column in `[0, 1]`, measured about the baseline: 0
-   * collapses them all onto it, 1 draws them at full length. Each
-   * {@link ChartBars}' own `growth` is bound to this, so tweening this one
-   * signal raises the whole chart in proportion.
-   */
-  @property({ default: 1 }) declare growth: number
-
-  /**
-   * How much of the slot each series currently claims, one entry per series.
-   *
-   * A *weight* rather than a boolean, because that is what makes hiding a series
-   * an animation instead of a jump: the grouped columns divide the slot in
-   * proportion to these, so tweening one to 0 has the remaining columns widen
-   * into the space as it shrinks away, and a stacked segment's contribution to
-   * the stack fades out with it. Seeded from each series' `enabled` field.
-   */
-  @property({ default: () => [] as number[] }) declare weights: number[]
-
-  /**
-   * The category currently spotlit, or `null` for none. Held as a plain reactive
-   * value rather than a tweened one: the *choice* snaps, and the animation is
-   * {@link spotlightReveal} dimming everything else.
-   */
-  @property({ default: null }) declare spotlight: number | null
-
-  /** How far the category spotlight is drawn in, `[0, 1]`. */
-  @property({ default: 0 }) declare spotlightReveal: number
-
-  // ---- Part handles (built in the constructor) --------------------------
-  private vAxis: VerticalAxis
-  private cAxis: CategoryAxis
-  private legend: ChartLegend | null = null
-  private barSets: ChartBars[] = []
-
-  /**
-   * `this.theme` read back through its *resolved* shape — the same
-   * loose-declared/resolved-stored idiom as a shape's `fill`/`stroke`, and as
-   * the line chart's own theme.
-   */
-  private get resolvedTheme(): BarChartConfig {
-    return this.theme as unknown as BarChartConfig
-  }
-
-  // ---- Derived scale ----------------------------------------------------
-
-  /** Fallback marker count when the value axis states no ticks. */
-  private static readonly DEFAULT_MARKERS = 5
-
-  private get valueScale(): Range {
-    const divisions =
-      (this.valueAxis.ticks?.length ?? BarChart.DEFAULT_MARKERS) - 1
-    return resolveBarScale(
-      this.data,
-      this.series,
-      this.stacked,
-      this.valueAxis.range,
-      divisions
-    )
-  }
-
-  /**
-   * A value written down as this chart's value axis says — the axis ticks and
-   * the figures printed on the columns both read through here, so the two
-   * cannot disagree about what a number looks like.
-   */
-  private valueLabel(value: number): string {
-    const pattern = this.valueAxis.format
-    return pattern === undefined
-      ? formatMarker(value)
-      : formatNumber(value, pattern)
-  }
-
-  /** The value axis ticks: the explicit ones, else five across the scale. */
-  private get resolvedMarkers(): number[] {
-    return (
-      this.valueAxis.ticks ??
-      markerValues(this.valueScale, BarChart.DEFAULT_MARKERS - 1)
-    )
-  }
-
-  // ---- Plot geometry, all derived from layoutBounds -----------------------
-
-  private get hasValueLabel(): boolean {
-    return this.valueAxis.label !== ""
-  }
-  private get hasCategoryLabel(): boolean {
-    return this.categoryAxis.label !== ""
-  }
-
-  private get leftInset(): number {
-    return Y_AXIS_GUTTER + (this.hasValueLabel ? Y_LABEL_GUTTER : 0)
-  }
-  private get bottomInset(): number {
-    return X_AXIS_GUTTER + (this.hasCategoryLabel ? X_LABEL_GUTTER : 0)
-  }
-
-  /** The plot rectangle in node space: `{ left, right, top, bottom }` (y-up). */
-  private plotBox(): {
-    left: number
-    right: number
-    top: number
-    bottom: number
-  } {
-    const W = this.layoutBounds.width
-    const H = this.layoutBounds.height
-    const areaTop = H / 2
-    const areaBottom = -H / 2 + (this.legend ? LEGEND_GUTTER : 0)
-    const left = -W / 2 + this.leftInset
-    const right = W / 2 - RIGHT_GUTTER
-    const top = areaTop - TOP_HEADROOM
-    const bottom = areaBottom + this.bottomInset
-    return { left, right, top, bottom }
-  }
-
-  /** Width and height of the plot, in px. */
-  private plotSize(): { w: number; h: number } {
-    const { left, right, top, bottom } = this.plotBox()
-    return { w: right - left, h: top - bottom }
-  }
-
-  /** Map a value onto the plot's **centred** pixel space (origin at its centre, y-up). */
-  private valueToY(value: number): number {
-    const [min, max] = this.valueScale
-    const { h } = this.plotSize()
-    if (max <= min) return -h / 2
-    return ((value - min) / (max - min) - 0.5) * h
-  }
-
-  /**
-   * Pixel y of the line every column grows from.
-   *
-   * Zero, clamped onto the scale — so an author who *did* crop the axis to
-   * `[40, 100]` gets columns rising from the plot floor rather than from a
-   * baseline off the bottom of the panel.
-   */
-  private get baselinePx(): number {
-    const [min, max] = this.valueScale
-    return this.valueToY(Math.min(Math.max(0, min), max))
-  }
-
-  // ---- Slot geometry ----------------------------------------------------
-
-  /** Width of one category's slot across the plot. */
-  private get slotWidth(): number {
-    const n = this.data.length
-    return n > 0 ? this.plotSize().w / n : 0
-  }
-
-  /** Centre x of category `i`'s slot, in the plot's centred space. */
-  private slotCenter(index: number): number {
-    return -this.plotSize().w / 2 + this.slotWidth * (index + 0.5)
-  }
-
-  /** The part of a slot the columns fill — the rest is the channel between categories. */
-  private get slotInner(): number {
-    return this.slotWidth * clampUnit(this.resolvedTheme.bar.slotFill)
-  }
-
-  /** Series `i`'s live share of the slot; 0 once it has been hidden. */
-  private weightAt(index: number): number {
-    return Math.max(0, this.weights[index] ?? 1)
-  }
-
-  /** Total live share across the series — the slot's inner width divides by this. */
-  private get totalWeight(): number {
-    let sum = 0
-    for (let i = 0; i < this.series.length; i++) sum += this.weightAt(i)
-    return sum > 0 ? sum : 1
-  }
-
-  /** Live share of every series *before* `index`, for the grouped offset. */
-  private weightBefore(index: number): number {
-    let sum = 0
-    for (let i = 0; i < index; i++) sum += this.weightAt(i)
-    return sum
-  }
-
-  /**
-   * Series `index`'s columns, mapped into the plot's centred pixel space.
-   *
-   * Both modes come out of one walk over the rows: a grouped series divides the
-   * slot with its siblings and every column runs from zero, a stacked one takes
-   * the whole slot and each column runs from the running total below it. The
-   * live {@link weights} scale the grouped widths and the stacked contributions
-   * alike, which is what lets `hideSeries` reflow rather than punch a hole.
-   */
-  private seriesBars(index: number): BarGeometry[] {
-    const series = this.series[index]
-    if (!series) return []
-    const stacked = this.stacked
-    const inner = this.slotInner
-    const gap = this.resolvedTheme.bar.groupGap
-    const unit = inner / this.totalWeight
-    const weight = this.weightAt(index)
-
-    return this.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 instead of dropping them by a
-      // step when it finally switches off. A grouped row needs no such scaling —
-      // there its weight moves the column's width, not its length.
-      const spans = barSpans(
-        stacked ? this.weightedRow(row) : row,
-        this.series,
-        stacked
-      )
-      const span = spans[index] ?? { from: 0, to: 0, value: 0 }
-      const cap = stacked ? stackCapIndex(row, this.series) : index
-
-      const slotLeft = this.slotCenter(rowIndex) - inner / 2
-      const x = stacked
-        ? this.slotCenter(rowIndex)
-        : slotLeft + unit * this.weightBefore(index) + (unit * weight) / 2
-      const width = stacked
-        ? inner
-        : Math.max(0, unit * weight - (this.series.length > 1 ? gap : 0))
-
-      return {
-        x,
-        width,
-        from: this.valueToY(span.from),
-        to: this.valueToY(span.to),
-        round: cap === index,
-        // The figure printed is the row's own value, not the weighted one — a
-        // series on its way out should not be seen counting down.
-        value: num(row, series.field),
-      }
-    })
-  }
-
-  /**
-   * `row` with each series' value scaled by that series' live {@link weights}
-   * entry — what the stacked spans are measured from.
-   */
-  private weightedRow(row: DataRecord): DataRecord {
-    const scaled: DataRecord = { ...row }
-    this.series.forEach((s, i) => {
-      const value = row[s.field]
-      if (typeof value === "number") scaled[s.field] = value * this.weightAt(i)
-    })
-    return scaled
-  }
-
-  /**
-   * 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.
-   */
-  private categoryDims(): number[] {
-    const focus = clampUnit(this.spotlightReveal)
-    const dim = this.resolvedTheme.spotlight.dimOpacity
-    const chosen = this.spotlight
-    return this.data.map((_, i) =>
-      focus <= 0 || chosen === i ? 1 : 1 - (1 - dim) * focus
-    )
-  }
-
-  // ---- Build ------------------------------------------------------------
-
-  constructor(props?: NodeConfig<BarChart, BarChartProps>) {
-    super(props)
-
-    // The whole chart is composed from plain props/`data` — no context needed,
-    // so the parts are built here (super() applied the props above). Everything
-    // a *leaf* reads live in `renderSelf` — each series' geometry, paint and
-    // dim, the panel's fill, the border's stroke — is passed as a closure rather
-    // than a snapshot, so `chart.to({ theme })` and
-    // `chart.to({ valueAxis: { range } })` genuinely animate the drawn chart.
-    const enabled = this.series.map((s) => s.enabled ?? true)
-    this.weights = enabled.map((on) => (on ? 1 : 0))
-    const showLegend = props?.showLegend !== false
-    const showValues = props?.showValues === true
-
-    this.vAxis = new VerticalAxis({
-      range: () => this.valueScale,
-      markers: () => this.resolvedMarkers,
-      axis: () => this.resolvedTheme.yAxis,
-      label: this.valueAxis.label ?? "",
-      width: "hug",
-      height: "fill",
-    })
-    this.vAxis.labelFor = (value) => this.valueLabel(value)
-
-    this.cAxis = new CategoryAxis({
-      categories: barCategories(this.data, this.categoryField),
-      axis: () => this.resolvedTheme.xAxis,
-      label: this.categoryAxis.label ?? "",
-      dims: () => this.categoryDims(),
-      width: "fill",
-      height: "hug",
-    })
-
-    this.barSets = this.series.map(
-      (s, i) =>
-        new ChartBars({
-          bars: () => this.seriesBars(i),
-          baseline: () => this.baselinePx,
-          fill: () => resolveBarFill(this.resolvedTheme.seriesFills, s, i),
-          barStroke: () => this.resolvedTheme.bar.stroke,
-          barShadow: () => this.resolvedTheme.bar.shadow,
-          cornerRadius: () => this.resolvedTheme.bar.cornerRadius,
-          growth: () => this.growth,
-          dims: () => this.categoryDims(),
-          showValues,
-          valueStyle: this.resolvedTheme.valueStyle,
-          enabled: enabled[i],
-        })
-    )
-    // The figures on the columns are the same numbers the value axis ticks, so
-    // they read through the same format.
-    for (const set of this.barSets) set.labelFor = (value) => this.valueLabel(value)
-
-    if (showLegend) {
-      this.legend = new ChartLegend({
-        series: this.series,
-        swatches: () =>
-          this.series.map((s, i) =>
-            resolveBarFill(this.resolvedTheme.seriesFills, s, i)
-          ),
-        legend: () => this.resolvedTheme.legend,
-      })
-    }
-
-    const plot = new Rect({
-      clip: true,
-      children: [
-        new ChartCanvas({
-          fill: () => this.resolvedTheme.plotArea.fill,
-          shadow: () => this.resolvedTheme.plotArea.shadow,
-          xGridStroke: () => this.resolvedTheme.xAxis.lineStyle,
-          yGridStroke: () => this.resolvedTheme.yAxis.lineStyle,
-          // No vertical rules: the horizontal axis is categorical, so there is
-          // no numeric position along it for a grid line to mark. The channel
-          // between slots does that job, and better.
-          xMarkers: [],
-          yMarkers: () => this.resolvedMarkers,
-          xExtent: () => [0, 1] as Range,
-          yExtent: () => this.valueScale,
-        }),
-        ...this.barSets,
-        new ChartBorder({
-          stroke: () => this.resolvedTheme.plotArea.stroke,
-        }),
-      ],
-    })
-
-    // Invisible twin of the value axis, reserving the same left gutter under the
-    // plot so the category row starts at the plot's left edge rather than the
-    // chart's — and so a caption lands under the columns it names.
-    const gutterSpacer = new VerticalAxis({
-      opacity: 0,
-      range: () => this.valueScale,
-      markers: () => this.resolvedMarkers,
-      axis: () => this.resolvedTheme.yAxis,
-      label: this.valueAxis.label ?? "",
-      width: "hug",
-      height: 0,
-    })
-
-    const below: Node2D[] = [this.cAxis]
-    if (this.legend) below.push(this.legend)
-
-    this.add(
-      new Rect({ flow: "vertical",
-        width: "fill",
-        height: "fill",
-        children: [
-          new Rect({ flow: "horizontal",
-            height: "fill",
-            width: "fill",
-            children: [this.vAxis, plot],
-          }),
-          new Rect({ flow: "horizontal",
-            width: "fill",
-            children: [
-              gutterSpacer,
-              new Rect({ flow: "vertical", width: "fill", gap: 20, children: below }),
-            ],
-          }),
-        ],
-      })
-    )
-  }
-
-  // ---- Orchestrated entrance --------------------------------------------
-
-  /**
-   * Prime every part at its pre-entrance state — axis markers and captions
-   * shifted and transparent, columns collapsed onto the baseline, legend dropped
-   * and transparent.
-   *
-   * Called by {@link enter} before its first frame so nothing flashes ahead of
-   * its beat. Idempotent, and public so a scene can hide a chart ahead of time
-   * without starting the entrance.
-   */
-  arm(): void {
-    this.vAxis.arm()
-    this.cAxis.arm()
-    this.growth = 0
-    this.legend?.set({ opacity: 0, y: -LEGEND_SLIDE })
-  }
-
-  /**
-   * 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.
-   *
-   * `duration` is the **whole** entrance. The phases are shares of it, not
-   * multiples — a command that declares 1.4 seconds has to take 1.4 seconds,
-   * because that is the slot the timeline lays out for it, the length its
-   * parallel siblings are timed against, and its contribution to the scene's own
-   * duration.
-   */
-  @command()
-  enter(args: CommandArgs<Record<string, never>> & { duration: number }): Command<Record<string, never>> {
-    const { duration } = args
-    const easing = args.easing ?? easeOut()
-    this.arm()
-
-    return asCommand(
-      sequenceOf(
-        together(
-          this.vAxis.enter({ data: { slide: 24 }, duration: duration * AXES_SHARE, easing }),
-          this.cAxis.enter({ data: { slide: 24 }, duration: duration * AXES_SHARE, easing })
-        ),
-        this.riseBars(duration * BARS_SHARE, easing),
-        ...(this.legend
-          ? [this.legend.to({ data: { opacity: 1, y: 0 }, duration: duration * LEGEND_SHARE, easing })]
-          : [])
-      ),
-      duration
-    )
-  }
-
-  /** Tween {@link growth} `0 → 1`, raising every column about the baseline. */
-  private riseBars(
-    duration: number,
-    easing: EasingFunction
-  ): Command<BarGrowth> {
-    // No priming to 0 first: the value at `t` is a function of `t`, so a repeat
-    // call re-raises by definition rather than by having reset something.
-    return this.command<BarGrowth>((t) => ({ growth: t }), duration, easing)
-  }
-
-  /**
-   * Show series `index`: bring its columns back, the group reflowing to make
-   * room as they arrive, in lockstep with its legend entry growing in.
-   */
-  @command({ args: [{ key: "seriesIndex", kind: "series", default: 0, min: 0, step: 1 }] })
-  showSeries(args: CommandArgs<{ seriesIndex: number }>): Command<Record<string, never>> {
-    const { seriesIndex = 0 } = args.data ?? {}
-    return this.toggleSeries(seriesIndex, 1, args.duration ?? 0.35, args.easing ?? easeOut())
-  }
-
-  /**
-   * Hide series `index`: its columns narrow away (or, stacked, sink out of the
-   * stack) while the rest of the group widens into the space, its legend entry
-   * shrinking beside them — the mirror of {@link showSeries}.
-   */
-  @command({ args: [{ key: "seriesIndex", kind: "series", default: 0, min: 0, step: 1 }] })
-  hideSeries(args: CommandArgs<{ seriesIndex: number }>): Command<Record<string, never>> {
-    const { seriesIndex = 0 } = args.data ?? {}
-    return this.toggleSeries(seriesIndex, 0, args.duration ?? 0.35, args.easing ?? easeOut())
-  }
-
-  /**
-   * Move series `index`'s slot share to `target`, with its legend entry.
-   *
-   * One method for both directions, so the pair cannot drift apart. `enabled`
-   * rides in the same value as the weight rather than being set before or after,
-   * which is what makes arriving at a time backwards show what arriving forwards
-   * does.
-   */
-  private toggleSeries(
-    index: number,
-    target: number,
-    duration: number,
-    easing: EasingFunction
-  ): Command<Record<string, never>> {
-    const bars = this.barSets[index]
-    if (!bars) return asCommand(hold(duration))
-
-    return asCommand(
-      together(
-        this.tweenWeight(index, target, duration, easing),
-        drive(duration, (t) => {
-          const share = t >= 1 ? target : Math.max(target, 1 - t)
-          bars.set({ enabled: target > 0 || share > 0 })
-        }),
-        ...(this.legend
-          ? [
-            target > 0
-              ? this.legend.showSeries({ data: { index }, duration, easing })
-              : this.legend.hideSeries({ data: { index }, duration, easing }),
-          ]
-          : [])
-      ),
-      duration
-    )
-  }
-
-  /**
-   * Fade out every other series — its columns **and its legend entry** — to
-   * focus attention on `index`, which comes back to full. Nothing moves, so the
-   * group doesn't reflow.
-   */
-  @command({ args: [{ key: "seriesIndex", kind: "series", default: 0, min: 0, step: 1 }] })
-  spotlightSeries(args: CommandArgs<{ seriesIndex: number }>): Command<Record<string, never>> {
-    const { seriesIndex = 0 } = args.data ?? {}
-    const duration = args.duration ?? 0.35
-    const easing = args.easing ?? easeOut()
-    const dim = this.resolvedTheme.spotlight.dimOpacity
-    return asCommand(
-      together(
-        ...this.barSets.map((bars, i) =>
-          bars.to({ data: { opacity: i === seriesIndex ? 1 : dim }, duration, easing })
-        ),
-        ...(this.legend
-          ? [this.legend.spotlightSeries({ data: { index: seriesIndex }, duration, easing })]
-          : [])
-      ),
-      duration
-    )
-  }
-
-  /** Ease series `index`'s slot share toward `target`, reflowing the group. */
-  private tweenWeight(
-    index: number,
-    target: number,
-    duration: number,
-    easing: EasingFunction
-  ): Seekable {
-    // Read through `weightAt` rather than off the array, so a chart whose stored
-    // weights are short (or absent) still tweens from the 1 it is drawing at.
-    const from = this.series.map((_, i) => this.weightAt(i))
-    const start = from[index] ?? 1
-    if (start === target) return hold(duration)
-
-    return drive(duration, (t) => {
-      const next = [...from]
-      next[index] = start + (target - start) * easing(t)
-      this.weights = next
-    })
-  }
-
-  // ---- Per-category ------------------------------------------------------
-
-  /**
-   * Spotlight one **category** — one column of the table rather than one series:
-   * every other category's bars and its caption fade to the theme's
-   * `dimOpacity`, and the chosen one stays full.
-   *
-   * The counterpart of the line chart's `spotlightRegion`, and the same shape of
-   * thing: it picks out a slice of the plot without changing what is drawn.
-   * Calling it while another category is already lit moves the focus directly —
-   * only the dimming changes, so there is nothing to retract first.
-   */
-  @command({ args: [{ key: "categoryIndex", kind: "number", default: 0, min: 0, step: 1 }] })
-  spotlightCategory(args: CommandArgs<{ categoryIndex: number }>): Command<CategorySpotlight> {
-    const { categoryIndex = 0 } = args.data ?? {}
-    const duration = args.duration ?? 0.4
-    const easing = args.easing ?? easeOut()
-    if (categoryIndex < 0 || categoryIndex >= this.data.length) return this.holdSpotlight(duration)
-    const from = this.spotlightReveal
-    // Which category is lit is part of the value, set from the first frame: the
-    // focus moves directly, so unlike the line chart's region there is nothing to
-    // retract before it.
-    return this.command<CategorySpotlight>(
-      (t) => ({ spotlight: categoryIndex, spotlightReveal: from + (1 - from) * t }),
-      duration,
-      easing
-    )
-  }
-
-  /**
-   * Drop the category spotlight, bringing every category back to full. A no-op
-   * when nothing is lit — but it still takes its slot on the timeline, for the
-   * reason `LineChart.clearRegion` does.
-   */
-  @command()
-  clearCategory(args: CommandArgs<Record<string, never>>): Command<CategorySpotlight> {
-    const duration = args.duration ?? 0.4
-    const easing = args.easing ?? easeOut()
-    const from = this.spotlightReveal
-    if (from === 0) return this.holdSpotlight(duration)
-
-    // The lit category is held until the fade lands — cleared at `t === 1` rather
-    // than up front, or there would be nothing left to fade.
-    return this.command<CategorySpotlight>(
-      (t) =>
-        t >= 1
-          ? { spotlight: null, spotlightReveal: 0 }
-          : { spotlightReveal: from * (1 - t) },
-      duration,
-      easing
-    )
-  }
-
-  /** The no-op both of the above return — see {@link hold}. */
-  private holdSpotlight(duration: number): Command<CategorySpotlight> {
-    return this.command<CategorySpotlight>(() => ({}), duration)
-  }
-}
+import {
+  command,
+  node,
+  Node2D,
+  Rect,
+  easeOut,
+  property,
+  type CommandArgs,
+  type DataRecord,
+  type Command,
+  type EasingFunction,
+  type NodeConfig,
+  type Node2DProps,
+} from "@motionscript/sdk"
+
+import { ChartBorder } from "../kit/chart-border"
+import { ChartCanvas } from "../kit/chart-canvas"
+import { ChartLegend } from "../kit/chart-legend"
+import { VerticalAxis } from "../kit/vertical-axis"
+import {
+  clampUnit,
+  formatMarker,
+  markerStep,
+  axisTweenTarget,
+  lerpAxisDomain,
+  markerValues,
+  num,
+  resolveAxisDomain,
+  type AxisDomainConfig,
+  type Range,
+} from "../kit/shared"
+import { formatNumber } from "@motionscript/sdk/component"
+import {
+  asCommand,
+  drive,
+  hold,
+  sequence as sequenceOf,
+  together,
+  type Seekable,
+} from "@motionscript/sdk/component"
+import { CategoryAxis } from "./category-axis"
+import { ChartBars, type BarGeometry } from "./chart-bars"
+import {
+  DEFAULT_BAR_CHART_THEME,
+  barCategories,
+  barSpans,
+  lerpBarChartTheme,
+  resolveBarChartTheme,
+  resolveBarFill,
+  resolveBarScale,
+  stackCapIndex,
+  type BarChartConfig,
+  type BarChartTheme,
+  type BarSeries,
+} from "./shared"
+
+export interface BarChartProps extends Node2DProps {
+  /** One row per category — a plain record of field name to value. */
+  data: DataRecord[]
+  /**
+   * Key into each row for its category caption, drawn beneath the baseline.
+   * Named `categoryField` rather than `category` for the same reason the line
+   * chart's is `xField`: it names a *column*, not a value.
+   */
+  categoryField: string
+  /** One entry per bar series: which column it plots, its `label`, its `fill`. */
+  series: BarSeries[]
+  /**
+   * When `true` every category's series stack into one column; when `false`
+   * (the default) each series gets its own bar, grouped side by side within the
+   * category's slot.
+   */
+  stacked?: boolean
+  /** The value axis's domain: caption, scale range, and tick placement. */
+  valueAxis?: AxisDomainConfig
+  /** The category axis's domain. Only its `label` is read — the slots are the rows. */
+  categoryAxis?: AxisDomainConfig
+  /**
+   * The chart's visual theme — bar palette and geometry, axis furniture, plot
+   * panel paint, legend, value figures. Every branch is optional and deep-merged
+   * onto {@link DEFAULT_BAR_CHART_THEME}.
+   */
+  theme?: BarChartTheme
+  /** Whether the legend row below the plot is drawn at all. */
+  showLegend?: boolean
+  /** Whether each column prints the figure it plots. */
+  showValues?: boolean
+}
+
+/**
+ * Headroom above the plot, in px — the line chart's, so the two sit at the same
+ * size in the same box and a scene can swap one for the other without re-tuning
+ * its layout. The plot's top grid line is the one place a marker would
+ * otherwise be drawn outside the chart's own box.
+ */
+const TOP_HEADROOM = 24
+
+/** How far the legend starts below its slot when it enters, in px. */
+const LEGEND_SLIDE = 20
+
+/**
+ * How {@link BarChart.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 — the entrance takes exactly the time it was
+ * given, for the reason spelt out on `LineChart.enter`.
+ */
+/**
+ * The signals the bar chart's own commands move, as props types.
+ *
+ * Written out rather than reusing `BarChartProps` because these are signals of
+ * the chart's own — how far the columns have risen, and which category is lit —
+ * rather than part of what an author states about it. Same reason the line chart
+ * types its `RegionState` separately.
+ */
+type CategorySpotlight = { spotlight: number | null; spotlightReveal: number }
+type BarGrowth = { growth: number }
+
+const AXES_SHARE = 0.35
+const BARS_SHARE = 0.5
+const LEGEND_SHARE = 0.15
+
+/**
+ * A grouped or stacked bar chart, composed from independent parts rather than
+ * one monolithic draw — the sibling of the {@link LineChart} family, built the
+ * same way and 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 of
+ *   the data, staggering in left-to-right.
+ * - {@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.
+ *
+ * The parts are laid out from this node's `layoutBounds` exactly as the line
+ * chart's are: the value axis on the left, the category captions below, the
+ * plot filling what's left, and the legend row beneath the whole thing. The
+ * columns are mapped across the plot panel's own laid-out box and read the same
+ * resolved scale the axis does, so a column's end lands exactly on its marker
+ * and the chart re-flows if its box changes.
+ *
+ * **Resting state is the finished chart** — the same bargain the line chart
+ * makes: an editor paints a node's Initial state on a paused canvas, so a chart
+ * that only appeared once a command had run would be edited blind. {@link enter}
+ * arms every part back to its pre-entrance state before animating.
+ *
+ * **Zero is always on the scale** (see `barValueExtent`), and the columns
+ * grow about it rather than about the plot floor, so a negative value draws
+ * downward out of the same `growth` signal that draws a positive one up.
+ *
+ * Past the entrance, two things move the chart:
+ * {@link showSeries}/{@link hideSeries}/{@link spotlightSeries} pick out a
+ * *series* — and hiding one **reflows the group**, the remaining columns
+ * widening into the space as it goes, rather than leaving a hole where it was —
+ * while {@link spotlightCategory}/{@link clearCategory} pick out a *column of
+ * the table*, dimming every other category and its caption with it.
+ */
+@node({
+  key: "barChart",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+    acceptsChildren: true,
+  },
+  seed: {
+    width: 760,
+    height: 460,
+  },
+})
+export class BarChart extends Node2D<BarChartProps> {
+  @property({ default: () => [] as DataRecord[] }) declare data: DataRecord[]
+  @property({ default: "" }) declare categoryField: string
+  @property({ default: () => [] as BarSeries[] }) declare series: BarSeries[]
+  @property({ default: false }) declare stacked: boolean
+  /**
+   * The value axis's domain (label/range/ticks), tweenable and mappable exactly
+   * as the line chart's axes are: the mapper merges a partial input onto the
+   * previous resolved domain and the tween interpolates numerically, so
+   * `chart.to({ data: { valueAxis: { range: [0, 10] } }, duration: 1 })` smoothly
+   * rescales every column. The axis *label* text is captured once at construction.
+   */
+  @property({
+    default: {},
+    mapper: resolveAxisDomain,
+    tween: lerpAxisDomain,
+  })
+  declare valueAxis: AxisDomainConfig
+  @property({
+    default: {},
+    mapper: resolveAxisDomain,
+    tween: lerpAxisDomain,
+  })
+  declare categoryAxis: AxisDomainConfig
+  @property({
+    default: DEFAULT_BAR_CHART_THEME,
+    mapper: resolveBarChartTheme,
+    tween: lerpBarChartTheme,
+  })
+  declare theme: BarChartTheme
+
+  /**
+   * Global rise of every column in `[0, 1]`, measured about the baseline: 0
+   * collapses them all onto it, 1 draws them at full length. Each
+   * {@link ChartBars}' own `growth` is bound to this, so tweening this one
+   * signal raises the whole chart in proportion.
+   */
+  @property({ default: 1 }) declare growth: number
+
+  /**
+   * How much of the slot each series currently claims, one entry per series.
+   *
+   * A *weight* rather than a boolean, because that is what makes hiding a series
+   * an animation instead of a jump: the grouped columns divide the slot in
+   * proportion to these, so tweening one to 0 has the remaining columns widen
+   * into the space as it shrinks away, and a stacked segment's contribution to
+   * the stack fades out with it. Seeded from each series' `enabled` field.
+   */
+  @property({ default: () => [] as number[] }) declare weights: number[]
+
+  /**
+   * The category currently spotlit, or `null` for none. Held as a plain reactive
+   * value rather than a tweened one: the *choice* snaps, and the animation is
+   * {@link spotlightReveal} dimming everything else.
+   */
+  @property({ default: null }) declare spotlight: number | null
+
+  /** How far the category spotlight is drawn in, `[0, 1]`. */
+  @property({ default: 0 }) declare spotlightReveal: number
+
+  // ---- Part handles (built in the constructor) --------------------------
+  private vAxis: VerticalAxis
+  private cAxis: CategoryAxis
+  private legend: ChartLegend | null = null
+  private barSets: ChartBars[] = []
+  /** The plot panel: the box the grid, the columns and the border all share. */
+  private plotRect: Rect
+
+  /**
+   * `this.theme` read back through its *resolved* shape — the same
+   * loose-declared/resolved-stored idiom as a shape's `fill`/`stroke`, and as
+   * the line chart's own theme.
+   */
+  private get resolvedTheme(): BarChartConfig {
+    return this.theme as unknown as BarChartConfig
+  }
+
+  // ---- Derived scale ----------------------------------------------------
+
+  /** Fallback marker count when the value axis states no ticks. */
+  private static readonly DEFAULT_MARKERS = 5
+
+  private get valueScale(): Range {
+    const divisions =
+      (this.valueAxis.ticks?.length ?? BarChart.DEFAULT_MARKERS) - 1
+    return resolveBarScale(
+      this.data,
+      this.series,
+      this.stacked,
+      this.valueAxis.range,
+      divisions
+    )
+  }
+
+  /**
+   * A value written down as this chart's value axis says — the axis ticks and
+   * the figures printed on the columns both read through here, so the two
+   * cannot disagree about what a number looks like.
+   */
+  private valueLabel(value: number): string {
+    const pattern = this.valueAxis.format
+    return pattern === undefined
+      ? formatMarker(value, markerStep(this.resolvedMarkers))
+      : formatNumber(value, pattern)
+  }
+
+  /** The value axis ticks: the explicit ones, else five across the scale. */
+  private get resolvedMarkers(): number[] {
+    return (
+      this.valueAxis.ticks ??
+      markerValues(this.valueScale, BarChart.DEFAULT_MARKERS - 1)
+    )
+  }
+
+  // ---- Plot geometry ------------------------------------------------------
+
+  /**
+   * The plot panel's size, **as laid out**.
+   *
+   * The value axis is `width: "hug"` and the category row and legend are as tall
+   * as their text, so the panel's real box is whatever the layout makes it. An
+   * estimate built from gutter constants never matched it, and the columns sat a
+   * few percent off the grid line they were supposed to end on. Asking the panel
+   * is exact by construction: the grid, the columns and the border all resolve
+   * against the one box they are drawn in. Zero until the first layout pass, like
+   * any other `layoutBounds` read; the bindings that call this re-run on the
+   * next frame.
+   */
+  private plotSize(): { w: number; h: number } {
+    const { width, height } = this.plotRect.layoutBounds
+    return { w: width, h: height }
+  }
+
+  /** Map a value onto the plot's **centred** pixel space (origin at its centre, y-up). */
+  private valueToY(value: number): number {
+    const [min, max] = this.valueScale
+    const { h } = this.plotSize()
+    if (max <= min) return -h / 2
+    return ((value - min) / (max - min) - 0.5) * h
+  }
+
+  /**
+   * Pixel y of the line every column grows from.
+   *
+   * Zero, clamped onto the scale — so an author who *did* crop the axis to
+   * `[40, 100]` gets columns rising from the plot floor rather than from a
+   * baseline off the bottom of the panel.
+   */
+  private get baselinePx(): number {
+    const [min, max] = this.valueScale
+    return this.valueToY(Math.min(Math.max(0, min), max))
+  }
+
+  // ---- Slot geometry ----------------------------------------------------
+
+  /** Width of one category's slot across the plot. */
+  private get slotWidth(): number {
+    const n = this.data.length
+    return n > 0 ? this.plotSize().w / n : 0
+  }
+
+  /** Centre x of category `i`'s slot, in the plot's centred space. */
+  private slotCenter(index: number): number {
+    return -this.plotSize().w / 2 + this.slotWidth * (index + 0.5)
+  }
+
+  /** The part of a slot the columns fill — the rest is the channel between categories. */
+  private get slotInner(): number {
+    return this.slotWidth * clampUnit(this.resolvedTheme.bar.slotFill)
+  }
+
+  /** Series `i`'s live share of the slot; 0 once it has been hidden. */
+  private weightAt(index: number): number {
+    return Math.max(0, this.weights[index] ?? 1)
+  }
+
+  /** Total live share across the series — the slot's inner width divides by this. */
+  private get totalWeight(): number {
+    let sum = 0
+    for (let i = 0; i < this.series.length; i++) sum += this.weightAt(i)
+    return sum > 0 ? sum : 1
+  }
+
+  /** Live share of every series *before* `index`, for the grouped offset. */
+  private weightBefore(index: number): number {
+    let sum = 0
+    for (let i = 0; i < index; i++) sum += this.weightAt(i)
+    return sum
+  }
+
+  /**
+   * Series `index`'s columns, mapped into the plot's centred pixel space.
+   *
+   * Both modes come out of one walk over the rows: a grouped series divides the
+   * slot with its siblings and every column runs from zero, a stacked one takes
+   * the whole slot and each column runs from the running total below it. The
+   * live {@link weights} scale the grouped widths and the stacked contributions
+   * alike, which is what lets `hideSeries` reflow rather than punch a hole.
+   */
+  private seriesBars(index: number): BarGeometry[] {
+    const series = this.series[index]
+    if (!series) return []
+    const stacked = this.stacked
+    const inner = this.slotInner
+    const gap = this.resolvedTheme.bar.groupGap
+    const unit = inner / this.totalWeight
+    const weight = this.weightAt(index)
+
+    return this.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 instead of dropping them by a
+      // step when it finally switches off. A grouped row needs no such scaling —
+      // there its weight moves the column's width, not its length.
+      const spans = barSpans(
+        stacked ? this.weightedRow(row) : row,
+        this.series,
+        stacked
+      )
+      const span = spans[index] ?? { from: 0, to: 0, value: 0 }
+      const cap = stacked ? stackCapIndex(row, this.series) : index
+
+      const slotLeft = this.slotCenter(rowIndex) - inner / 2
+      const x = stacked
+        ? this.slotCenter(rowIndex)
+        : slotLeft + unit * this.weightBefore(index) + (unit * weight) / 2
+      const width = stacked
+        ? inner
+        : Math.max(0, unit * weight - (this.series.length > 1 ? gap : 0))
+
+      return {
+        x,
+        width,
+        from: this.valueToY(span.from),
+        to: this.valueToY(span.to),
+        round: cap === index,
+        // The figure printed is the row's own value, not the weighted one — a
+        // series on its way out should not be seen counting down.
+        value: num(row, series.field),
+      }
+    })
+  }
+
+  /**
+   * `row` with each series' value scaled by that series' live {@link weights}
+   * entry — what the stacked spans are measured from.
+   */
+  private weightedRow(row: DataRecord): DataRecord {
+    const scaled: DataRecord = { ...row }
+    this.series.forEach((s, i) => {
+      const value = row[s.field]
+      if (typeof value === "number") scaled[s.field] = value * this.weightAt(i)
+    })
+    return scaled
+  }
+
+  /**
+   * 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.
+   */
+  private categoryDims(): number[] {
+    const focus = clampUnit(this.spotlightReveal)
+    const dim = this.resolvedTheme.spotlight.dimOpacity
+    const chosen = this.spotlight
+    return this.data.map((_, i) =>
+      focus <= 0 || chosen === i ? 1 : 1 - (1 - dim) * focus
+    )
+  }
+
+  // ---- Build ------------------------------------------------------------
+
+  constructor(props?: NodeConfig<BarChart, BarChartProps>) {
+    super(props)
+
+    // The whole chart is composed from plain props/`data` — no context needed,
+    // so the parts are built here (super() applied the props above). Everything
+    // a *leaf* reads live in `renderSelf` — each series' geometry, paint and
+    // dim, the panel's fill, the border's stroke — is passed as a closure rather
+    // than a snapshot, so `chart.to({ theme })` and
+    // `chart.to({ valueAxis: { range } })` genuinely animate the drawn chart.
+    const enabled = this.series.map((s) => s.enabled ?? true)
+    this.weights = enabled.map((on) => (on ? 1 : 0))
+    const showLegend = props?.showLegend !== false
+    const showValues = props?.showValues === true
+
+    this.vAxis = new VerticalAxis({
+      range: () => this.valueScale,
+      markers: () => this.resolvedMarkers,
+      axis: () => this.resolvedTheme.yAxis,
+      label: this.valueAxis.label ?? "",
+      width: "hug",
+      height: "fill",
+    })
+    this.vAxis.labelFor = (value) => this.valueLabel(value)
+
+    this.cAxis = new CategoryAxis({
+      categories: barCategories(this.data, this.categoryField),
+      axis: () => this.resolvedTheme.xAxis,
+      label: this.categoryAxis.label ?? "",
+      dims: () => this.categoryDims(),
+      width: "fill",
+      height: "hug",
+    })
+
+    this.barSets = this.series.map(
+      (s, i) =>
+        new ChartBars({
+          bars: () => this.seriesBars(i),
+          baseline: () => this.baselinePx,
+          fill: () => resolveBarFill(this.resolvedTheme.seriesFills, s, i),
+          barStroke: () => this.resolvedTheme.bar.stroke,
+          barShadow: () => this.resolvedTheme.bar.shadow,
+          cornerRadius: () => this.resolvedTheme.bar.cornerRadius,
+          growth: () => this.growth,
+          dims: () => this.categoryDims(),
+          showValues,
+          valueStyle: this.resolvedTheme.valueStyle,
+          enabled: enabled[i],
+        })
+    )
+    // The figures on the columns are the same numbers the value axis ticks, so
+    // they read through the same format.
+    for (const set of this.barSets) set.labelFor = (value) => this.valueLabel(value)
+
+    if (showLegend) {
+      this.legend = new ChartLegend({
+        series: this.series,
+        swatches: () =>
+          this.series.map((s, i) =>
+            resolveBarFill(this.resolvedTheme.seriesFills, s, i)
+          ),
+        legend: () => this.resolvedTheme.legend,
+      })
+    }
+
+    this.plotRect = new Rect({
+      clip: true,
+      children: [
+        new ChartCanvas({
+          fill: () => this.resolvedTheme.plotArea.fill,
+          shadow: () => this.resolvedTheme.plotArea.shadow,
+          xGridStroke: () => this.resolvedTheme.xAxis.lineStyle,
+          yGridStroke: () => this.resolvedTheme.yAxis.lineStyle,
+          // No vertical rules: the horizontal axis is categorical, so there is
+          // no numeric position along it for a grid line to mark. The channel
+          // between slots does that job, and better.
+          xMarkers: [],
+          yMarkers: () => this.resolvedMarkers,
+          xExtent: () => [0, 1] as Range,
+          yExtent: () => this.valueScale,
+        }),
+        ...this.barSets,
+        new ChartBorder({
+          stroke: () => this.resolvedTheme.plotArea.stroke,
+        }),
+      ],
+    })
+
+    // Invisible twin of the value axis, reserving the same left gutter under the
+    // plot so the category row starts at the plot's left edge rather than the
+    // chart's — and so a caption lands under the columns it names.
+    const gutterSpacer = new VerticalAxis({
+      opacity: 0,
+      range: () => this.valueScale,
+      markers: () => this.resolvedMarkers,
+      axis: () => this.resolvedTheme.yAxis,
+      label: this.valueAxis.label ?? "",
+      width: "hug",
+      height: 0,
+    })
+
+    const below: Node2D[] = [this.cAxis]
+    if (this.legend) below.push(this.legend)
+
+    this.add(
+      new Rect({ flow: "vertical",
+        width: "fill",
+        height: "fill",
+        // See {@link TOP_HEADROOM}.
+        padding: { top: TOP_HEADROOM },
+        children: [
+          new Rect({ flow: "horizontal",
+            height: "fill",
+            width: "fill",
+            children: [this.vAxis, this.plotRect],
+          }),
+          new Rect({ flow: "horizontal",
+            width: "fill",
+            children: [
+              gutterSpacer,
+              new Rect({ flow: "vertical", width: "fill", gap: 20, children: below }),
+            ],
+          }),
+        ],
+      })
+    )
+  }
+
+  // ---- Orchestrated entrance --------------------------------------------
+
+  /**
+   * Prime every part at its pre-entrance state — axis markers and captions
+   * shifted and transparent, columns collapsed onto the baseline, legend dropped
+   * and transparent.
+   *
+   * Called by {@link enter} before its first frame so nothing flashes ahead of
+   * its beat. Idempotent, and public so a scene can hide a chart ahead of time
+   * without starting the entrance.
+   */
+  arm(): void {
+    this.vAxis.arm()
+    this.cAxis.arm()
+    this.growth = 0
+    this.legend?.set({ opacity: 0, y: -LEGEND_SLIDE })
+  }
+
+  /**
+   * 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.
+   *
+   * `duration` is the **whole** entrance. The phases are shares of it, not
+   * multiples — a command that declares 1.4 seconds has to take 1.4 seconds,
+   * because that is the slot the timeline lays out for it, the length its
+   * parallel siblings are timed against, and its contribution to the scene's own
+   * duration.
+   */
+  @command()
+  enter(args: CommandArgs<Record<string, never>> & { duration: number }): Command<Record<string, never>> {
+    const { duration } = args
+    const easing = args.easing ?? easeOut()
+    this.arm()
+
+    return asCommand(
+      sequenceOf(
+        together(
+          this.vAxis.enter({ data: { slide: 24 }, duration: duration * AXES_SHARE, easing }),
+          this.cAxis.enter({ data: { slide: 24 }, duration: duration * AXES_SHARE, easing })
+        ),
+        this.riseBars(duration * BARS_SHARE, easing),
+        // Without a legend the beat is still its share of the whole, so the
+        // entrance ends exactly when it was laid out to.
+        this.legend
+          ? this.legend.to({ data: { opacity: 1, y: 0 }, duration: duration * LEGEND_SHARE, easing })
+          : hold(duration * LEGEND_SHARE)
+      ),
+      duration
+    )
+  }
+
+  /**
+   * Move props to new values; a restated value-axis `range` or `ticks` tweens
+   * from the domain as drawn, so an auto axis (the default) rescales the columns
+   * continuously instead of cutting at the midpoint of the move.
+   */
+  override to<D extends Partial<BarChartProps> = Partial<BarChartProps>>(
+    args: CommandArgs<D> & { duration: number }
+  ): Command<BarChartProps> {
+    const data = (args.data ?? {}) as Partial<BarChartProps>
+    const drawn: AxisDomainConfig = {
+      ...this.valueAxis,
+      range: this.valueScale,
+      ticks: this.resolvedMarkers,
+    }
+    const target = axisTweenTarget(drawn, data.valueAxis)
+    if (!target) return super.to(args)
+
+    const { valueAxis: _valueAxis, ...rest } = data
+    const axis = this.command<{ valueAxis: AxisDomainConfig }>(
+      (t) => ({ valueAxis: lerpAxisDomain(drawn, target, t) }),
+      args.duration,
+      args.easing
+    )
+    if (Object.keys(rest).length === 0) return axis as unknown as Command<BarChartProps>
+    return asCommand(
+      together(super.to({ ...args, data: rest } as typeof args), axis),
+      args.duration
+    ) as unknown as Command<BarChartProps>
+  }
+
+  /** Tween {@link growth} `0 → 1`, raising every column about the baseline. */
+  private riseBars(
+    duration: number,
+    easing: EasingFunction
+  ): Command<BarGrowth> {
+    // No priming to 0 first: the value at `t` is a function of `t`, so a repeat
+    // call re-raises by definition rather than by having reset something.
+    return this.command<BarGrowth>((t) => ({ growth: t }), duration, easing)
+  }
+
+  /**
+   * Show series `index`: bring its columns back, the group reflowing to make
+   * room as they arrive, in lockstep with its legend entry growing in.
+   */
+  @command({ args: [{ key: "seriesIndex", kind: "series", default: 0, min: 0, step: 1 }] })
+  showSeries(args: CommandArgs<{ seriesIndex: number }>): Command<Record<string, never>> {
+    const { seriesIndex = 0 } = args.data ?? {}
+    return this.toggleSeries(seriesIndex, 1, args.duration ?? 0.35, args.easing ?? easeOut())
+  }
+
+  /**
+   * Hide series `index`: its columns narrow away (or, stacked, sink out of the
+   * stack) while the rest of the group widens into the space, its legend entry
+   * shrinking beside them — the mirror of {@link showSeries}.
+   */
+  @command({ args: [{ key: "seriesIndex", kind: "series", default: 0, min: 0, step: 1 }] })
+  hideSeries(args: CommandArgs<{ seriesIndex: number }>): Command<Record<string, never>> {
+    const { seriesIndex = 0 } = args.data ?? {}
+    return this.toggleSeries(seriesIndex, 0, args.duration ?? 0.35, args.easing ?? easeOut())
+  }
+
+  /**
+   * Move series `index`'s slot share to `target`, with its legend entry.
+   *
+   * One method for both directions, so the pair cannot drift apart. `enabled`
+   * rides in the same value as the weight rather than being set before or after,
+   * which is what makes arriving at a time backwards show what arriving forwards
+   * does.
+   */
+  private toggleSeries(
+    index: number,
+    target: number,
+    duration: number,
+    easing: EasingFunction
+  ): Command<Record<string, never>> {
+    const bars = this.barSets[index]
+    if (!bars) return asCommand(hold(duration))
+
+    return asCommand(
+      together(
+        this.tweenWeight(index, target, duration, easing),
+        drive(duration, (t) => {
+          const share = t >= 1 ? target : Math.max(target, 1 - t)
+          bars.set({ enabled: target > 0 || share > 0 })
+        }),
+        ...(this.legend
+          ? [
+            target > 0
+              ? this.legend.showSeries({ data: { index }, duration, easing })
+              : this.legend.hideSeries({ data: { index }, duration, easing }),
+          ]
+          : [])
+      ),
+      duration
+    )
+  }
+
+  /**
+   * Fade out every other series — its columns **and its legend entry** — to
+   * focus attention on `index`, which comes back to full. Nothing moves, so the
+   * group doesn't reflow.
+   */
+  @command({ args: [{ key: "seriesIndex", kind: "series", default: 0, min: 0, step: 1 }] })
+  spotlightSeries(args: CommandArgs<{ seriesIndex: number }>): Command<Record<string, never>> {
+    const { seriesIndex = 0 } = args.data ?? {}
+    const duration = args.duration ?? 0.35
+    const easing = args.easing ?? easeOut()
+    const dim = this.resolvedTheme.spotlight.dimOpacity
+    return asCommand(
+      together(
+        ...this.barSets.map((bars, i) =>
+          bars.to({ data: { opacity: i === seriesIndex ? 1 : dim }, duration, easing })
+        ),
+        ...(this.legend
+          ? [this.legend.spotlightSeries({ data: { index: seriesIndex }, duration, easing })]
+          : [])
+      ),
+      duration
+    )
+  }
+
+  /** Ease series `index`'s slot share toward `target`, reflowing the group. */
+  private tweenWeight(
+    index: number,
+    target: number,
+    duration: number,
+    easing: EasingFunction
+  ): Seekable {
+    // Read through `weightAt` rather than off the array, so a chart whose stored
+    // weights are short (or absent) still tweens from the 1 it is drawing at.
+    const from = this.series.map((_, i) => this.weightAt(i))
+    const start = from[index] ?? 1
+    if (start === target) return hold(duration)
+
+    return drive(duration, (t) => {
+      const next = [...from]
+      next[index] = start + (target - start) * easing(t)
+      this.weights = next
+    })
+  }
+
+  // ---- Per-category ------------------------------------------------------
+
+  /**
+   * Spotlight one **category** — one column of the table rather than one series:
+   * every other category's bars and its caption fade to the theme's
+   * `dimOpacity`, and the chosen one stays full.
+   *
+   * The counterpart of the line chart's `spotlightRegion`, and the same shape of
+   * thing: it picks out a slice of the plot without changing what is drawn.
+   * Calling it while another category is already lit moves the focus directly —
+   * only the dimming changes, so there is nothing to retract first.
+   */
+  @command({ args: [{ key: "categoryIndex", kind: "number", default: 0, min: 0, step: 1 }] })
+  spotlightCategory(args: CommandArgs<{ categoryIndex: number }>): Command<CategorySpotlight> {
+    const { categoryIndex = 0 } = args.data ?? {}
+    const duration = args.duration ?? 0.4
+    const easing = args.easing ?? easeOut()
+    if (categoryIndex < 0 || categoryIndex >= this.data.length) return this.holdSpotlight(duration)
+    const from = this.spotlightReveal
+    // Which category is lit is part of the value, set from the first frame: the
+    // focus moves directly, so unlike the line chart's region there is nothing to
+    // retract before it.
+    return this.command<CategorySpotlight>(
+      (t) => ({ spotlight: categoryIndex, spotlightReveal: from + (1 - from) * t }),
+      duration,
+      easing
+    )
+  }
+
+  /**
+   * Drop the category spotlight, bringing every category back to full. A no-op
+   * when nothing is lit — but it still takes its slot on the timeline, for the
+   * reason `LineChart.clearRegion` does.
+   */
+  @command()
+  clearCategory(args: CommandArgs<Record<string, never>>): Command<CategorySpotlight> {
+    const duration = args.duration ?? 0.4
+    const easing = args.easing ?? easeOut()
+    const from = this.spotlightReveal
+    if (from === 0) return this.holdSpotlight(duration)
+
+    // The lit category is held until the fade lands — cleared at `t === 1` rather
+    // than up front, or there would be nothing left to fade.
+    return this.command<CategorySpotlight>(
+      (t) =>
+        t >= 1
+          ? { spotlight: null, spotlightReveal: 0 }
+          : { spotlightReveal: from * (1 - t) },
+      duration,
+      easing
+    )
+  }
+
+  /** The no-op both of the above return — see {@link hold}. */
+  private holdSpotlight(duration: number): Command<CategorySpotlight> {
+    return this.command<CategorySpotlight>(() => ({}), duration)
+  }
+}