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

package/dist/pie-chart/pie-chart.d.ts

@@ -0,0 +1,170 @@
+import { Node2D, type CommandArgs, type DataRecord, type NodeConfig, type Node2DProps } from "@motionscript/core";
+import { type PieChartTheme, type PieLabelMode, type PieLabelPlacement } from "./shared.js";
+import { 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;
+}
+/**
+ * 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.
+ */
+export declare class PieChart extends Node2D<PieChartProps> {
+    data: DataRecord[];
+    categoryField: string;
+    valueField: string;
+    theme: PieChartTheme;
+    labelMode: PieLabelMode;
+    labelPlacement: PieLabelPlacement;
+    gap: number;
+    centerLabel: string;
+    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.
+     */
+    pops: number[];
+    private ring;
+    private legend;
+    /** `this.theme` read back through its *resolved* shape — see `LineChart.theme`. */
+    private get resolvedTheme();
+    /** The slices the ring and the legend draw, resolved from the rows and the palette. */
+    private get slices();
+    /**
+     * 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;
+    /** How far slice `index` is currently pushed out, in `[0, 1]`. */
+    private popAt;
+    constructor(props?: NodeConfig<PieChart, PieChartProps>);
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    enter(args: CommandArgs<Record<string, never>> & {
+        duration: number;
+    }): Seekable;
+    /**
+     * 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.
+     */
+    revealCenter(args?: CommandArgs<Record<string, never>> & {
+        duration?: number;
+    }): Seekable;
+    /** True when slice `index` is currently grown out past the ring's rim. */
+    isSelected(index: number): boolean;
+    /**
+     * 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.
+     */
+    selectSlice(args: CommandArgs<{
+        sliceIndex: number;
+    }> & {
+        duration?: number;
+    }): Seekable;
+    /** Settle slice `index` back flush with the ring. */
+    deselectSlice(args: CommandArgs<{
+        sliceIndex: number;
+    }> & {
+        duration?: number;
+    }): Seekable;
+    /** Move the focus to slice `index` alone, settling whatever else was out. */
+    selectOnlySlice(args: CommandArgs<{
+        sliceIndex: number;
+    }> & {
+        duration?: number;
+    }): Seekable;
+    /** Settle every slice flush and bring the whole chart back to full. */
+    clearSelection(args?: CommandArgs<Record<string, never>> & {
+        duration?: number;
+    }): Seekable;
+    /**
+     * 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;
+}
+//# sourceMappingURL=pie-chart.d.ts.map

package/dist/pie-chart/pie-chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pie-chart.d.ts","sourceRoot":"","sources":["../../src/pie-chart/pie-chart.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,MAAM,EAGN,KAAK,WAAW,EAChB,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAA;AAK3B,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAEvB,MAAM,UAAU,CAAA;AACjB,OAAO,EAKL,KAAK,QAAQ,EACd,MAAM,8BAA8B,CAAA;AAErC,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,iEAAiE;IACjE,IAAI,EAAE,UAAU,EAAE,CAAA;IAClB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAA;IACrB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,kCAAkC;IAClC,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,iBAAiB,CAAA;IAClC,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAea,QAAS,SAAQ,MAAM,CAAC,aAAa,CAAC;IACQ,IAAI,EAAE,UAAU,EAAE,CAAA;IACxC,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAM7C,KAAK,EAAE,aAAa,CAAA;IACc,SAAS,EAAE,YAAY,CAAA;IACxB,cAAc,EAAE,iBAAiB,CAAA;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IAExD;;;;;;OAMG;IACkD,IAAI,EAAE,MAAM,EAAE,CAAA;IAGnE,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,MAAM,CAAyB;IAEvC,mFAAmF;IACnF,OAAO,KAAK,aAAa,GAExB;IAED,uFAAuF;IACvF,OAAO,KAAK,MAAM,GAOjB;IAED;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAYjB,kEAAkE;IAClE,OAAO,CAAC,KAAK;gBAID,KAAK,CAAC,EAAE,UAAU,CAAC,QAAQ,EAAE,aAAa,CAAC;IAmDvD;;;;;;;;OAQG;IACH,GAAG,IAAI,IAAI;IAKX;;;;;OAKG;IAEH,KAAK,CACH,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAC9D,QAAQ;IAgBX;;;;;;;OAOG;IAEH,YAAY,CACV,IAAI,GAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GACpE,QAAQ;IAMX,0EAA0E;IAC1E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIlC;;;OAGG;IAEH,WAAW,CACT,IAAI,EAAE,WAAW,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAChE,QAAQ;IAOX,qDAAqD;IAErD,aAAa,CACX,IAAI,EAAE,WAAW,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAChE,QAAQ;IAOX,6EAA6E;IAE7E,eAAe,CACb,IAAI,EAAE,WAAW,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAChE,QAAQ;IAOX,uEAAuE;IAEvE,cAAc,CACZ,IAAI,GAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GACpE,QAAQ;IAMX;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,SAAS;CAclB"}

package/dist/pie-chart/pie-chart.js

@@ -0,0 +1,291 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Rect, command, node, Node2D, easeOut, property, } from "@motionscript/core";
+import { clampUnit } from "../kit/shared.js";
+import { PieLegend } from "./pie-legend.js";
+import { PieRing } from "./pie-ring.js";
+import { DEFAULT_PIE_CHART_THEME, lerpPieChartTheme, resolvePieChartTheme, resolvePieSlices, } from "./shared.js";
+import { drive, hold, sequence as sequenceOf, together, } from "@motionscript/core/component";
+/**
+ * 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.
+ */
+let PieChart = class PieChart extends Node2D {
+    // ---- Part handles (built in the constructor) --------------------------
+    ring;
+    legend = null;
+    /** `this.theme` read back through its *resolved* shape — see `LineChart.theme`. */
+    get resolvedTheme() {
+        return this.theme;
+    }
+    /** The slices the ring and the legend draw, resolved from the rows and the palette. */
+    get slices() {
+        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.
+     */
+    sliceDims() {
+        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]`. */
+    popAt(index) {
+        return clampUnit(this.pops[index] ?? 0);
+    }
+    constructor(props) {
+        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 = [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() {
+        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.
+     */
+    enter(args) {
+        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.
+     */
+    revealCenter(args = {}) {
+        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) {
+        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.
+     */
+    selectSlice(args) {
+        const { sliceIndex: index } = args.data;
+        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. */
+    deselectSlice(args) {
+        const { sliceIndex: index } = args.data;
+        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. */
+    selectOnlySlice(args) {
+        const { sliceIndex: index } = args.data;
+        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. */
+    clearSelection(args = {}) {
+        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.
+     */
+    tweenPops(pop, duration, easing) {
+        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);
+        });
+    }
+};
+__decorate([
+    property({ default: () => [] })
+], PieChart.prototype, "data", void 0);
+__decorate([
+    property({ default: "" })
+], PieChart.prototype, "categoryField", void 0);
+__decorate([
+    property({ default: "" })
+], PieChart.prototype, "valueField", void 0);
+__decorate([
+    property({
+        default: DEFAULT_PIE_CHART_THEME,
+        mapper: resolvePieChartTheme,
+        tween: lerpPieChartTheme,
+    })
+], PieChart.prototype, "theme", void 0);
+__decorate([
+    property({ default: "percent" })
+], PieChart.prototype, "labelMode", void 0);
+__decorate([
+    property({ default: "leader" })
+], PieChart.prototype, "labelPlacement", void 0);
+__decorate([
+    property({ default: 40 })
+], PieChart.prototype, "gap", void 0);
+__decorate([
+    property({ default: "" })
+], PieChart.prototype, "centerLabel", void 0);
+__decorate([
+    property({ default: "" })
+], PieChart.prototype, "centerCaption", void 0);
+__decorate([
+    property({ default: () => [] })
+], PieChart.prototype, "pops", void 0);
+__decorate([
+    command()
+], PieChart.prototype, "enter", null);
+__decorate([
+    command()
+], PieChart.prototype, "revealCenter", null);
+__decorate([
+    command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
+], PieChart.prototype, "selectSlice", null);
+__decorate([
+    command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
+], PieChart.prototype, "deselectSlice", null);
+__decorate([
+    command({ args: [{ key: "sliceIndex", kind: "number", default: 0, min: 0, step: 1 }] })
+], PieChart.prototype, "selectOnlySlice", null);
+__decorate([
+    command()
+], PieChart.prototype, "clearSelection", null);
+PieChart = __decorate([
+    node({
+        key: "pieChart",
+        parentKey: "node",
+        forkable: true,
+        layout: {
+            children: "freeform",
+            defaultWidthMode: "fixed",
+            defaultHeightMode: "fixed",
+            acceptsChildren: true,
+        },
+        seed: {
+            width: 680,
+            height: 480,
+        },
+    })
+], PieChart);
+export { PieChart };
+//# sourceMappingURL=pie-chart.js.map

package/dist/pie-chart/pie-chart.js.map

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

package/dist/pie-chart/pie-legend.d.ts

@@ -0,0 +1,60 @@
+import { Rect, type CommandArgs, type NodeConfig, type RectProps } from "@motionscript/core";
+import { type LegendConfig } from "../kit/shared.js";
+import { type Seekable } from "@motionscript/core/component";
+import type { PieSlice } from "./shared.js";
+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[];
+}
+/**
+ * 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 declare class PieLegend extends Rect {
+    slices: PieSlice[];
+    legend: LegendConfig;
+    dims: number[];
+    /** One entry per slice, ordered top → bottom, for the staggered entrance. */
+    private items;
+    constructor(props?: NodeConfig<PieLegend, PieLegendProps>);
+    /** One entry: the slice's colour swatch beside its caption. */
+    private buildItem;
+    /**
+     * 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?: number): void;
+    /**
+     * 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.
+     */
+    enter(args: CommandArgs<Record<string, never>> & {
+        duration: number;
+    }): Seekable;
+}
+//# sourceMappingURL=pie-legend.d.ts.map

package/dist/pie-chart/pie-legend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pie-legend.d.ts","sourceRoot":"","sources":["../../src/pie-chart/pie-legend.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,IAAI,EAKJ,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAqB,KAAK,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,0CAA0C;IAC1C,MAAM,EAAE,QAAQ,EAAE,CAAA;IAClB,oFAAoF;IACpF,MAAM,EAAE,YAAY,CAAA;IACpB;;;OAGG;IACH,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAKD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAU,SAAQ,IAAI;IACsB,MAAM,EAAE,QAAQ,EAAE,CAAA;IAC1B,MAAM,EAAE,YAAY,CAAA;IACd,IAAI,EAAE,MAAM,EAAE,CAAA;IAEnE,6EAA6E;IAC7E,OAAO,CAAC,KAAK,CAAa;gBAEd,KAAK,CAAC,EAAE,UAAU,CAAC,SAAS,EAAE,cAAc,CAAC;IAmCzD,+DAA+D;IAC/D,OAAO,CAAC,SAAS;IAwBjB;;;;;;OAMG;IACH,GAAG,CAAC,KAAK,SAAQ,GAAG,IAAI;IAIxB;;;;;;OAMG;IAEH,KAAK,CACH,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAC9D,QAAQ;CAkBZ"}