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

package/src/pie-chart/pie-chart.ts

@@ -1,381 +1,383 @@
-import {
-  Rect,
-  command,
-  node,
-  Node2D,
-  easeOut,
-  property,
-  type Command,
-  type CommandArgs,
-  type DataRecord,
-  type EasingFunction,
-  type NodeConfig,
-  type Node2DProps,
-} from "@motionscript/sdk"
-
-import { clampUnit } from "../kit/shared"
-import { PieLegend } from "./pie-legend"
-import { PieRing } from "./pie-ring"
-import {
-  DEFAULT_PIE_CHART_THEME,
-  lerpPieChartTheme,
-  resolvePieChartTheme,
-  resolvePieSlices,
-  type PieChartConfig,
-  type PieChartTheme,
-  type PieLabelMode,
-  type PieLabelPlacement,
-  type PieSlice,
-} from "./shared"
-import {
-  asCommand,
-  hold,
-  sequence as sequenceOf,
-  together,
-} from "@motionscript/sdk/component"
-
-export interface PieChartProps extends Node2DProps {
-  /** One row per slice — a plain record of field name to value. */
-  data: DataRecord[]
-  /** Key into each row for its slice caption, used on the labels and the legend. */
-  categoryField: string
-  /** Key into each row for its slice magnitude — the wedge's share of the ring. */
-  valueField: string
-  /**
-   * The chart's visual theme — slice palette, ring geometry, label and centre
-   * type, legend. Every branch is optional and deep-merged onto
-   * {@link DEFAULT_PIE_CHART_THEME}.
-   */
-  theme?: PieChartTheme
-  /** What the ring's labels say. */
-  labelMode?: PieLabelMode
-  /** Where they sit: inside their wedge, outside on a leader, or nowhere. */
-  labelPlacement?: PieLabelPlacement
-  /** Whether the legend column beside the ring is drawn at all. */
-  showLegend?: boolean
-  /** Gap between the ring and the legend, in px. */
-  gap?: number
-  /** Text set in the ring's hole — see {@link revealCenter}. */
-  centerLabel?: string
-  /** Smaller second line under {@link centerLabel}. */
-  centerCaption?: string
-  /**
-   * Whether the hole's summary is drawn at rest. `true` (the default) is the
-   * plain answer; a scene that wants the conclusion to land on a later beat sets
-   * this `false` and calls {@link revealCenter} when it gets there.
-   */
-  showCenter?: boolean
-}
-
-/**
- * How {@link PieChart.enter} divides its duration: the wedges sweeping in, then
- * the labels and the legend arriving together. Shares of the whole, so they sum
- * to 1 — the entrance takes exactly the time it was given, for the reason spelt
- * out on `LineChart.enter`.
- */
-const SWEEP_SHARE = 0.65
-const LABEL_SHARE = 0.35
-
-/** What the selection commands move: the chart's own {@link PieChart.pops}. */
-type SlicePops = { pops: number[] }
-
-/**
- * A pie or donut chart, composed from two independent parts rather than one
- * monolithic draw — the third of the chart family, built the same way as the
- * line and bar charts beside it:
- *
- * - {@link PieRing} — the wedges, each sized by its share of the total, with its
- *   label set inside its own band or pinned outside on a leader line, and the
- *   summary in the hole. The only part of the family that draws a path.
- * - {@link PieLegend} — a column of swatch-and-caption rows naming each slice.
- *
- * The two are laid out by a plain horizontal-flow {@link Rect}: the ring fills whatever the
- * hugging legend leaves, both centred, so the chart re-flows if its box changes.
- *
- * **One mark per row, not per column** — which is what makes this the odd one of
- * the three. A line or a bar chart plots *series*, so its colours belong to
- * columns and hiding one is a sensible thing to ask for. A pie plots rows, so its
- * palette is indexed by row and there is nothing to hide: dropping a slice would
- * silently re-cut every other wedge's share, which is a different chart rather
- * than the same chart with a series switched off. {@link selectSlice} and its
- * siblings are what a pie has instead — a slice swells out of the ring, its hole
- * edge staying put, and everything else dims behind it.
- *
- * **Resting state is the finished chart** — the same bargain the other two make:
- * 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. The one exception
- * is the hole's summary, which a scene can hold back with `showCenter: false`
- * because it is usually the chart's *conclusion* rather than part of its setup.
- */
-@node({
-  key: "pieChart",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    defaultWidthMode: "fixed",
-    defaultHeightMode: "fixed",
-    acceptsChildren: true,
-  },
-  seed: {
-    width: 680,
-    height: 480,
-  },
-})
-export class PieChart extends Node2D<PieChartProps> {
-  @property({ default: () => [] as DataRecord[] }) declare data: DataRecord[]
-  @property({ default: "" }) declare categoryField: string
-  @property({ default: "" }) declare valueField: string
-  @property({
-    default: DEFAULT_PIE_CHART_THEME,
-    mapper: resolvePieChartTheme,
-    tween: lerpPieChartTheme,
-  })
-  declare theme: PieChartTheme
-  @property({ default: "percent" }) declare labelMode: PieLabelMode
-  @property({ default: "leader" }) declare labelPlacement: PieLabelPlacement
-  @property({ default: 40 }) declare gap: number
-  @property({ default: "" }) declare centerLabel: string
-  @property({ default: "" }) declare centerCaption: string
-
-  /**
-   * How far each slice is currently pushed out of the ring, `0`–`1` per index.
-   *
-   * Held here rather than on the ring because two parts read it: the wedges grow
-   * out by it, and the legend entries dim by it. One signal, one tween, and the
-   * two can't drift.
-   */
-  @property({ default: () => [] as number[] }) declare pops: number[]
-
-  // ---- Part handles (built in the constructor) --------------------------
-  private ring: PieRing
-  private legend: PieLegend | null = null
-
-  /** `this.theme` read back through its *resolved* shape — see `LineChart.theme`. */
-  private get resolvedTheme(): PieChartConfig {
-    return this.theme as unknown as PieChartConfig
-  }
-
-  /** The slices the ring and the legend draw, resolved from the rows and the palette. */
-  private get slices(): PieSlice[] {
-    return resolvePieSlices(
-      this.data,
-      this.categoryField,
-      this.valueField,
-      this.resolvedTheme.sliceFills
-    )
-  }
-
-  /**
-   * How far each slice is dimmed by the current selection, one entry per slice —
-   * 1 while nothing is selected, and for the selected slice itself; falling
-   * toward the theme's `dimOpacity` for the rest in proportion to how far the
-   * selection has grown.
-   */
-  private sliceDims(): number[] {
-    let focus = 0
-    for (let i = 0; i < this.data.length; i++) {
-      focus = Math.max(focus, this.popAt(i))
-    }
-    const dim = this.resolvedTheme.spotlight.dimOpacity
-    if (focus <= 0) return this.data.map(() => 1)
-    return this.data.map(
-      (_, i) => 1 - (1 - clampUnit(dim)) * focus * (1 - this.popAt(i))
-    )
-  }
-
-  /** How far slice `index` is currently pushed out, in `[0, 1]`. */
-  private popAt(index: number): number {
-    return clampUnit(this.pops[index] ?? 0)
-  }
-
-  constructor(props?: NodeConfig<PieChart, PieChartProps>) {
-    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). The slice
-    // *structure* (one wedge and one legend row each) is read once, like every
-    // other chart's series list; everything the parts draw with is passed as a
-    // closure, so `chart.to({ theme })` genuinely re-paints the ring.
-    const slices = this.slices
-    const showLegend = props?.showLegend !== false
-    this.pops = slices.map(() => 0)
-
-    this.ring = new PieRing({
-      width: "fill",
-      height: "fill",
-      slices,
-      ring: () => this.resolvedTheme.ring,
-      label: () => this.resolvedTheme.label,
-      centerStyle: () => this.resolvedTheme.center,
-      labelMode: this.labelMode,
-      labelPlacement: this.labelPlacement,
-      pops: () => this.pops,
-      dimOpacity: () => this.resolvedTheme.spotlight.dimOpacity,
-      centerLabel: this.centerLabel,
-      centerCaption: this.centerCaption,
-      centerReveal: props?.showCenter === false ? 0 : 1,
-    })
-
-    const children: Node2D[] = [this.ring]
-    if (showLegend) {
-      this.legend = new PieLegend({
-        slices,
-        legend: () => this.resolvedTheme.legend,
-        dims: () => this.sliceDims(),
-      })
-      children.push(this.legend)
-    }
-
-    this.add(
-      new Rect({ flow: "horizontal",
-        width: "fill",
-        height: "fill",
-        gap: this.gap,
-        align: "center",
-        children,
-      })
-    )
-  }
-
-  // ---- Orchestrated entrance --------------------------------------------
-
-  /**
-   * Prime every part at its pre-entrance state — no wedges swept, no labels, the
-   * legend shifted 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. The hole's summary is deliberately untouched:
-   * it has its own signal, so a scene that set it up to land later keeps that.
-   */
-  arm(): void {
-    this.ring.set({ growth: 0, labelReveal: 0 })
-    this.legend?.arm()
-  }
-
-  /**
-   * Animate the whole chart in: the wedges sweep in clockwise from the theme's
-   * `startAngle`, then the labels fade up and the legend staggers in together.
-   *
-   * `duration` is the **whole** entrance; the phases are shares of it.
-   */
-  @command()
-  enter(
-    args: CommandArgs<Record<string, never>> & { duration: number }
-  ): Command<Record<string, never>> {
-    const duration = args.duration
-    const easing = args.easing ?? easeOut()
-    this.arm()
-
-    return asCommand(
-      sequenceOf(
-        this.ring.sweep({ duration: duration * SWEEP_SHARE, easing }),
-        together(
-          this.ring.revealLabels({ duration: duration * LABEL_SHARE, easing }),
-          this.legend
-            ? this.legend.enter({ duration: duration * LABEL_SHARE, easing })
-            : hold(duration * LABEL_SHARE)
-        )
-      ),
-      duration
-    )
-  }
-
-  /**
-   * Fade the hole's summary up.
-   *
-   * Held out of {@link enter} on purpose: what sits in a donut's hole is usually
-   * the chart's conclusion, so the scene lands it on the beat it belongs to
-   * rather than giving it away with the first frame. Pair it with
-   * `showCenter: false`, which is what leaves the hole clear to begin with.
-   */
-  @command()
-  revealCenter(
-    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
-  ): Command<{ centerReveal: number }> {
-    return this.ring.revealCenter({ duration: args.duration ?? 0.6, easing: args.easing ?? easeOut() })
-  }
-
-  // ---- Selection ---------------------------------------------------------
-
-  /** True when slice `index` is currently grown out past the ring's rim. */
-  isSelected(index: number): boolean {
-    return this.popAt(index) > 0.5
-  }
-
-  /**
-   * Grow slice `index` out past the ring's rim and dim the rest of the chart
-   * behind it, leaving any other selected slice where it is.
-   */
-  @command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
-  selectSlice(
-    args: CommandArgs<{ sliceIndex: number }> & { duration?: number }
-  ): Command<SlicePops> {
-    const { sliceIndex: index } = args.data as { sliceIndex: number }
-    const duration = args.duration ?? 0.45
-    const easing = args.easing ?? easeOut()
-    return this.tweenPops((i) => (i === index ? 1 : this.popAt(i)), duration, easing)
-  }
-
-  /** Settle slice `index` back flush with the ring. */
-  @command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
-  deselectSlice(
-    args: CommandArgs<{ sliceIndex: number }> & { duration?: number }
-  ): Command<SlicePops> {
-    const { sliceIndex: index } = args.data as { sliceIndex: number }
-    const duration = args.duration ?? 0.45
-    const easing = args.easing ?? easeOut()
-    return this.tweenPops((i) => (i === index ? 0 : this.popAt(i)), duration, easing)
-  }
-
-  /** Move the focus to slice `index` alone, settling whatever else was out. */
-  @command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
-  selectOnlySlice(
-    args: CommandArgs<{ sliceIndex: number }> & { duration?: number }
-  ): Command<SlicePops> {
-    const { sliceIndex: index } = args.data as { sliceIndex: number }
-    const duration = args.duration ?? 0.45
-    const easing = args.easing ?? easeOut()
-    return this.tweenPops((i) => (i === index ? 1 : 0), duration, easing)
-  }
-
-  /** Settle every slice flush and bring the whole chart back to full. */
-  @command()
-  clearSelection(
-    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
-  ): Command<SlicePops> {
-    const duration = args.duration ?? 0.45
-    const easing = args.easing ?? easeOut()
-    return this.tweenPops(() => 0, duration, easing)
-  }
-
-  /**
-   * Ease every slice's pop from where it is now to what `pop` asks for.
-   *
-   * Consumes its full duration even when nothing moves: in the studio a
-   * command's duration is what the timeline lays out and what its parallel
-   * siblings are timed against, so a no-op that took no frames would pull
-   * everything after it forward.
-   *
-   * `from` and the targets are read when the command is *built*, which for a
-   * driven scene is with the node in the state its own start time implies — so a
-   * select that follows another starts from where that one left the ring.
-   */
-  private tweenPops(
-    pop: (index: number) => number,
-    duration: number,
-    easing: EasingFunction
-  ): Command<SlicePops> {
-    const from = this.data.map((_, i) => this.popAt(i))
-    const targets = this.data.map((_, i) => clampUnit(pop(i)))
-    if (from.every((value, i) => value === targets[i])) return this.command<SlicePops>(() => ({}), duration)
-
-    return this.command<SlicePops>(
-      (t) => ({ pops: from.map((value, i) => value + (targets[i] - value) * t) }),
-      duration,
-      easing
-    )
-  }
-}
+import {
+  Rect,
+  command,
+  node,
+  Node2D,
+  easeOut,
+  property,
+  type Command,
+  type CommandArgs,
+  type DataRecord,
+  type EasingFunction,
+  type NodeConfig,
+  type Node2DProps,
+} from "@motionscript/sdk"
+
+import { clampUnit } from "../kit/shared"
+import { PieLegend } from "./pie-legend"
+import { PieRing } from "./pie-ring"
+import {
+  DEFAULT_PIE_CHART_THEME,
+  lerpPieChartTheme,
+  resolvePieChartTheme,
+  resolvePieSlices,
+  type PieChartConfig,
+  type PieChartTheme,
+  type PieLabelMode,
+  type PieLabelPlacement,
+  type PieSlice,
+} from "./shared"
+import {
+  asCommand,
+  hold,
+  sequence as sequenceOf,
+  together,
+} from "@motionscript/sdk/component"
+
+export interface PieChartProps extends Node2DProps {
+  /** One row per slice — a plain record of field name to value. */
+  data: DataRecord[]
+  /** Key into each row for its slice caption, used on the labels and the legend. */
+  categoryField: string
+  /** Key into each row for its slice magnitude — the wedge's share of the ring. */
+  valueField: string
+  /**
+   * The chart's visual theme — slice palette, ring geometry, label and centre
+   * type, legend. Every branch is optional and deep-merged onto
+   * {@link DEFAULT_PIE_CHART_THEME}.
+   */
+  theme?: PieChartTheme
+  /** What the ring's labels say. */
+  labelMode?: PieLabelMode
+  /** Where they sit: inside their wedge, outside on a leader, or nowhere. */
+  labelPlacement?: PieLabelPlacement
+  /** Whether the legend column beside the ring is drawn at all. */
+  showLegend?: boolean
+  /** Gap between the ring and the legend, in px. */
+  gap?: number
+  /** Text set in the ring's hole — see {@link revealCenter}. */
+  centerLabel?: string
+  /** Smaller second line under {@link centerLabel}. */
+  centerCaption?: string
+  /**
+   * Whether the hole's summary is drawn at rest. `true` (the default) is the
+   * plain answer; a scene that wants the conclusion to land on a later beat sets
+   * this `false` and calls {@link revealCenter} when it gets there.
+   */
+  showCenter?: boolean
+}
+
+/**
+ * How {@link PieChart.enter} divides its duration: the wedges sweeping in, then
+ * the labels and the legend arriving together. Shares of the whole, so they sum
+ * to 1 — the entrance takes exactly the time it was given, for the reason spelt
+ * out on `LineChart.enter`.
+ */
+const SWEEP_SHARE = 0.65
+const LABEL_SHARE = 0.35
+
+/** What the selection commands move: the chart's own {@link PieChart.pops}. */
+type SlicePops = { pops: number[] }
+
+/**
+ * A pie or donut chart, composed from two independent parts rather than one
+ * monolithic draw — the third of the chart family, built the same way as the
+ * line and bar charts beside it:
+ *
+ * - {@link PieRing} — the wedges, each sized by its share of the total, with its
+ *   label set inside its own band or pinned outside on a leader line, and the
+ *   summary in the hole. The only part of the family that draws a path.
+ * - {@link PieLegend} — a column of swatch-and-caption rows naming each slice.
+ *
+ * The two are laid out by a plain horizontal-flow {@link Rect}: the ring fills whatever the
+ * hugging legend leaves, both centred, so the chart re-flows if its box changes.
+ *
+ * **One mark per row, not per column** — which is what makes this the odd one of
+ * the three. A line or a bar chart plots *series*, so its colours belong to
+ * columns and hiding one is a sensible thing to ask for. A pie plots rows, so its
+ * palette is indexed by row and there is nothing to hide: dropping a slice would
+ * silently re-cut every other wedge's share, which is a different chart rather
+ * than the same chart with a series switched off. {@link selectSlice} and its
+ * siblings are what a pie has instead — a slice swells out of the ring, its hole
+ * edge staying put, and everything else dims behind it.
+ *
+ * **Resting state is the finished chart** — the same bargain the other two make:
+ * 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. The one exception
+ * is the hole's summary, which a scene can hold back with `showCenter: false`
+ * because it is usually the chart's *conclusion* rather than part of its setup.
+ */
+@node({
+  key: "pieChart",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+    acceptsChildren: true,
+  },
+  seed: {
+    width: 680,
+    height: 480,
+  },
+})
+export class PieChart extends Node2D<PieChartProps> {
+  @property({ default: () => [] as DataRecord[] }) declare data: DataRecord[]
+  @property({ default: "" }) declare categoryField: string
+  @property({ default: "" }) declare valueField: string
+  @property({
+    default: DEFAULT_PIE_CHART_THEME,
+    mapper: resolvePieChartTheme,
+    tween: lerpPieChartTheme,
+  })
+  declare theme: PieChartTheme
+  @property({ default: "percent" }) declare labelMode: PieLabelMode
+  @property({ default: "leader" }) declare labelPlacement: PieLabelPlacement
+  @property({ default: 40 }) declare gap: number
+  @property({ default: "" }) declare centerLabel: string
+  @property({ default: "" }) declare centerCaption: string
+
+  /**
+   * How far each slice is currently pushed out of the ring, `0`–`1` per index.
+   *
+   * Held here rather than on the ring because two parts read it: the wedges grow
+   * out by it, and the legend entries dim by it. One signal, one tween, and the
+   * two can't drift.
+   */
+  @property({ default: () => [] as number[] }) declare pops: number[]
+
+  // ---- Part handles (built in the constructor) --------------------------
+  private ring: PieRing
+  private legend: PieLegend | null = null
+
+  /** `this.theme` read back through its *resolved* shape — see `LineChart.theme`. */
+  private get resolvedTheme(): PieChartConfig {
+    return this.theme as unknown as PieChartConfig
+  }
+
+  /** The slices the ring and the legend draw, resolved from the rows and the palette. */
+  private get slices(): PieSlice[] {
+    return resolvePieSlices(
+      this.data,
+      this.categoryField,
+      this.valueField,
+      this.resolvedTheme.sliceFills
+    )
+  }
+
+  /**
+   * How far each slice is dimmed by the current selection, one entry per slice —
+   * 1 while nothing is selected, and for the selected slice itself; falling
+   * toward the theme's `dimOpacity` for the rest in proportion to how far the
+   * selection has grown.
+   */
+  private sliceDims(): number[] {
+    let focus = 0
+    for (let i = 0; i < this.data.length; i++) {
+      focus = Math.max(focus, this.popAt(i))
+    }
+    const dim = this.resolvedTheme.spotlight.dimOpacity
+    if (focus <= 0) return this.data.map(() => 1)
+    return this.data.map(
+      (_, i) => 1 - (1 - clampUnit(dim)) * focus * (1 - this.popAt(i))
+    )
+  }
+
+  /** How far slice `index` is currently pushed out, in `[0, 1]`. */
+  private popAt(index: number): number {
+    return clampUnit(this.pops[index] ?? 0)
+  }
+
+  constructor(props?: NodeConfig<PieChart, PieChartProps>) {
+    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). The slice
+    // *structure* (one label and one legend row per row of `data`) is read once,
+    // like every other chart's series list; everything the parts draw with,
+    // including the slices themselves and the paint they take from the palette,
+    // is passed as a closure, so `chart.to({ theme })` genuinely re-paints the
+    // ring and the swatches and a `set` of `data` re-cuts the wedges.
+    const slices = this.slices
+    const showLegend = props?.showLegend !== false
+    this.pops = slices.map(() => 0)
+
+    this.ring = new PieRing({
+      width: "fill",
+      height: "fill",
+      slices: () => this.slices,
+      ring: () => this.resolvedTheme.ring,
+      label: () => this.resolvedTheme.label,
+      centerStyle: () => this.resolvedTheme.center,
+      labelMode: this.labelMode,
+      labelPlacement: this.labelPlacement,
+      pops: () => this.pops,
+      dimOpacity: () => this.resolvedTheme.spotlight.dimOpacity,
+      centerLabel: this.centerLabel,
+      centerCaption: this.centerCaption,
+      centerReveal: props?.showCenter === false ? 0 : 1,
+    })
+
+    const children: Node2D[] = [this.ring]
+    if (showLegend) {
+      this.legend = new PieLegend({
+        slices: () => this.slices,
+        legend: () => this.resolvedTheme.legend,
+        dims: () => this.sliceDims(),
+      })
+      children.push(this.legend)
+    }
+
+    this.add(
+      new Rect({ flow: "horizontal",
+        width: "fill",
+        height: "fill",
+        gap: this.gap,
+        align: "center",
+        children,
+      })
+    )
+  }
+
+  // ---- Orchestrated entrance --------------------------------------------
+
+  /**
+   * Prime every part at its pre-entrance state — no wedges swept, no labels, the
+   * legend shifted 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. The hole's summary is deliberately untouched:
+   * it has its own signal, so a scene that set it up to land later keeps that.
+   */
+  arm(): void {
+    this.ring.set({ growth: 0, labelReveal: 0 })
+    this.legend?.arm()
+  }
+
+  /**
+   * Animate the whole chart in: the wedges sweep in clockwise from the theme's
+   * `startAngle`, then the labels fade up and the legend staggers in together.
+   *
+   * `duration` is the **whole** entrance; the phases are shares of it.
+   */
+  @command()
+  enter(
+    args: CommandArgs<Record<string, never>> & { duration: number }
+  ): Command<Record<string, never>> {
+    const duration = args.duration
+    const easing = args.easing ?? easeOut()
+    this.arm()
+
+    return asCommand(
+      sequenceOf(
+        this.ring.sweep({ duration: duration * SWEEP_SHARE, easing }),
+        together(
+          this.ring.revealLabels({ duration: duration * LABEL_SHARE, easing }),
+          this.legend
+            ? this.legend.enter({ duration: duration * LABEL_SHARE, easing })
+            : hold(duration * LABEL_SHARE)
+        )
+      ),
+      duration
+    )
+  }
+
+  /**
+   * Fade the hole's summary up.
+   *
+   * Held out of {@link enter} on purpose: what sits in a donut's hole is usually
+   * the chart's conclusion, so the scene lands it on the beat it belongs to
+   * rather than giving it away with the first frame. Pair it with
+   * `showCenter: false`, which is what leaves the hole clear to begin with.
+   */
+  @command()
+  revealCenter(
+    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
+  ): Command<{ centerReveal: number }> {
+    return this.ring.revealCenter({ duration: args.duration ?? 0.6, easing: args.easing ?? easeOut() })
+  }
+
+  // ---- Selection ---------------------------------------------------------
+
+  /** True when slice `index` is currently grown out past the ring's rim. */
+  isSelected(index: number): boolean {
+    return this.popAt(index) > 0.5
+  }
+
+  /**
+   * Grow slice `index` out past the ring's rim and dim the rest of the chart
+   * behind it, leaving any other selected slice where it is.
+   */
+  @command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
+  selectSlice(
+    args: CommandArgs<{ sliceIndex: number }> & { duration?: number }
+  ): Command<SlicePops> {
+    const { sliceIndex: index } = args.data as { sliceIndex: number }
+    const duration = args.duration ?? 0.45
+    const easing = args.easing ?? easeOut()
+    return this.tweenPops((i) => (i === index ? 1 : this.popAt(i)), duration, easing)
+  }
+
+  /** Settle slice `index` back flush with the ring. */
+  @command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
+  deselectSlice(
+    args: CommandArgs<{ sliceIndex: number }> & { duration?: number }
+  ): Command<SlicePops> {
+    const { sliceIndex: index } = args.data as { sliceIndex: number }
+    const duration = args.duration ?? 0.45
+    const easing = args.easing ?? easeOut()
+    return this.tweenPops((i) => (i === index ? 0 : this.popAt(i)), duration, easing)
+  }
+
+  /** Move the focus to slice `index` alone, settling whatever else was out. */
+  @command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
+  selectOnlySlice(
+    args: CommandArgs<{ sliceIndex: number }> & { duration?: number }
+  ): Command<SlicePops> {
+    const { sliceIndex: index } = args.data as { sliceIndex: number }
+    const duration = args.duration ?? 0.45
+    const easing = args.easing ?? easeOut()
+    return this.tweenPops((i) => (i === index ? 1 : 0), duration, easing)
+  }
+
+  /** Settle every slice flush and bring the whole chart back to full. */
+  @command()
+  clearSelection(
+    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
+  ): Command<SlicePops> {
+    const duration = args.duration ?? 0.45
+    const easing = args.easing ?? easeOut()
+    return this.tweenPops(() => 0, duration, easing)
+  }
+
+  /**
+   * Ease every slice's pop from where it is now to what `pop` asks for.
+   *
+   * Consumes its full duration even when nothing moves: in an editor a
+   * command's duration is what the timeline lays out and what its parallel
+   * siblings are timed against, so a no-op that took no frames would pull
+   * everything after it forward.
+   *
+   * `from` and the targets are read when the command is *built*, which for a
+   * driven scene is with the node in the state its own start time implies — so a
+   * select that follows another starts from where that one left the ring.
+   */
+  private tweenPops(
+    pop: (index: number) => number,
+    duration: number,
+    easing: EasingFunction
+  ): Command<SlicePops> {
+    const from = this.data.map((_, i) => this.popAt(i))
+    const targets = this.data.map((_, i) => clampUnit(pop(i)))
+    if (from.every((value, i) => value === targets[i])) return this.command<SlicePops>(() => ({}), duration)
+
+    return this.command<SlicePops>(
+      (t) => ({ pops: from.map((value, i) => value + (targets[i] - value) * t) }),
+      duration,
+      easing
+    )
+  }
+}