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

package/src/line-chart/shared.ts

@@ -12,7 +12,7 @@
  * Kept renderer-agnostic (no `Node` imports) so every part shares one
  * scale/format/palette/theme vocabulary, and so a host's own inspector
  * mapping can build a partial {@link ChartTheme} without
- * pulling the node classes in.
+ * pulling the components in.
  */
 
 import {
@@ -365,7 +365,7 @@ function lerpRegionConfig(
 }
 
 /**
- * {@link LineChart}'s `theme` @property mapper: merges the author's partial
+ * {@link LineChart}'s `theme` entry's resolve: merges the author's partial
  * {@link ChartTheme} onto `previous` (falling back to
  * {@link DEFAULT_CHART_THEME} on first resolution), fully resolving every leaf.
  */
@@ -384,7 +384,7 @@ export function resolveChartTheme(
   }
 }
 
-/** {@link LineChart}'s `theme` @property tween — leaf by leaf. */
+/** {@link LineChart}'s `theme` entry's lerp — leaf by leaf. */
 export function lerpChartTheme(
   from: ChartConfig,
   to: ChartConfig,

package/src/nodes.ts

@@ -6,15 +6,13 @@ import { PieChart } from "./pie-chart";
  * Every node type this package publishes.
  *
  * A host registers these by handing the array to an engine —
- * `new Engine(platform, { nodes: NODES })` — which reads each class's `@node()`
- * key. The decorator only *declares* that key: nothing is registered by the mere
- * act of importing a module, so a registry holds exactly what its owner asked
- * for and two engines in one process can differ about it.
+ * `new Engine(platform, { nodes: NODES })` — which reads each component's key.
+ * Defining a component only *declares* that key: nothing is registered by
+ * importing a module, so a registry holds exactly what its owner asked for.
  *
- * Listing class **values** is also what survives bundling. This package declares
- * `sideEffects: false`, which licenses a bundler to drop a module nothing
- * imports a value from, and a document names a node type by string — so
- * `import "./line-chart"` for its side effect is exactly what gets shaken out, where an
- * array of bindings is a data dependency that cannot be.
+ * Listing the component **values** is also what survives bundling: this package
+ * declares `sideEffects: false`, and a document names a node type by string, so
+ * an import kept only for its side effect is exactly what gets shaken out.
  */
-export const NODES = [LineChart, BarChart, PieChart];
+// Typed by name, so the declaration names each component rather than spelling out its type through core.
+export const NODES: (typeof LineChart | typeof BarChart | typeof PieChart)[] = [LineChart, BarChart, PieChart];

package/src/pie-chart/index.ts

@@ -7,8 +7,8 @@
  * pie; it defaults to a donut, because the hole is the only place a chart has
  * to put its conclusion.
  */
-export { PieChart } from "./pie-chart"
-export type { PieChartProps } from "./pie-chart"
+export { PieChart, isSliceSelected } from "./pie-chart"
+export type { PieChartProps, PieChartValues } from "./pie-chart"
 export { PieRing } from "./pie-ring"
 export type { PieRingProps } from "./pie-ring"
 export { PieLegend } from "./pie-legend"

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

@@ -1,18 +1,19 @@
 import {
   Rect,
-  command,
-  node,
-  Node2D,
+  Types,
+  component2d,
   easeOut,
-  property,
-  type Command,
-  type CommandArgs,
+  type ChildView,
   type DataRecord,
-  type EasingFunction,
-  type NodeConfig,
+  type NodeOf,
+  // Named so this component's emitted type reaches `Node2D` through the sdk, not core.
+  type Node2D,
   type Node2DProps,
+  type Timeline,
 } from "@motionscript/sdk"
 
+import { asParts, fresh } from "../kit/entries"
+import { beats, type Beat } from "../kit/motion"
 import { clampUnit } from "../kit/shared"
 import { PieLegend } from "./pie-legend"
 import { PieRing } from "./pie-ring"
@@ -27,12 +28,6 @@ import {
   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. */
@@ -55,329 +50,244 @@ export interface PieChartProps extends Node2DProps {
   showLegend?: boolean
   /** Gap between the ring and the legend, in px. */
   gap?: number
-  /** Text set in the ring's hole — see {@link revealCenter}. */
+  /** Text set in the ring's hole — see `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.
+   * this `false` and runs `revealCenter` when it gets there.
    */
   showCenter?: boolean
 }
 
+/** What the selection reads: the rows, how they are cut, and the pops the commands move. */
+export interface PieChartValues {
+  readonly data: DataRecord[]
+  readonly categoryField: string
+  readonly valueField: string
+  readonly theme: PieChartConfig
+  readonly pops: number[]
+}
+
 /**
- * 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`.
+ * How `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.
  */
 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[] }
+const SLICE_ARG = Types.number(0, { min: 0, step: 1 })
+
+/** The slices the ring and the legend draw, resolved from the rows and the palette. */
+function slicesOf(s: PieChartValues): PieSlice[] {
+  return resolvePieSlices(s.data, s.categoryField, s.valueField, s.theme.sliceFills)
+}
+
+/** How far slice `index` is pushed out, in `[0, 1]`. */
+function popAt(s: PieChartValues, index: number): number {
+  return clampUnit(s.pops[index] ?? 0)
+}
+
+/** Whether slice `index` is grown out past the ring's rim: past half way, so a slice mid-swell is not yet counted. */
+export function isSliceSelected(s: PieChartValues, index: number): boolean {
+  return popAt(s, index) > 0.5
+}
+
+/**
+ * How far each slice is dimmed by the selection, one entry per slice: 1 while
+ * nothing is out, and for the selected slice itself; falling toward the theme's
+ * `dimOpacity` for the rest in proportion to how far the selection has grown.
+ */
+function sliceDims(s: PieChartValues): number[] {
+  let focus = 0
+  for (let i = 0; i < s.data.length; i++) focus = Math.max(focus, popAt(s, i))
+  const dim = s.theme.spotlight.dimOpacity
+  if (focus <= 0) return s.data.map(() => 1)
+  return s.data.map((_, i) => 1 - (1 - clampUnit(dim)) * focus * (1 - popAt(s, i)))
+}
+
+type AnyTimeline = Timeline<any, any>
+
+/**
+ * Every slice's pop eased from where it is to what `pop` asks for. A move that
+ * changes nothing still takes its slot, writing nothing.
+ */
+function popping(timeline: AnyTimeline, s: PieChartValues, pop: (index: number) => number) {
+  const from = s.data.map((_, i) => popAt(s, i))
+  const targets = s.data.map((_, i) => clampUnit(pop(i)))
+  if (from.every((value, i) => value === targets[i])) return timeline.wait(timeline.duration)
+  return timeline.animate((t) => ({ pops: from.map((value, i) => value + (targets[i] - value) * t) }))
+}
+
+/** The ring and the legend, found through the chart's children: the last row of them is the one it built. */
+function partsOf(children: readonly ChildView[]) {
+  for (let i = children.length - 1; i >= 0; i--) {
+    const row = children[i]
+    const ring = Rect.is(row) ? row.children.find(PieRing.is) : undefined
+    if (ring) return { ring, legend: row.children.find(PieLegend.is) ?? null }
+  }
+  return null
+}
 
 /**
- * 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:
+ * A pie or donut chart, composed from two parts laid out by a horizontal-flow
+ * {@link Rect} — the ring filling whatever the hugging legend leaves, both
+ * centred:
  *
  * - {@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.
+ *   label inside its own band or pinned outside on a leader line, and the
+ *   summary in the hole.
  * - {@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**: a pie's palette is indexed by row and
+ * there is nothing to hide, since dropping a slice would re-cut every other
+ * wedge. `selectSlice` and its siblings are what a pie has instead — a slice
+ * swells out of the ring and everything else dims behind it.
  *
- * **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.
+ * **Resting state is the finished chart**; `enter` arms every part on its first
+ * frame. 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*.
  */
-@node({
+export const PieChart = component2d({
   key: "pieChart",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    defaultWidthMode: "fixed",
-    defaultHeightMode: "fixed",
-    acceptsChildren: true,
+  state: {
+    data: fresh<DataRecord[]>(() => []),
+    categoryField: "",
+    valueField: "",
+    theme: Types.custom<PieChartTheme, PieChartConfig>(DEFAULT_PIE_CHART_THEME, { resolve: resolvePieChartTheme, lerp: lerpPieChartTheme }),
+    labelMode: Types.custom<PieLabelMode>("percent"),
+    labelPlacement: Types.custom<PieLabelPlacement>("leader"),
+    gap: 40,
+    centerLabel: "",
+    centerCaption: "",
+    /**
+     * How far each slice is 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. Seeded flush, one to a row.
+     */
+    pops: fresh<number[]>(() => []),
+    /** 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 the hole's summary is drawn at rest. */
+    showCenter: Types.boolean(true, { animatable: false }),
   },
-  seed: {
-    width: 680,
-    height: 480,
+  defaults: {
+    // Its parts fill it; a node made of them would hug them.
+    width: "fill",
+    height: "fill",
+    pops: (state) => slicesOf(state).map(() => 0),
   },
-})
-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",
+  // The slice *structure* (one label and one legend row per row) is read once;
+  // the slices themselves, their paint and the selection are bound, so a theme
+  // tween re-paints and a `set` of `data` re-cuts the wedges.
+  children: (state) => {
+    const theme = () => state.theme
+    const slices = () => slicesOf(state)
+    const parts: Node2D[] = [
+      new PieRing({
         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)
+        slices,
+        ring: () => theme().ring,
+        label: () => theme().label,
+        centerStyle: () => theme().center,
+        labelMode: state.labelMode,
+        labelPlacement: state.labelPlacement,
+        pops: () => state.pops,
+        dimOpacity: () => theme().spotlight.dimOpacity,
+        centerLabel: state.centerLabel,
+        centerCaption: state.centerCaption,
+        centerReveal: state.showCenter === false ? 0 : 1,
+      }) as unknown as Node2D,
+    ]
+    if (state.showLegend !== false) {
+      parts.push(
+        new PieLegend({
+          slices,
+          legend: () => theme().legend,
+          dims: () => sliceDims(state),
+          // The column's spacing is the theme's as the chart was built, like the
+          // entries' type and chips.
+          gap: state.theme.legend.itemGap / 3,
+          padding: state.theme.legend.padding,
+        }) as unknown as Node2D
+      )
+    }
+    const row = new Rect({ flow: "horizontal", width: "fill", height: "fill", gap: state.gap, align: "center", children: parts })
+    return asParts([...(state.children as unknown as Node2D[]), row as unknown as Node2D])
+  },
+  commands: {
+    /**
+     * 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.
+     * Its first frame arms the wedges, the labels and the legend; the hole's
+     * summary keeps its own signal. `duration` is the **whole** entrance.
+     */
+    enter: {
+      args: {},
+      easing: easeOut(),
+      run: (timeline, _state, children) => {
+        const parts = partsOf(children)
+        if (!parts) return timeline.wait(timeline.duration)
+        const { ring, legend } = parts
+        const sweep = timeline.duration * SWEEP_SHARE
+        const labels = timeline.duration * LABEL_SHARE
+        const at0 = (piece: Beat["piece"]): Beat => ({ at: 0, duration: 0, piece })
+        return beats(timeline, [
+          at0(ring.to({ growth: 0, labelReveal: 0 })),
+          ...(legend ? [at0(legend.run("arm"))] : []),
+          { at: 0, duration: sweep, piece: ring.run("sweep") },
+          { at: sweep, duration: labels, piece: ring.run("revealLabels") },
+          ...(legend ? [{ at: sweep, duration: labels, piece: legend.run("enter") }] : []),
+        ])
+      },
+    },
+    /**
+     * Fade the hole's summary up. Held out of `enter` on purpose: what sits in a
+     * donut's hole is usually the chart's conclusion, so the scene lands it on
+     * its own beat. Pair it with `showCenter: false`.
+     */
+    revealCenter: {
+      args: {},
+      easing: easeOut(),
+      run: (timeline, _state, children) => partsOf(children)?.ring.run("revealCenter") ?? timeline.wait(timeline.duration),
+    },
+    /** Grow slice `index` out past the ring's rim and dim the rest, leaving any other selected slice where it is. */
+    selectSlice: {
+      args: { sliceIndex: SLICE_ARG },
+      easing: easeOut(),
+      run: (timeline, state) => {
+        const index = timeline.args.sliceIndex
+        return popping(timeline, state, (i) => (i === index ? 1 : popAt(state, i)))
+      },
+    },
+    /** Settle slice `index` back flush with the ring. */
+    deselectSlice: {
+      args: { sliceIndex: SLICE_ARG },
+      easing: easeOut(),
+      run: (timeline, state) => {
+        const index = timeline.args.sliceIndex
+        return popping(timeline, state, (i) => (i === index ? 0 : popAt(state, i)))
+      },
+    },
+    /** Move the focus to slice `index` alone, settling whatever else was out. */
+    selectOnlySlice: {
+      args: { sliceIndex: SLICE_ARG },
+      easing: easeOut(),
+      run: (timeline, state) => {
+        const index = timeline.args.sliceIndex
+        return popping(timeline, state, (i) => (i === index ? 1 : 0))
+      },
+    },
+    /** Settle every slice flush and bring the whole chart back to full. */
+    clearSelection: {
+      args: {},
+      easing: easeOut(),
+      run: (timeline, state) => popping(timeline, state, () => 0),
+    },
+  },
+})
 
-    return this.command<SlicePops>(
-      (t) => ({ pops: from.map((value, i) => value + (targets[i] - value) * t) }),
-      duration,
-      easing
-    )
-  }
-}
+export type PieChart = NodeOf<typeof PieChart>