@motionscript/charts 0.0.0-stage → 0.1.0-alpha.0

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

@@ -0,0 +1,374 @@
+import {
+  Rect,
+  command,
+  node,
+  Node2D,
+  easeOut,
+  property,
+  type CommandArgs,
+  type DataRecord,
+  type EasingFunction,
+  type NodeConfig,
+  type Node2DProps,
+} from "@motionscript/core"
+
+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 {
+  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. */
+  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
+
+/**
+ * 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 }
+  ): 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)
+      )
+    )
+  }
+
+  /**
+   * 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)
+
+    return drive(duration, (t) => {
+      const e = easing(t)
+      this.pops = from.map((value, i) => value + (targets[i] - value) * e)
+    })
+  }
+}

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

@@ -0,0 +1,159 @@
+import {
+  command,
+  Rect,
+  Text,
+  easeOut,
+  property,
+  textOps,
+  type CommandArgs,
+  type NodeConfig,
+  type RectProps,
+} from "@motionscript/core"
+
+import {
+  DEFAULT_LEGEND,
+  clampUnit,
+  type LegendConfig,
+} from "../kit/shared"
+import { at, compose, hold, type Seekable } from "@motionscript/core/component"
+import type { PieSlice } from "./shared"
+
+export interface PieLegendProps extends RectProps {
+  /** One entry per slice, in ring order. */
+  slices: PieSlice[]
+  /** Padding, caption style, gaps, and swatch geometry — see {@link LegendConfig}. */
+  legend: LegendConfig
+  /**
+   * Per-slice opacity multiplier, by index — the same signal that dims the ring,
+   * so an entry fades in step with the wedge it names. Missing entries read as 1.
+   */
+  dims: number[]
+}
+
+/** How far an entry starts to the right of its slot when it enters, in px. */
+const SLIDE = 16
+
+/**
+ * The legend of a {@link PieChart}: a **vertical-flow column** of entries, one per
+ * slice, each pairing the slice's caption with its colour swatch.
+ *
+ * A column rather than the cartesian charts' row, because it sits *beside* the
+ * ring rather than beneath the plot — a pie is as tall as it is wide, so the
+ * space it leaves over is a vertical strip. It is otherwise the same entry: the
+ * swatch carries the colour, the caption reads in the legend's neutral ink, and
+ * both take the shared {@link LegendConfig}.
+ *
+ * There is no show/hide here. A pie's marks are its *rows*, and a row that
+ * shouldn't be in the chart shouldn't be in the table — removing one would
+ * silently re-cut every other wedge's share, which is a different chart rather
+ * than the same chart with something hidden. Selection is what a pie has
+ * instead, and it arrives through {@link dims}.
+ */
+export class PieLegend extends Rect {
+  @property({ default: () => [] as PieSlice[] }) declare slices: PieSlice[]
+  @property({ default: DEFAULT_LEGEND }) declare legend: LegendConfig
+  @property({ default: () => [] as number[] }) declare dims: number[]
+
+  /** One entry per slice, ordered top → bottom, for the staggered entrance. */
+  private items: Rect[] = []
+
+  constructor(props?: NodeConfig<PieLegend, PieLegendProps>) {
+    // `flow` with the rest of the fixed geometry, and for the reason
+    // {@link ChartLegend} spells out: a `Rect` given none lays its children out
+    // `freeform`, so an unstated column is every caption drawn on top of the
+    // last one.
+    super({
+      ...(props as RectProps),
+      flow: "vertical",
+      align: "centerLeft",
+      width: "hug",
+      height: "hug",
+    })
+
+    // Fixed column geometry last, so it wins over what super() applied.
+    this.set({ gap: this.legend.itemGap / 3, padding: this.legend.padding })
+
+    for (let i = 0; i < this.slices.length; i++) {
+      const item = this.buildItem(this.slices[i])
+      this.items.push(item)
+      // The selection dim rides a wrapper rather than the entry itself, so the
+      // entrance can animate the entry's own opacity without the two fighting
+      // over one value — opacity multiplies down the tree, which is exactly the
+      // composition wanted here.
+      this.add(
+        new Rect({
+          width: "hug",
+          height: "hug",
+          flow: "freeform",
+          opacity: () => clampUnit(this.dims[i] ?? 1),
+          children: [item],
+        })
+      )
+    }
+  }
+
+  /** One entry: the slice's colour swatch beside its caption. */
+  private buildItem(slice: PieSlice): Rect {
+    const marker = this.legend.markerStyle
+    return new Rect({ flow: "horizontal",
+      gap: 12,
+      align: "center",
+      width: "hug",
+      height: "hug",
+      children: [
+        new Rect({
+          width: marker.height,
+          height: marker.height,
+          cornerRadius: marker.borderRadius,
+          fill: slice.fill,
+          stroke: marker.stroke,
+          shadow: marker.shadow,
+        }),
+        new Text({
+          ...textOps.styleProps(this.legend.textStyle),
+          text: slice.category,
+        }),
+      ],
+    })
+  }
+
+  /**
+   * Prime every entry at its pre-entrance state: shifted right and transparent.
+   *
+   * Idempotent, and separate from {@link enter} so the chart can arm its whole
+   * composition before the first frame is drawn — the resting state is the
+   * finished legend, so there is nothing hidden to reveal unless a scene asks.
+   */
+  arm(slide = SLIDE): void {
+    for (const item of this.items) item.set({ opacity: 0, x: slide })
+  }
+
+  /**
+   * Slide + fade every entry in from the right, staggered top-to-bottom.
+   *
+   * `duration` is the **whole** entrance: the stagger is carved out of it rather
+   * than added on top, so the command takes exactly the time the timeline laid
+   * out for it.
+   */
+  @command()
+  enter(
+    args: CommandArgs<Record<string, never>> & { duration: number }
+  ): Seekable {
+    const duration = args.duration
+    const easing = args.easing ?? easeOut()
+    const items = this.items
+    if (items.length === 0) return hold(duration)
+    this.arm()
+
+    // Each gap is a fifth of an entry's own move, the rhythm the axes use;
+    // solved for from the budget rather than added to it. The offsets were
+    // always `i * step` — written as `wait` inside a generator they merely only
+    // existed while it ran.
+    const per = duration / (1 + Math.max(0, items.length - 1) / 5)
+    const step = per / 5
+
+    return compose(
+      items.map((item, i) => at(i * step, item.to({ data: { opacity: 1, x: 0 }, duration: per, easing })))
+    )
+  }
+}