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

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

@@ -0,0 +1,296 @@
+import {
+  Rect,
+  Types,
+  component2d,
+  easeOut,
+  type ChildView,
+  type DataRecord,
+  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"
+import {
+  DEFAULT_PIE_CHART_THEME,
+  lerpPieChartTheme,
+  resolvePieChartTheme,
+  resolvePieSlices,
+  type PieChartConfig,
+  type PieChartTheme,
+  type PieLabelMode,
+  type PieLabelPlacement,
+  type PieSlice,
+} from "./shared"
+
+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 `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 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 `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 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 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.
+ *
+ * **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**; `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*.
+ */
+export const PieChart = component2d({
+  key: "pieChart",
+  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 }),
+  },
+  defaults: {
+    // Its parts fill it; a node made of them would hug them.
+    width: "fill",
+    height: "fill",
+    pops: (state) => slicesOf(state).map(() => 0),
+  },
+  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",
+        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([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),
+    },
+  },
+})
+
+export type PieChart = NodeOf<typeof PieChart>

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

@@ -0,0 +1,169 @@
+import {
+  Flow,
+  Paint,
+  Rect,
+  Shapes,
+  Text,
+  Types,
+  component2d,
+  textOps,
+  type NodeOf,
+  type RectProps,
+  // Named so the column's emitted type reaches the Rect surface it spreads through the sdk, not core.
+  type Alignment as _Alignment,
+  type CornerRadiusResolved as _CornerRadiusResolved,
+  type CornerStyleResolved as _CornerStyleResolved,
+  type Fill as _Fill,
+  type FillResolved as _FillResolved,
+  type FlowMode as _FlowMode,
+  type FlowResolved as _FlowResolved,
+  type GapSize as _GapSize,
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
+  type RectCornerRadius as _RectCornerRadius,
+  type RectCornerStyle as _RectCornerStyle,
+  type Shadow as _Shadow,
+  type ShadowResolved as _ShadowResolved,
+  type Stroke as _Stroke,
+  type StrokeResolved as _StrokeResolved,
+  type Vector2 as _Vector2,
+} from "@motionscript/sdk"
+
+import { fresh } from "../kit/entries"
+import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "../kit/motion"
+import {
+  DEFAULT_LEGEND,
+  clampUnit,
+  type LegendConfig,
+} from "../kit/shared"
+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 PieLegendProps.dims}.
+ */
+export const PieLegend = component2d({
+  key: "pieLegend",
+  state: {
+    ...Paint.state,
+    ...Flow.state,
+    ...Shapes.corners,
+    slices: fresh<PieSlice[]>(() => []),
+    legend: Types.custom<LegendConfig>(DEFAULT_LEGEND),
+    dims: fresh<number[]>(() => []),
+    arrivals: arrivalsEntry(),
+  },
+  // A column, for the reason `ChartLegend` gives for its row: a `Rect` given no
+  // flow lays its children out `freeform`, every caption on top of the last.
+  defaults: {
+    flow: "vertical",
+    align: "centerLeft",
+    width: "hug",
+    height: "hug",
+    gap: (state) => state.legend.itemGap / 3,
+    padding: (state) => state.legend.padding,
+  },
+  // One entry per slice, ordered top → bottom. 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.
+  children: (state) => {
+    const marker = state.legend.markerStyle
+    return state.slices.map((_, index) =>
+      Rect({
+        width: "hug",
+        height: "hug",
+        flow: "freeform",
+        opacity: () => clampUnit(state.dims[index] ?? 1),
+        children: [
+          Rect({
+            flow: "horizontal",
+            gap: 12,
+            align: "center",
+            width: "hug",
+            height: "hug",
+            opacity: () => arrivalOf(state.arrivals, index).opacity,
+            x: () => arrivalOf(state.arrivals, index).shift,
+            children: [
+              Rect({
+                width: marker.height,
+                height: marker.height,
+                cornerRadius: marker.borderRadius,
+                fill: () => state.slices[index]?.fill ?? "white",
+                stroke: marker.stroke,
+                shadow: marker.shadow,
+              }),
+              Text({
+                ...textOps.styleProps(state.legend.textStyle),
+                text: () => state.slices[index]?.category ?? "",
+              }),
+            ],
+          }),
+        ],
+      })
+    )
+  },
+  commands: {
+    ...Paint.commands,
+    /**
+     * Every entry at its pre-entrance state, shifted right and transparent: what
+     * a chart shows ahead of this legend's own beat in its entrance, since
+     * `enter` arms the entries only on its first frame.
+     */
+    arm: (timeline, state) =>
+      timeline.animate(() => ({ arrivals: armed([...state.slices.keys()], { opacity: 0, shift: SLIDE }) })),
+    /**
+     * Slide + fade every entry in from the right, staggered top-to-bottom. Its
+     * first frame arms them all: shifted right and transparent.
+     *
+     * The timeline's 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.
+     */
+    enter: (timeline, state) => {
+      const count = state.slices.length
+      if (count === 0) return timeline.wait(timeline.duration)
+      const from: Arrival = { opacity: 0, shift: SLIDE }
+      const arm = timeline.animate(() => ({ arrivals: armed([...state.slices.keys()], from) }))
+      // 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.
+      const per = timeline.duration / (1 + Math.max(0, count - 1) / 5)
+      const step = per / 5
+      const ease = frameEase(timeline)
+      const entries = state.slices.map((_, i) => ({ at: i * step, duration: per, piece: arrival(timeline, i, from, ease) }))
+      return timeline.together([arm, beats(timeline, entries)])
+    },
+  },
+  measure: (measurer, state, children) => Flow.measure(measurer, state, children, Paint.inset(state)),
+  layout: (box, state, children) => Flow.layout(box, state, children, Paint.inset(state)),
+  render: (ctx, state) => Paint.draw(ctx, state, Shapes.rect(ctx.size, state)),
+})
+
+export type PieLegend = NodeOf<typeof PieLegend>