@motionscript/charts 0.1.0-alpha.0 → 0.1.0-alpha.10

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

@@ -1,17 +1,19 @@
 import {
   Rect,
-  command,
-  node,
-  Node2D,
+  Types,
+  component2d,
   easeOut,
-  property,
-  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,
-} from "@motionscript/core"
+  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"
@@ -26,13 +28,6 @@ import {
   type PieLabelPlacement,
   type PieSlice,
 } from "./shared"
-import {
-  drive,
-  hold,
-  sequence as sequenceOf,
-  together,
-  type Seekable,
-} from "@motionscript/core/component"
 
 export interface PieChartProps extends Node2DProps {
   /** One row per slice — a plain record of field name to value. */
@@ -55,320 +50,247 @@ 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
 
+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** — 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.
+ * **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.
  *
- * **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.
+ * **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 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",
+  allowedChildren: [],
+  // 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 }
-  ): Seekable {
-    const duration = args.duration
-    const easing = args.easing ?? easeOut()
-    this.arm()
-
-    return 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)
+        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
       )
-    )
-  }
-
-  /**
-   * 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 } = {}
-  ): Seekable {
-    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 }
-  ): Seekable {
-    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 }
-  ): Seekable {
-    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 }
-  ): Seekable {
-    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 } = {}
-  ): Seekable {
-    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
-  ): Seekable {
-    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 hold(duration)
+    }
+    const row = new Rect({ flow: "horizontal", width: "fill", height: "fill", gap: state.gap, align: "center", children: parts })
+    return asParts([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: {},
+      // Held from the chart's arrival, so it never shows finished ahead of its draw.
+      entrance: true,
+      easing: easeOut(),
+      run: (timeline, _state, children) => {
+        const parts = partsOf(children)
+        if (!parts) return timeline.wait(timeline.duration)
+        const { 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 drive(duration, (t) => {
-      const e = easing(t)
-      this.pops = from.map((value, i) => value + (targets[i] - value) * e)
-    })
-  }
-}
+export type PieChart = NodeOf<typeof PieChart>