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

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

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

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

@@ -0,0 +1,266 @@
+import { type AssetScope, Node2D, type Command, type CommandArgs, type NodeConfig, type Node2DProps, type RenderContext2D } from "@motionscript/core";
+import { type CenterConfig, type LabelConfig, type PieLabelMode, type PieLabelPlacement, type PieSlice, type RingConfig } from "./shared.js";
+export interface PieRingProps extends Node2DProps {
+    /** One entry per slice: its `category`, `value` and `fill`. */
+    slices: PieSlice[];
+    /** Ring geometry and paint — gap, hole, start angle, selection growth. */
+    ring: RingConfig;
+    /** How the labels are set, and the leader lines that point at them. */
+    label: LabelConfig;
+    /**
+     * How the hole's summary is set.
+     *
+     * Named `centerStyle` rather than `center` because every node already has a
+     * `center` — the anchor its position is measured from.
+     */
+    centerStyle: CenterConfig;
+    /** What the labels say, or `"none"` to drop them entirely. */
+    labelMode: PieLabelMode;
+    /** Where the labels sit: inside their wedge, outside on a leader, or nowhere. */
+    labelPlacement: PieLabelPlacement;
+    /**
+     * Sweep of the ring in `[0, 1]`: 0 draws nothing, 1 the full circle. The
+     * wedges grow around clockwise from the ring's `startAngle` as this rises.
+     */
+    growth: number;
+    /**
+     * Fade of the leader lines and labels in `[0, 1]`, held separate from
+     * {@link growth} so they arrive *after* the ring has swept in.
+     */
+    labelReveal: number;
+    /**
+     * How far each slice is currently pushed out of the ring, `0`–`1` per index.
+     * Owned by the chart, so the ring and the legend read one signal.
+     */
+    pops: number[];
+    /** Opacity everything *unselected* falls back to while any slice is selected. */
+    dimOpacity: number;
+    /**
+     * Text set in the middle of the ring's hole — the largest uninterrupted area
+     * the chart owns, and on a donut otherwise empty. A one-line summary there
+     * routinely does more work than the whole ring around it. Empty (the default)
+     * leaves the hole clear; ignored when there is no hole.
+     */
+    centerLabel: string;
+    /** Smaller second line under {@link centerLabel}. Empty (the default) drops it. */
+    centerCaption: string;
+    /**
+     * Fade of the hole's summary in `[0, 1]`. Its own signal, untouched by the
+     * ring's entrance — a hole label is usually a *conclusion*, so a scene that
+     * wants it to land on a later beat sets this to 0 and calls
+     * `PieChart.revealCenter` when it gets there.
+     */
+    centerReveal: number;
+}
+/**
+ * The ring itself: one wedge per {@link PieSlice}, sized by its share of the
+ * total, swept clockwise from the theme's `startAngle` with a `gap` of clear
+ * space between neighbours — a *constant-width* channel, the same at the hole as
+ * at the rim (see {@link wedgePath}). A **selected** slice reaches further out
+ * while its hole edge stays put — so it reads as that band swelling out of the
+ * ring rather than breaking off it — and the rest of the ring dims behind it,
+ * leaders and labels included.
+ *
+ * This is the only part of the chart family that draws a path: the wedges are
+ * filled {@link PathBuilder} polygons approximating each arc, and the leaders are
+ * stroked polylines — both in the node's centred, y-up space, so neither depends
+ * on SVG arc-sweep conventions. The **labels are real {@link Text} nodes**
+ * (stacked in a hug vertical flow and pinned by their inner edge), so no
+ * glyph-width guesswork decides where a caption starts.
+ *
+ * ### Label placement
+ * Each label sits either **inside** its wedge or **outside** on a leader.
+ *
+ * An inside label is centred on its slice's band and leads with the number, the
+ * caption set small underneath — inside a wedge the reader already knows which
+ * slice they're on, so the magnitude is the thing being read. It costs no gutter
+ * and no eye round-trip, so a ring labelled that way draws considerably bigger in
+ * the same box.
+ *
+ * A leader label sits outside on the end of a polyline that lifts off its wedge,
+ * elbows, and runs horizontally into the text. Labels are split into a left and a
+ * right column by which way their slice's bisector points, and each column is
+ * de-conflicted independently (see {@link relaxLabels}): a label takes the spot
+ * nearest its wedge that still clears its neighbour, and the column is squeezed
+ * to fit the node's height rather than spilling out of it. The elbow then rides on
+ * a circle just outside the ring **at the label's settled y**, so the run into the
+ * text is always horizontal and a nudged label never drags its leader back across
+ * the ring.
+ *
+ * Only the sides that actually carry a leader reserve a gutter, and the ring's
+ * centre slides into whatever the other side left over ({@link centerX}) — so a
+ * ring whose slices all leader one way doesn't leave a bald patch on the other.
+ */
+export declare class PieRing extends Node2D<PieRingProps> {
+    slices: PieSlice[];
+    ring: RingConfig;
+    label: LabelConfig;
+    centerStyle: CenterConfig;
+    labelMode: PieLabelMode;
+    labelPlacement: PieLabelPlacement;
+    growth: number;
+    labelReveal: number;
+    pops: number[];
+    dimOpacity: number;
+    centerLabel: string;
+    centerCaption: string;
+    centerReveal: number;
+    /** Each slice's fill, resolved once so `renderSelf` doesn't re-resolve every frame. */
+    private fills;
+    constructor(props?: NodeConfig<PieRing, PieRingProps>);
+    /** Build slice `arc`'s label, in whichever form the chart's placement asks for. */
+    private addLabel;
+    /** Build the hole's summary block. */
+    private addCenterLabel;
+    /** The drawn slices' angular spans, re-read every frame so a value tween re-cuts them. */
+    private get arcs();
+    /** Which side a leader off bisector `mid` runs to: +1 right, −1 left. */
+    private sideOf;
+    /** Whether any slice is labelled on a leader — the only thing that costs a gutter. */
+    private get hasLeaderLabels();
+    /**
+     * How wide a horizontal label centred in slice `arc`'s band can run before it
+     * leaves the wedge, in px.
+     *
+     * Two things bound it, and which one binds depends entirely on where the wedge
+     * sits. Stepping sideways from the label's centre moves you *radially* by
+     * `dx·sin(mid)` and *tangentially* by `dx·cos(mid)`, so a wedge at 3 o'clock is
+     * limited by the band's thickness (its label runs straight across the band)
+     * while a wedge at 12 o'clock is limited by its own arc (its label runs along
+     * the band, which is much roomier). Taking the smaller of the two is what stops
+     * a label overflowing the ring on one chart and being pointlessly shrunk on the
+     * next.
+     *
+     * Measured off the *unpopped* radius, so a slice growing out of the ring
+     * doesn't resize its own text mid-animation.
+     */
+    private insideRoom;
+    /** Widest line, in glyphs at the leading line's size, an inside label runs to. */
+    private insideGlyphs;
+    /**
+     * Font size of an inside label's leading line: what the theme asked for,
+     * shrunk if that wouldn't fit inside its wedge. **One size across every inside
+     * label** — the smallest any of them needs — because labels at mismatched
+     * sizes read as a mistake rather than as emphasis.
+     *
+     * So the theme's `insideStyle.fontSize` is an upper bound, not a promise: ask
+     * for the size the chart wants and the ring keeps it legal.
+     */
+    private get insideFont();
+    /** Whether the hole carries a summary at all. */
+    private get hasCenterLabel();
+    /**
+     * Font size of the hole's summary: the configured size, capped so it still
+     * fits across the hole. The cap matters because the hole's radius derives from
+     * the box, so a chart that reflows smaller would otherwise push its summary out
+     * through the ring.
+     */
+    private get centerFont();
+    /** Rim radius of a fully selected slice as a multiple of the ring's, clamped sane. */
+    private get growFactor();
+    /** How far past the ring's rim a fully selected slice reaches, in px. */
+    private get maxPop();
+    /** Height of one **leader** label block, in px — the unit those columns are spaced by. */
+    private get labelRowHeight();
+    /** Widest line, in glyphs, that a leader label for slice `index` can run to. */
+    private captionGlyphs;
+    /**
+     * Horizontal room reserved on each side for the leaders and their labels, in
+     * px — measured **per side**, from the slices that actually leader out that
+     * way. A ring whose labels are all inside reserves nothing and draws bigger.
+     *
+     * Excludes the ring's own selection-growth allowance, which scales with the
+     * radius and so is divided out in {@link outerRadius} instead.
+     */
+    private get labelGutters();
+    /**
+     * How far the ring's centre sits from the node's, in px. Zero while the
+     * gutters match; when the labels all fall one way it slides the ring into the
+     * empty half so the ring-plus-labels group stays centred in the box instead of
+     * the ring sitting dead centre with a bald patch beside it.
+     */
+    private get centerX();
+    /**
+     * Radius of the ring's outer edge, fitted to whatever the label gutters leave.
+     * A fully selected slice reaches `radius × growFactor`, so the room has to
+     * cover that — hence the divisor, which keeps even the grown slice inside the
+     * box (and holds the ring the same size whether or not anything is selected).
+     */
+    private get outerRadius();
+    /** Radius of the hole in the middle: a fraction of the outer radius, or explicit px. */
+    private get holeRadius();
+    /** Radius of the circle every leader elbows on, clear of even a popped-out slice. */
+    private get elbowRadius();
+    /** How far slice `index` is currently pushed out, in `[0, 1]`. */
+    private popOf;
+    /** Radius of slice `index`'s outer edge, its selection growth included. */
+    private anchorRadius;
+    /**
+     * Radius an inside label sits at on slice `index`: halfway across the band on a
+     * donut, and further out than halfway on a solid pie, where "halfway" would
+     * crowd the point every wedge converges on. Rides the slice's own pop, so an
+     * inside label travels out with the wedge it belongs to.
+     */
+    private bandMidRadius;
+    /** Node2D-space point slice `index`'s inside label is centred on. */
+    private insideAnchor;
+    /**
+     * How selected the ring is overall, in `[0, 1]` — the most-grown slice. Rides
+     * the same tween the pops do, so the dim below arrives with the growth rather
+     * than needing an animation of its own.
+     */
+    private get selectionStrength();
+    /**
+     * Opacity slice `index` (and its leader and label) is drawn at: full while
+     * nothing is selected, falling toward {@link dimOpacity} in proportion to how
+     * selected the *rest* of the ring is. A slice that's selected itself stays at
+     * full — the two factors cancel.
+     */
+    private sliceOpacity;
+    /**
+     * Where every leader label sits and how its leader gets there. Labels are split
+     * into a right and a left column by their slice's bisector, each column is
+     * spread so nothing overlaps (and nothing leaves the box), and each leader is
+     * then built as wedge edge → elbow → label. The elbow rides the leader circle at
+     * the label's *settled* y, which keeps the final run horizontal and the whole
+     * polyline outside the ring however far the label was nudged.
+     */
+    private placements;
+    /** This frame's placement for slice `index`, or `undefined` if it isn't leadered. */
+    private placementFor;
+    /**
+     * The ring's paints live nowhere `ShapeNode` would look: one fill per slice,
+     * resolved once into {@link fills}, plus the leader line's own stroke. Both are
+     * passed explicitly — see {@link declarePaints}.
+     */
+    declareAssets(assets: AssetScope): void;
+    protected renderSelf(ctx: RenderContext2D): void;
+    /** Tween {@link growth} `0 → 1`, wiping the wedges in around the ring. */
+    sweep(args: CommandArgs<Record<string, never>> & {
+        duration: number;
+    }): Command<RingSweep>;
+    /** Tween {@link labelReveal} `0 → 1`, fading the leaders and captions up. */
+    revealLabels(args: CommandArgs<Record<string, never>> & {
+        duration: number;
+    }): Command<RingLabels>;
+    /**
+     * Fade the hole's summary up. Deliberately not part of the ring's entrance: a
+     * hole label is usually the chart's conclusion, so the scene decides when it
+     * lands.
+     */
+    revealCenter(args?: CommandArgs<Record<string, never>> & {
+        duration?: number;
+    }): Command<RingCenter>;
+}
+/** The signals the ring's own commands move, as props types. */
+type RingSweep = {
+    growth: number;
+};
+type RingLabels = {
+    labelReveal: number;
+};
+type RingCenter = {
+    centerReveal: number;
+};
+export {};
+//# sourceMappingURL=pie-ring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pie-ring.d.ts","sourceRoot":"","sources":["../../src/pie-chart/pie-ring.ts"],"names":[],"mappings":"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"}