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

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

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

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

@@ -0,0 +1,113 @@
+import { type NodeOf, type RectProps, 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 { type Arrival } from "../kit/motion.js";
+import { type LegendConfig } from "../kit/shared.js";
+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 PieLegendProps.dims}.
+ */
+export declare const PieLegend: import("@motionscript/sdk").Component<"pieLegend", import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    readonly slices: import("@motionscript/sdk").Type<PieSlice[], PieSlice[], false>;
+    readonly legend: import("@motionscript/sdk").Type<LegendConfig, LegendConfig, false>;
+    readonly dims: import("@motionscript/sdk").Type<number[], number[], false>;
+    readonly arrivals: import("@motionscript/sdk").Type<Readonly<Record<string, Arrival>>, Readonly<Record<string, Arrival>>, false>;
+    readonly cornerRadius: import("@motionscript/sdk").Attribute<_RectCornerRadius, _CornerRadiusResolved>;
+    readonly cornerStyle: import("@motionscript/sdk").Attribute<_RectCornerStyle, _CornerStyleResolved>;
+    readonly flow: import("@motionscript/sdk").Type<_FlowMode, _FlowResolved, false>;
+    readonly gap: import("@motionscript/sdk").Type<_GapSize, _GapSize, false>;
+    readonly wrap: boolean;
+    readonly crossGap: import("@motionscript/sdk").Type<number | undefined, number | undefined, false>;
+    readonly columns: import("@motionscript/sdk").Type<number, number, false>;
+    readonly align: import("@motionscript/sdk").Attribute<_Alignment, _Vector2>;
+    readonly fill: import("@motionscript/sdk").Attribute<_Fill, _FillResolved[]>;
+    readonly stroke: import("@motionscript/sdk").Attribute<_Stroke, _StrokeResolved[]>;
+    readonly shadow: import("@motionscript/sdk").Attribute<_Shadow, _ShadowResolved[]>;
+    readonly overlay: import("@motionscript/sdk").Attribute<_Fill, _FillResolved[]>;
+    readonly start: import("@motionscript/sdk").Type<number, number, false>;
+    readonly end: import("@motionscript/sdk").Type<number, number, false>;
+}>, {
+    readonly arm: unknown;
+    readonly enter: unknown;
+    readonly fillTo: readonly ["fill"];
+    readonly strokeTo: readonly ["stroke"];
+    readonly shadowTo: readonly ["shadow"];
+    readonly overlayTo: readonly ["overlay"];
+    readonly progressTo: readonly ["start", "end"];
+    readonly flash: {
+        readonly portion: import("@motionscript/sdk").Type<number, number, false>;
+    };
+}, null, _Node2D<_Node2DProps>, import("@motionscript/sdk").CallProps<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    readonly slices: import("@motionscript/sdk").Type<PieSlice[], PieSlice[], false>;
+    readonly legend: import("@motionscript/sdk").Type<LegendConfig, LegendConfig, false>;
+    readonly dims: import("@motionscript/sdk").Type<number[], number[], false>;
+    readonly arrivals: import("@motionscript/sdk").Type<Readonly<Record<string, Arrival>>, Readonly<Record<string, Arrival>>, false>;
+    readonly cornerRadius: import("@motionscript/sdk").Attribute<_RectCornerRadius, _CornerRadiusResolved>;
+    readonly cornerStyle: import("@motionscript/sdk").Attribute<_RectCornerStyle, _CornerStyleResolved>;
+    readonly flow: import("@motionscript/sdk").Type<_FlowMode, _FlowResolved, false>;
+    readonly gap: import("@motionscript/sdk").Type<_GapSize, _GapSize, false>;
+    readonly wrap: boolean;
+    readonly crossGap: import("@motionscript/sdk").Type<number | undefined, number | undefined, false>;
+    readonly columns: import("@motionscript/sdk").Type<number, number, false>;
+    readonly align: import("@motionscript/sdk").Attribute<_Alignment, _Vector2>;
+    readonly fill: import("@motionscript/sdk").Attribute<_Fill, _FillResolved[]>;
+    readonly stroke: import("@motionscript/sdk").Attribute<_Stroke, _StrokeResolved[]>;
+    readonly shadow: import("@motionscript/sdk").Attribute<_Shadow, _ShadowResolved[]>;
+    readonly overlay: import("@motionscript/sdk").Attribute<_Fill, _FillResolved[]>;
+    readonly start: import("@motionscript/sdk").Type<number, number, false>;
+    readonly end: import("@motionscript/sdk").Type<number, number, false>;
+}>, null, import("@motionscript/sdk").BuiltNode<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    readonly slices: import("@motionscript/sdk").Type<PieSlice[], PieSlice[], false>;
+    readonly legend: import("@motionscript/sdk").Type<LegendConfig, LegendConfig, false>;
+    readonly dims: import("@motionscript/sdk").Type<number[], number[], false>;
+    readonly arrivals: import("@motionscript/sdk").Type<Readonly<Record<string, Arrival>>, Readonly<Record<string, Arrival>>, false>;
+    readonly cornerRadius: import("@motionscript/sdk").Attribute<_RectCornerRadius, _CornerRadiusResolved>;
+    readonly cornerStyle: import("@motionscript/sdk").Attribute<_RectCornerStyle, _CornerStyleResolved>;
+    readonly flow: import("@motionscript/sdk").Type<_FlowMode, _FlowResolved, false>;
+    readonly gap: import("@motionscript/sdk").Type<_GapSize, _GapSize, false>;
+    readonly wrap: boolean;
+    readonly crossGap: import("@motionscript/sdk").Type<number | undefined, number | undefined, false>;
+    readonly columns: import("@motionscript/sdk").Type<number, number, false>;
+    readonly align: import("@motionscript/sdk").Attribute<_Alignment, _Vector2>;
+    readonly fill: import("@motionscript/sdk").Attribute<_Fill, _FillResolved[]>;
+    readonly stroke: import("@motionscript/sdk").Attribute<_Stroke, _StrokeResolved[]>;
+    readonly shadow: import("@motionscript/sdk").Attribute<_Shadow, _ShadowResolved[]>;
+    readonly overlay: import("@motionscript/sdk").Attribute<_Fill, _FillResolved[]>;
+    readonly start: import("@motionscript/sdk").Type<number, number, false>;
+    readonly end: import("@motionscript/sdk").Type<number, number, false>;
+}>, {
+    readonly arm: unknown;
+    readonly enter: unknown;
+    readonly fillTo: readonly ["fill"];
+    readonly strokeTo: readonly ["stroke"];
+    readonly shadowTo: readonly ["shadow"];
+    readonly overlayTo: readonly ["overlay"];
+    readonly progressTo: readonly ["start", "end"];
+    readonly flash: {
+        readonly portion: import("@motionscript/sdk").Type<number, number, false>;
+    };
+}, _Node2D<_Node2DProps>>>>;
+export type PieLegend = NodeOf<typeof PieLegend>;
+//# 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,EASL,KAAK,MAAM,EACX,KAAK,SAAS,EAEd,KAAK,SAAS,IAAI,UAAU,EAC5B,KAAK,oBAAoB,IAAI,qBAAqB,EAClD,KAAK,mBAAmB,IAAI,oBAAoB,EAChD,KAAK,IAAI,IAAI,KAAK,EAClB,KAAK,YAAY,IAAI,aAAa,EAClC,KAAK,QAAQ,IAAI,SAAS,EAC1B,KAAK,YAAY,IAAI,aAAa,EAClC,KAAK,OAAO,IAAI,QAAQ,EACxB,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,WAAW,IAAI,YAAY,EAChC,KAAK,gBAAgB,IAAI,iBAAiB,EAC1C,KAAK,eAAe,IAAI,gBAAgB,EACxC,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,cAAc,IAAI,eAAe,EACtC,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,cAAc,IAAI,eAAe,EACtC,KAAK,OAAO,IAAI,QAAQ,EACzB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAA8D,KAAK,OAAO,EAAE,MAAM,eAAe,CAAA;AACxG,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAA;AACtB,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,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA+FpB,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,SAAS,CAAC,CAAA"}

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

@@ -0,0 +1,117 @@
+import { Flow, Paint, Rect, Shapes, Text, Types, component2d, textOps, } from "@motionscript/sdk";
+import { fresh } from "../kit/entries.js";
+import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase } from "../kit/motion.js";
+import { DEFAULT_LEGEND, clampUnit, } from "../kit/shared.js";
+/** 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(() => []),
+        legend: Types.custom(DEFAULT_LEGEND),
+        dims: fresh(() => []),
+        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 = { 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)),
+});
+//# sourceMappingURL=pie-legend.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pie-legend.js","sourceRoot":"","sources":["../../src/pie-chart/pie-legend.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  Flow,\n  Paint,\n  Rect,\n  Shapes,\n  Text,\n  Types,\n  component2d,\n  textOps,\n  type NodeOf,\n  type RectProps,\n  // Named so the column's emitted type reaches the Rect surface it spreads through the sdk, not core.\n  type Alignment as _Alignment,\n  type CornerRadiusResolved as _CornerRadiusResolved,\n  type CornerStyleResolved as _CornerStyleResolved,\n  type Fill as _Fill,\n  type FillResolved as _FillResolved,\n  type FlowMode as _FlowMode,\n  type FlowResolved as _FlowResolved,\n  type GapSize as _GapSize,\n  type Node2D as _Node2D,\n  type Node2DProps as _Node2DProps,\n  type RectCornerRadius as _RectCornerRadius,\n  type RectCornerStyle as _RectCornerStyle,\n  type Shadow as _Shadow,\n  type ShadowResolved as _ShadowResolved,\n  type Stroke as _Stroke,\n  type StrokeResolved as _StrokeResolved,\n  type Vector2 as _Vector2,\n} from \"@motionscript/sdk\"\n\nimport { fresh } from \"../kit/entries\"\nimport { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from \"../kit/motion\"\nimport {\n  DEFAULT_LEGEND,\n  clampUnit,\n  type LegendConfig,\n} from \"../kit/shared\"\nimport type { PieSlice } from \"./shared\"\n\nexport interface PieLegendProps extends RectProps {\n  /** One entry per slice, in ring order. */\n  slices: PieSlice[]\n  /** Padding, caption style, gaps, and swatch geometry — see {@link LegendConfig}. */\n  legend: LegendConfig\n  /**\n   * Per-slice opacity multiplier, by index — the same signal that dims the ring,\n   * so an entry fades in step with the wedge it names. Missing entries read as 1.\n   */\n  dims: number[]\n}\n\n/** How far an entry starts to the right of its slot when it enters, in px. */\nconst SLIDE = 16\n\n/**\n * The legend of a {@link PieChart}: a **vertical-flow column** of entries, one per\n * slice, each pairing the slice's caption with its colour swatch.\n *\n * A column rather than the cartesian charts' row, because it sits *beside* the\n * ring rather than beneath the plot — a pie is as tall as it is wide, so the\n * space it leaves over is a vertical strip. It is otherwise the same entry: the\n * swatch carries the colour, the caption reads in the legend's neutral ink, and\n * both take the shared {@link LegendConfig}.\n *\n * There is no show/hide here. A pie's marks are its *rows*, and a row that\n * shouldn't be in the chart shouldn't be in the table — removing one would\n * silently re-cut every other wedge's share, which is a different chart rather\n * than the same chart with something hidden. Selection is what a pie has\n * instead, and it arrives through {@link PieLegendProps.dims}.\n */\nexport const PieLegend = component2d({\n  key: \"pieLegend\",\n  state: {\n    ...Paint.state,\n    ...Flow.state,\n    ...Shapes.corners,\n    slices: fresh<PieSlice[]>(() => []),\n    legend: Types.custom<LegendConfig>(DEFAULT_LEGEND),\n    dims: fresh<number[]>(() => []),\n    arrivals: arrivalsEntry(),\n  },\n  // A column, for the reason `ChartLegend` gives for its row: a `Rect` given no\n  // flow lays its children out `freeform`, every caption on top of the last.\n  defaults: {\n    flow: \"vertical\",\n    align: \"centerLeft\",\n    width: \"hug\",\n    height: \"hug\",\n    gap: (state) => state.legend.itemGap / 3,\n    padding: (state) => state.legend.padding,\n  },\n  // One entry per slice, ordered top → bottom. The selection dim rides a wrapper\n  // rather than the entry itself, so the entrance can animate the entry's own\n  // opacity without the two fighting over one value — opacity multiplies down\n  // the tree, which is exactly the composition wanted here.\n  children: (state) => {\n    const marker = state.legend.markerStyle\n    return state.slices.map((_, index) =>\n      Rect({\n        width: \"hug\",\n        height: \"hug\",\n        flow: \"freeform\",\n        opacity: () => clampUnit(state.dims[index] ?? 1),\n        children: [\n          Rect({\n            flow: \"horizontal\",\n            gap: 12,\n            align: \"center\",\n            width: \"hug\",\n            height: \"hug\",\n            opacity: () => arrivalOf(state.arrivals, index).opacity,\n            x: () => arrivalOf(state.arrivals, index).shift,\n            children: [\n              Rect({\n                width: marker.height,\n                height: marker.height,\n                cornerRadius: marker.borderRadius,\n                fill: () => state.slices[index]?.fill ?? \"white\",\n                stroke: marker.stroke,\n                shadow: marker.shadow,\n              }),\n              Text({\n                ...textOps.styleProps(state.legend.textStyle),\n                text: () => state.slices[index]?.category ?? \"\",\n              }),\n            ],\n          }),\n        ],\n      })\n    )\n  },\n  commands: {\n    ...Paint.commands,\n    /**\n     * Every entry at its pre-entrance state, shifted right and transparent: what\n     * a chart shows ahead of this legend's own beat in its entrance, since\n     * `enter` arms the entries only on its first frame.\n     */\n    arm: (timeline, state) =>\n      timeline.animate(() => ({ arrivals: armed([...state.slices.keys()], { opacity: 0, shift: SLIDE }) })),\n    /**\n     * Slide + fade every entry in from the right, staggered top-to-bottom. Its\n     * first frame arms them all: shifted right and transparent.\n     *\n     * The timeline's duration is the **whole** entrance: the stagger is carved\n     * out of it rather than added on top, so the command takes exactly the time\n     * the timeline laid out for it.\n     */\n    enter: (timeline, state) => {\n      const count = state.slices.length\n      if (count === 0) return timeline.wait(timeline.duration)\n      const from: Arrival = { opacity: 0, shift: SLIDE }\n      const arm = timeline.animate(() => ({ arrivals: armed([...state.slices.keys()], from) }))\n      // Each gap is a fifth of an entry's own move, the rhythm the axes use;\n      // solved for from the budget rather than added to it.\n      const per = timeline.duration / (1 + Math.max(0, count - 1) / 5)\n      const step = per / 5\n      const ease = frameEase(timeline)\n      const entries = state.slices.map((_, i) => ({ at: i * step, duration: per, piece: arrival(timeline, i, from, ease) }))\n      return timeline.together([arm, beats(timeline, entries)])\n    },\n  },\n  measure: (measurer, state, children) => Flow.measure(measurer, state, children, Paint.inset(state)),\n  layout: (box, state, children) => Flow.layout(box, state, children, Paint.inset(state)),\n  render: (ctx, state) => Paint.draw(ctx, state, Shapes.rect(ctx.size, state)),\n})\n\nexport type PieLegend = NodeOf<typeof PieLegend>\n"]}