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

package/dist/kit/vertical-axis.js

@@ -0,0 +1,176 @@
+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, Node2D, Rect, RotatedBox, Text, easeOut, property, insetsOps, textOps, } from "@motionscript/core";
+import { DEFAULT_Y_AXIS, enterBudget, formatMarker, } from "./shared.js";
+import { at, compose } from "@motionscript/core/component";
+/** How far a marker starts to the right of its slot when it enters, in px. */
+const SLIDE = 24;
+/**
+ * The numeric vertical axis shared by the cartesian charts: a **column of
+ * {@link Text} nodes**, one per marker value, running top-to-bottom (highest
+ * value at the top). Pure layout — no `Graphics` — so the markers are real text
+ * nodes the scene can measure, restyle, or animate individually.
+ *
+ * Each marker is positioned so its centre lands exactly on its value's fraction
+ * across `range` within the axis's filled height, so unevenly-spaced markers
+ * land where their values fall. Both the caption and the position are *bound*,
+ * not snapshotted: a chart that rescales its axes (see `LineChart.zoomTo`)
+ * tweens `range`/`markers` live. Only the marker **count** is fixed at
+ * construction.
+ *
+ * {@link enter} staggers them in **bottom-to-top**: each marker starts pushed a
+ * little to the right and transparent, then fades and slides left into place.
+ * The resting state is the landed one, so a chart that is never told to enter
+ * still reads as a finished chart.
+ */
+export class VerticalAxis extends Node2D {
+    /**
+     * How a tick value is captioned. Defaults to the bare numeric reading; a
+     * chart with a number format on this axis replaces it (see `number-format`).
+     *
+     * A plain field rather than a `@property`, for the reason the horizontal
+     * axis's twin spells out: it is a policy, not a value, and there is nothing
+     * to tween between two formatters.
+     */
+    labelFor = formatMarker;
+    /** One text node per marker, ordered top → bottom, for the staggered enter. */
+    markerNodes = [];
+    /** The caption node, or null when `label` is empty. Entered after the markers. */
+    labelNode = null;
+    /** The live tick values, top → bottom (highest first) — re-read every frame. */
+    get sortedMarkers() {
+        return [...this.markers].sort((a, b) => b - a);
+    }
+    /**
+     * Tick `i`'s value, or `undefined` once the live `markers` list is shorter
+     * than the column of text nodes built for it — a slot with no value renders as
+     * empty text rather than repeating its neighbour.
+     */
+    valueAt(index) {
+        return this.sortedMarkers[index];
+    }
+    /** Tick `i`'s fraction across the live `range`, 0 at the bottom edge. */
+    fracAt(index) {
+        const v = this.valueAt(index);
+        if (v === undefined)
+            return 0;
+        const [min, max] = this.range;
+        return max <= min ? 0 : (v - min) / (max - min);
+    }
+    constructor(props) {
+        super(props);
+        // Composed from plain props (range/markers/label) — no context needed, so
+        // it's built here. super() applied the props, so the reads below resolve.
+        const tickPad = insetsOps.resolve(this.axis.tickPadding).right;
+        const titlePad = insetsOps.resolve(this.axis.titlePadding).right;
+        this.markerNodes = this.markers.map((_, i) => {
+            const marker = new Text({
+                ...textOps.styleProps(this.axis.labelStyle),
+                text: () => {
+                    const v = this.valueAt(i);
+                    return v === undefined ? "" : this.labelFor(v);
+                },
+                y: () => {
+                    // Node2D space is y-up, so the fraction runs from the bottom.
+                    const height = this.layoutBounds.height;
+                    const centred = (this.fracAt(i) - 0.5) * height;
+                    // Held inside the axis's top edge — the backstop for a chart whose
+                    // headroom is smaller than its marker text is tall, which a theme with
+                    // much larger markers can arrange. Only the top, because what lies
+                    // below the axis is the chart's own horizontal axis and legend.
+                    const limit = height / 2 - marker.layoutBounds.height / 2;
+                    return Math.min(centred, limit);
+                },
+            });
+            return marker;
+        });
+        const children = [];
+        if (this.label !== "") {
+            this.labelNode = new Text({
+                ...textOps.styleProps(this.axis.titleStyle),
+                text: this.label,
+            });
+            // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
+            children.push(new RotatedBox({
+                angle: -90,
+                width: "hug",
+                height: "hug",
+                children: this.labelNode,
+            }));
+        }
+        children.push(new Rect({
+            height: "fill",
+            width: "hug",
+            padding: { right: tickPad },
+            children: this.markerNodes,
+        }));
+        this.add(new Rect({ flow: "horizontal", gap: titlePad, children }));
+    }
+    /**
+     * Primes every marker (and the caption) 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.
+     */
+    arm(slide = SLIDE) {
+        for (const marker of this.markerNodes)
+            marker.set({ opacity: 0, x: slide });
+        this.labelNode?.set({ opacity: 0, x: slide });
+    }
+    /**
+     * Stagger the markers in bottom to top, then slide the caption in from the
+     * right after them.
+     *
+     * A {@link Seekable} rather than a generator — see the note on the horizontal
+     * axis's `enter`. The offsets were always static; expressing them as `wait`
+     * inside a generator is what made them reachable only by running it.
+     *
+     * `args.duration` is the **whole** entrance, not one marker's slide: the
+     * stagger and the caption are carved out of it rather than added on top. See
+     * {@link enterBudget} for why that distinction matters here.
+     *
+     * `args.data.stagger` is seconds between successive markers (derived when
+     * omitted); `args.data.slide` is the starting rightward offset in px.
+     */
+    enter(args) {
+        const { stagger, slide = SLIDE } = args.data ?? {};
+        const easing = args.easing ?? easeOut();
+        const nodes = this.markerNodes;
+        if (nodes.length === 0)
+            return compose([]);
+        const { step, per, caption } = enterBudget(args.duration, nodes.length, this.labelNode !== null, stagger);
+        this.arm(slide);
+        // Bottom marker leads: markerNodes is top → bottom, so walk it in reverse.
+        const markers = nodes.map((node, i) => {
+            const order = nodes.length - 1 - i; // bottom-most = 0
+            return at(order * step, node.to({ data: { opacity: 1, x: 0 }, duration: per, easing }));
+        });
+        const lastMarkerEnds = (nodes.length - 1) * step + per;
+        // Once every marker has landed, the caption slides in from the right.
+        return compose([
+            ...markers,
+            ...(this.labelNode
+                ? [at(lastMarkerEnds, this.labelNode.to({ data: { opacity: 1, x: 0 }, duration: caption, easing }))]
+                : []),
+        ]);
+    }
+}
+__decorate([
+    property({ default: () => [0, 1] })
+], VerticalAxis.prototype, "range", void 0);
+__decorate([
+    property({ default: () => [] })
+], VerticalAxis.prototype, "markers", void 0);
+__decorate([
+    property({ default: DEFAULT_Y_AXIS })
+], VerticalAxis.prototype, "axis", void 0);
+__decorate([
+    property({ default: "" })
+], VerticalAxis.prototype, "label", void 0);
+__decorate([
+    command()
+], VerticalAxis.prototype, "enter", null);
+//# sourceMappingURL=vertical-axis.js.map

package/dist/kit/vertical-axis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertical-axis.js","sourceRoot":"","sources":["../../src/kit/vertical-axis.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  command,\n  Node2D,\n  Rect,\n  RotatedBox,\n  Text,\n  easeOut,\n  property,\n  insetsOps,\n  textOps,\n  type CommandArgs,\n  type NodeConfig,\n  type Node2DProps,\n} from \"@motionscript/core\"\n\nimport {\n  DEFAULT_Y_AXIS,\n  enterBudget,\n  formatMarker,\n  type AxisConfig,\n  type Range,\n} from \"./shared\"\nimport { at, compose, type Seekable } from \"@motionscript/core/component\"\n\nexport interface VerticalAxisProps extends Node2DProps {\n  /** `[min, max]` of the vertical scale the markers are positioned within. */\n  range: Range\n  /**\n   * Tick values (in data units) to draw up the axis, each placed by its fraction\n   * across {@link VerticalAxisProps.range}. Need not be evenly spaced or include\n   * the ends.\n   */\n  markers: number[]\n  /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */\n  axis: AxisConfig\n  /**\n   * Rotated caption drawn in the gutter to the left of the marker column. Empty\n   * string (the default) hides it — no caption node is built and no label gutter\n   * is reserved.\n   */\n  label: string\n}\n\n/** How far a marker starts to the right of its slot when it enters, in px. */\nconst SLIDE = 24\n\n/** How a tick value is captioned — see {@link VerticalAxis.labelFor}. */\nexport type MarkerLabel = (value: number) => string\n\n/**\n * The numeric vertical axis shared by the cartesian charts: a **column of\n * {@link Text} nodes**, one per marker value, running top-to-bottom (highest\n * value at the top). Pure layout — no `Graphics` — so the markers are real text\n * nodes the scene can measure, restyle, or animate individually.\n *\n * Each marker is positioned so its centre lands exactly on its value's fraction\n * across `range` within the axis's filled height, so unevenly-spaced markers\n * land where their values fall. Both the caption and the position are *bound*,\n * not snapshotted: a chart that rescales its axes (see `LineChart.zoomTo`)\n * tweens `range`/`markers` live. Only the marker **count** is fixed at\n * construction.\n *\n * {@link enter} staggers them in **bottom-to-top**: each marker starts pushed a\n * little to the right and transparent, then fades and slides left into place.\n * The resting state is the landed one, so a chart that is never told to enter\n * still reads as a finished chart.\n */\nexport class VerticalAxis extends Node2D<VerticalAxisProps> {\n  @property({ default: () => [0, 1] as Range }) declare range: Range\n  @property({ default: () => [] as number[] }) declare markers: number[]\n  @property({ default: DEFAULT_Y_AXIS }) declare axis: AxisConfig\n  @property({ default: \"\" }) declare label: string\n\n  /**\n   * How a tick value is captioned. Defaults to the bare numeric reading; a\n   * chart with a number format on this axis replaces it (see `number-format`).\n   *\n   * A plain field rather than a `@property`, for the reason the horizontal\n   * axis's twin spells out: it is a policy, not a value, and there is nothing\n   * to tween between two formatters.\n   */\n  labelFor: MarkerLabel = formatMarker\n\n  /** One text node per marker, ordered top → bottom, for the staggered enter. */\n  private markerNodes: Text[] = []\n  /** The caption node, or null when `label` is empty. Entered after the markers. */\n  private labelNode: Text | null = null\n\n  /** The live tick values, top → bottom (highest first) — re-read every frame. */\n  private get sortedMarkers(): number[] {\n    return [...this.markers].sort((a, b) => b - a)\n  }\n\n  /**\n   * Tick `i`'s value, or `undefined` once the live `markers` list is shorter\n   * than the column of text nodes built for it — a slot with no value renders as\n   * empty text rather than repeating its neighbour.\n   */\n  private valueAt(index: number): number | undefined {\n    return this.sortedMarkers[index]\n  }\n\n  /** Tick `i`'s fraction across the live `range`, 0 at the bottom edge. */\n  private fracAt(index: number): number {\n    const v = this.valueAt(index)\n    if (v === undefined) return 0\n    const [min, max] = this.range\n    return max <= min ? 0 : (v - min) / (max - min)\n  }\n\n  constructor(props?: NodeConfig<VerticalAxis, VerticalAxisProps>) {\n    super(props)\n\n    // Composed from plain props (range/markers/label) — no context needed, so\n    // it's built here. super() applied the props, so the reads below resolve.\n    const tickPad = insetsOps.resolve(this.axis.tickPadding).right\n    const titlePad = insetsOps.resolve(this.axis.titlePadding).right\n\n    this.markerNodes = this.markers.map((_, i) => {\n      const marker: Text = new Text({\n        ...textOps.styleProps(this.axis.labelStyle),\n        text: () => {\n          const v = this.valueAt(i)\n          return v === undefined ? \"\" : this.labelFor(v)\n        },\n        y: () => {\n          // Node2D space is y-up, so the fraction runs from the bottom.\n          const height = this.layoutBounds.height\n          const centred = (this.fracAt(i) - 0.5) * height\n          // Held inside the axis's top edge — the backstop for a chart whose\n          // headroom is smaller than its marker text is tall, which a theme with\n          // much larger markers can arrange. Only the top, because what lies\n          // below the axis is the chart's own horizontal axis and legend.\n          const limit = height / 2 - marker.layoutBounds.height / 2\n          return Math.min(centred, limit)\n        },\n      })\n      return marker\n    })\n\n    const children: Node2D[] = []\n    if (this.label !== \"\") {\n      this.labelNode = new Text({\n        ...textOps.styleProps(this.axis.titleStyle),\n        text: this.label,\n      })\n      // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.\n      children.push(\n        new RotatedBox({\n          angle: -90,\n          width: \"hug\",\n          height: \"hug\",\n          children: this.labelNode,\n        })\n      )\n    }\n    children.push(\n      new Rect({\n        height: \"fill\",\n        width: \"hug\",\n        padding: { right: tickPad },\n        children: this.markerNodes,\n      })\n    )\n\n    this.add(new Rect({ flow: \"horizontal\", gap: titlePad, children }))\n  }\n\n  /**\n   * Primes every marker (and the caption) at its pre-entrance state: shifted\n   * right and transparent. Idempotent, and separate from {@link enter} so the\n   * chart can arm its whole composition before the first frame is drawn.\n   */\n  arm(slide = SLIDE): void {\n    for (const marker of this.markerNodes) marker.set({ opacity: 0, x: slide })\n    this.labelNode?.set({ opacity: 0, x: slide })\n  }\n\n  /**\n   * Stagger the markers in bottom to top, then slide the caption in from the\n   * right after them.\n   *\n   * A {@link Seekable} rather than a generator — see the note on the horizontal\n   * axis's `enter`. The offsets were always static; expressing them as `wait`\n   * inside a generator is what made them reachable only by running it.\n   *\n   * `args.duration` is the **whole** entrance, not one marker's slide: the\n   * stagger and the caption are carved out of it rather than added on top. See\n   * {@link enterBudget} for why that distinction matters here.\n   *\n   * `args.data.stagger` is seconds between successive markers (derived when\n   * omitted); `args.data.slide` is the starting rightward offset in px.\n   */\n  @command()\n  enter(args: CommandArgs<{ stagger?: number; slide?: number }> & { duration: number }): Seekable {\n    const { stagger, slide = SLIDE } = args.data ?? {}\n    const easing = args.easing ?? easeOut()\n    const nodes = this.markerNodes\n    if (nodes.length === 0) return compose([])\n    const { step, per, caption } = enterBudget(\n      args.duration,\n      nodes.length,\n      this.labelNode !== null,\n      stagger\n    )\n\n    this.arm(slide)\n\n    // Bottom marker leads: markerNodes is top → bottom, so walk it in reverse.\n    const markers = nodes.map((node, i) => {\n      const order = nodes.length - 1 - i // bottom-most = 0\n      return at(order * step, node.to({ data: { opacity: 1, x: 0 }, duration: per, easing }))\n    })\n    const lastMarkerEnds = (nodes.length - 1) * step + per\n\n    // Once every marker has landed, the caption slides in from the right.\n    return compose([\n      ...markers,\n      ...(this.labelNode\n        ? [at(lastMarkerEnds, this.labelNode.to({ data: { opacity: 1, x: 0 }, duration: caption, easing }))]\n        : []),\n    ])\n  }\n}\n"]}

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

@@ -0,0 +1,91 @@
+import { type AssetScope, Node2D, type Command, type CommandArgs, type EasingFunction, type Node2DProps, type RenderContext2D, type Stroke, type Vector2 } from "@motionscript/core";
+import { type RegionBox } from "./shared.js";
+export interface ChartLineProps extends Node2DProps {
+    /**
+     * The series polyline, already mapped into this node's local pixel space
+     * (origin at centre, y-up) by the parent {@link LineChart}. Ordered along x.
+     */
+    points: Vector2[];
+    /** Line colour + weight (+ optional dash/cap/join) — the per-series stroke. */
+    stroke: Stroke;
+    /**
+     * Reveal of the line in `[0, 1]`: 0 hides it, 1 traces it fully from its left
+     * end to its right.
+     *
+     * Defaults to **1**, unlike the standalone chart this was ported from: in the
+     * studio a node's resting state is what the paused editor canvas paints, so a
+     * chart that only appeared once a command had run would edit blind. {@link
+     * enter} drives it from 0 regardless of where it rests, so the animation is
+     * unchanged.
+     */
+    progress: number;
+    /**
+     * Whether this line is drawn at all. `false` hides it outright — the switch
+     * the chart flips alongside its legend's per-series toggle.
+     */
+    enabled: boolean;
+    /**
+     * A slice of the plot to spotlight, in this node's own pixel space. When set
+     * to a real box, the stretches of the line *outside* it drop to
+     * {@link ChartLineProps.dimOpacity} while the stretches inside stay full.
+     */
+    spotlight: RegionBox;
+    /** Opacity the out-of-region stretches fade to. */
+    dimOpacity: number;
+}
+/**
+ * A single series line of a {@link LineChart}: one rounded polyline traced
+ * through pre-mapped pixel `points`, drawn as one {@link Graphics2D} command list.
+ * Sized and positioned by the parent, which shares the plot's coordinate frame.
+ *
+ * Two signals drive it: {@link ChartLineProps.progress} traces the line in
+ * (animated by {@link enter}) and `enabled` shows or hides it wholesale.
+ */
+export declare class ChartLine extends Node2D<ChartLineProps> {
+    points: Vector2[];
+    stroke: Stroke;
+    progress: number;
+    enabled: boolean;
+    spotlight: RegionBox;
+    dimOpacity: number;
+    /**
+     * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
+     * paint props it carries — see {@link declarePaints}.
+     */
+    declareAssets(assets: AssetScope): void;
+    protected renderSelf(ctx: RenderContext2D): void;
+    /**
+     * The prefix of `pts` revealed at fraction `p ∈ [0, 1]`, measuring the reveal
+     * by *cumulative arc length* so the line traces at a steady pace regardless of
+     * uneven point spacing. Returns the whole-point prefix plus one interpolated
+     * point partway along the active segment.
+     */
+    private tracePoints;
+    /**
+     * Trace the line in from its left end to its right over `duration` seconds.
+     * Drives `progress` `0 → 1`.
+     *
+     * A `Command` rather than a generator, so the trace can be *evaluated* at a
+     * time instead of run to one — which is what lets a scene containing this
+     * chart be scrubbed in constant time. It no longer needs to prime `progress`
+     * to 0 first: the value at `t` is a function of `t`, so a repeat call re-traces
+     * by definition rather than by having reset something.
+     */
+    enter(args: CommandArgs<Record<string, never>> & {
+        duration: number;
+    }): Command<ChartLineProps>;
+    /**
+     * The trace, with both ends stated: `progress` runs `from` → `to`.
+     *
+     * What {@link LineChart.showSeries} and `hideSeries` are both made of — they
+     * are the same motion in opposite directions, and expressing them as one thing
+     * with endpoints is what stops the pair drifting apart.
+     *
+     * `enabled` rides along in the same value rather than being set before or after
+     * the command. A line is drawable for every `t` the trace covers and undrawn
+     * outside it, which is what makes arriving at a time backwards show what
+     * arriving forwards does — a flag flipped by a side effect would not.
+     */
+    enterFrom(from: number, duration: number, easing?: EasingFunction, to?: number): Command<ChartLineProps>;
+}
+//# sourceMappingURL=chart-line.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chart-line.d.ts","sourceRoot":"","sources":["../../src/line-chart/chart-line.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EAEf,MAAM,EAKN,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,MAAM,EAEX,KAAK,OAAO,EACb,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,UAAU,CAAA;AAGjB,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD;;;OAGG;IACH,MAAM,EAAE,OAAO,EAAE,CAAA;IACjB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;;OASG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,MAAM,CAAC,cAAc,CAAC;IACG,MAAM,EAAE,OAAO,EAAE,CAAA;IAE/D,MAAM,EAAE,MAAM,CAAA;IACY,QAAQ,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IACE,SAAS,EAAE,SAAS,CAAA;IAC7B,UAAU,EAAE,MAAM,CAAA;IAEhE;;;OAGG;IACM,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAKhD,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAuChD;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IA+BnB;;;;;;;;;OASG;IAEH,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAI/F;;;;;;;;;;;OAWG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,cAA0B,EAClC,EAAE,SAAI,GACL,OAAO,CAAC,cAAc,CAAC;CAY3B"}

package/dist/line-chart/chart-line.js

@@ -0,0 +1,156 @@
+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 { Graphics2D, Node2D, command, easeOut, strokeOps, property, } from "@motionscript/core";
+import { SPOTLIGHT_DIM } from "../kit/shared.js";
+import { EMPTY_REGION_BOX, clipPolylineToBox, hasRegion, } from "./shared.js";
+import { declarePaints } from "@motionscript/core/component";
+/**
+ * A single series line of a {@link LineChart}: one rounded polyline traced
+ * through pre-mapped pixel `points`, drawn as one {@link Graphics2D} command list.
+ * Sized and positioned by the parent, which shares the plot's coordinate frame.
+ *
+ * Two signals drive it: {@link ChartLineProps.progress} traces the line in
+ * (animated by {@link enter}) and `enabled` shows or hides it wholesale.
+ */
+export class ChartLine extends Node2D {
+    /**
+     * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
+     * paint props it carries — see {@link declarePaints}.
+     */
+    declareAssets(assets) {
+        super.declareAssets(assets);
+        declarePaints(this, assets);
+    }
+    renderSelf(ctx) {
+        if (!this.enabled)
+            return;
+        const pts = this.points;
+        if (pts.length < 2)
+            return;
+        const p = Math.max(0, Math.min(1, this.progress));
+        if (p <= 0)
+            return;
+        const drawn = this.tracePoints(pts, p);
+        if (drawn.length < 2)
+            return;
+        const stroke = this.stroke;
+        const radius = (stroke[0]?.weight ?? 0) * 2; // round the joins
+        const box = this.spotlight;
+        if (!hasRegion(box)) {
+            ctx.draw(new Graphics2D().line({ points: drawn, radius }).stroke(stroke));
+            return;
+        }
+        // Spotlit: the whole line goes down to `dimOpacity`, then the stretches
+        // inside the region are re-drawn over it at full strength. Two passes rather
+        // than one dim + one bright *complementary* pair, so the bright run has
+        // continuous geometry through the region and its joins round the way an
+        // unspotlit line's do — and so the boundary lands exactly on the region edge.
+        ctx.draw(new Graphics2D()
+            .line({ points: drawn, radius })
+            .stroke(stroke)
+            .opacity(Math.max(0, Math.min(1, this.dimOpacity))));
+        // One `draw` per run: shapes chained before a `stroke()` are combined into a
+        // single surface, and stroking a union of disjoint open paths doesn't paint
+        // — so a line that leaves the region and comes back would lose both halves.
+        for (const run of clipPolylineToBox(drawn, box)) {
+            ctx.draw(new Graphics2D().line({ points: run, radius }).stroke(stroke));
+        }
+    }
+    /**
+     * The prefix of `pts` revealed at fraction `p ∈ [0, 1]`, measuring the reveal
+     * by *cumulative arc length* so the line traces at a steady pace regardless of
+     * uneven point spacing. Returns the whole-point prefix plus one interpolated
+     * point partway along the active segment.
+     */
+    tracePoints(pts, p) {
+        if (p >= 1 || pts.length < 2)
+            return pts;
+        if (p <= 0)
+            return [];
+        const segLen = [];
+        let total = 0;
+        for (let i = 1; i < pts.length; i++) {
+            const d = Math.hypot(pts[i].x - pts[i - 1].x, pts[i].y - pts[i - 1].y);
+            segLen.push(d);
+            total += d;
+        }
+        if (total === 0)
+            return pts;
+        let target = total * p;
+        const out = [pts[0]];
+        for (let i = 0; i < segLen.length; i++) {
+            if (target >= segLen[i]) {
+                out.push(pts[i + 1]);
+                target -= segLen[i];
+            }
+            else {
+                const t = segLen[i] === 0 ? 0 : target / segLen[i];
+                out.push({
+                    x: pts[i].x + (pts[i + 1].x - pts[i].x) * t,
+                    y: pts[i].y + (pts[i + 1].y - pts[i].y) * t,
+                });
+                break;
+            }
+        }
+        return out;
+    }
+    /**
+     * Trace the line in from its left end to its right over `duration` seconds.
+     * Drives `progress` `0 → 1`.
+     *
+     * A `Command` rather than a generator, so the trace can be *evaluated* at a
+     * time instead of run to one — which is what lets a scene containing this
+     * chart be scrubbed in constant time. It no longer needs to prime `progress`
+     * to 0 first: the value at `t` is a function of `t`, so a repeat call re-traces
+     * by definition rather than by having reset something.
+     */
+    enter(args) {
+        return this.enterFrom(0, args.duration, args.easing ?? easeOut());
+    }
+    /**
+     * The trace, with both ends stated: `progress` runs `from` → `to`.
+     *
+     * What {@link LineChart.showSeries} and `hideSeries` are both made of — they
+     * are the same motion in opposite directions, and expressing them as one thing
+     * with endpoints is what stops the pair drifting apart.
+     *
+     * `enabled` rides along in the same value rather than being set before or after
+     * the command. A line is drawable for every `t` the trace covers and undrawn
+     * outside it, which is what makes arriving at a time backwards show what
+     * arriving forwards does — a flag flipped by a side effect would not.
+     */
+    enterFrom(from, duration, easing = easeOut(), to = 1) {
+        return this.command((t) => {
+            const progress = from + (to - from) * t;
+            // Hidden only once it has fully retraced, so the last frame of a hide is
+            // the empty plot rather than a line that vanished a frame early.
+            return { progress, enabled: progress > 0 };
+        }, duration, easing);
+    }
+}
+__decorate([
+    property({ default: () => [] })
+], ChartLine.prototype, "points", void 0);
+__decorate([
+    property({ default: [], mapper: strokeOps.resolve, tween: strokeOps.lerp })
+], ChartLine.prototype, "stroke", void 0);
+__decorate([
+    property({ default: 1 })
+], ChartLine.prototype, "progress", void 0);
+__decorate([
+    property({ default: true })
+], ChartLine.prototype, "enabled", void 0);
+__decorate([
+    property({ default: () => EMPTY_REGION_BOX })
+], ChartLine.prototype, "spotlight", void 0);
+__decorate([
+    property({ default: SPOTLIGHT_DIM })
+], ChartLine.prototype, "dimOpacity", void 0);
+__decorate([
+    command()
+], ChartLine.prototype, "enter", null);
+//# sourceMappingURL=chart-line.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chart-line.js","sourceRoot":"","sources":["../../src/line-chart/chart-line.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type AssetScope,\n  Graphics2D,\n  Node2D,\n  command,\n  easeOut,\n  strokeOps,\n  property,\n  type Command,\n  type CommandArgs,\n  type EasingFunction,\n  type Node2DProps,\n  type RenderContext2D,\n  type Stroke,\n  type StrokeResolved,\n  type Vector2,\n} from \"@motionscript/core\"\n\nimport { SPOTLIGHT_DIM } from \"../kit/shared\"\nimport {\n  EMPTY_REGION_BOX,\n  clipPolylineToBox,\n  hasRegion,\n  type RegionBox,\n} from \"./shared\"\nimport { declarePaints } from \"@motionscript/core/component\"\n\nexport interface ChartLineProps extends Node2DProps {\n  /**\n   * The series polyline, already mapped into this node's local pixel space\n   * (origin at centre, y-up) by the parent {@link LineChart}. Ordered along x.\n   */\n  points: Vector2[]\n  /** Line colour + weight (+ optional dash/cap/join) — the per-series stroke. */\n  stroke: Stroke\n  /**\n   * Reveal of the line in `[0, 1]`: 0 hides it, 1 traces it fully from its left\n   * end to its right.\n   *\n   * Defaults to **1**, unlike the standalone chart this was ported from: in the\n   * studio a node's resting state is what the paused editor canvas paints, so a\n   * chart that only appeared once a command had run would edit blind. {@link\n   * enter} drives it from 0 regardless of where it rests, so the animation is\n   * unchanged.\n   */\n  progress: number\n  /**\n   * Whether this line is drawn at all. `false` hides it outright — the switch\n   * the chart flips alongside its legend's per-series toggle.\n   */\n  enabled: boolean\n  /**\n   * A slice of the plot to spotlight, in this node's own pixel space. When set\n   * to a real box, the stretches of the line *outside* it drop to\n   * {@link ChartLineProps.dimOpacity} while the stretches inside stay full.\n   */\n  spotlight: RegionBox\n  /** Opacity the out-of-region stretches fade to. */\n  dimOpacity: number\n}\n\n/**\n * A single series line of a {@link LineChart}: one rounded polyline traced\n * through pre-mapped pixel `points`, drawn as one {@link Graphics2D} command list.\n * Sized and positioned by the parent, which shares the plot's coordinate frame.\n *\n * Two signals drive it: {@link ChartLineProps.progress} traces the line in\n * (animated by {@link enter}) and `enabled` shows or hides it wholesale.\n */\nexport class ChartLine extends Node2D<ChartLineProps> {\n  @property({ default: () => [] as Vector2[] }) declare points: Vector2[]\n  @property({ default: [], mapper: strokeOps.resolve, tween: strokeOps.lerp })\n  declare stroke: Stroke\n  @property({ default: 1 }) declare progress: number\n  @property({ default: true }) declare enabled: boolean\n  @property({ default: () => EMPTY_REGION_BOX }) declare spotlight: RegionBox\n  @property({ default: SPOTLIGHT_DIM }) declare dimOpacity: number\n\n  /**\n   * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the\n   * paint props it carries — see {@link declarePaints}.\n   */\n  override declareAssets(assets: AssetScope): void {\n    super.declareAssets(assets)\n    declarePaints(this, assets)\n  }\n\n  protected renderSelf(ctx: RenderContext2D): void {\n    if (!this.enabled) return\n    const pts = this.points\n    if (pts.length < 2) return\n\n    const p = Math.max(0, Math.min(1, this.progress))\n    if (p <= 0) return\n\n    const drawn = this.tracePoints(pts, p)\n    if (drawn.length < 2) return\n    const stroke = this.stroke as StrokeResolved[]\n    const radius = (stroke[0]?.weight ?? 0) * 2 // round the joins\n\n    const box = this.spotlight\n    if (!hasRegion(box)) {\n      ctx.draw(new Graphics2D().line({ points: drawn, radius }).stroke(stroke))\n      return\n    }\n\n    // Spotlit: the whole line goes down to `dimOpacity`, then the stretches\n    // inside the region are re-drawn over it at full strength. Two passes rather\n    // than one dim + one bright *complementary* pair, so the bright run has\n    // continuous geometry through the region and its joins round the way an\n    // unspotlit line's do — and so the boundary lands exactly on the region edge.\n    ctx.draw(\n      new Graphics2D()\n        .line({ points: drawn, radius })\n        .stroke(stroke)\n        .opacity(Math.max(0, Math.min(1, this.dimOpacity)))\n    )\n\n    // One `draw` per run: shapes chained before a `stroke()` are combined into a\n    // single surface, and stroking a union of disjoint open paths doesn't paint\n    // — so a line that leaves the region and comes back would lose both halves.\n    for (const run of clipPolylineToBox(drawn, box)) {\n      ctx.draw(new Graphics2D().line({ points: run, radius }).stroke(stroke))\n    }\n  }\n\n  /**\n   * The prefix of `pts` revealed at fraction `p ∈ [0, 1]`, measuring the reveal\n   * by *cumulative arc length* so the line traces at a steady pace regardless of\n   * uneven point spacing. Returns the whole-point prefix plus one interpolated\n   * point partway along the active segment.\n   */\n  private tracePoints(pts: Vector2[], p: number): Vector2[] {\n    if (p >= 1 || pts.length < 2) return pts\n    if (p <= 0) return []\n\n    const segLen: number[] = []\n    let total = 0\n    for (let i = 1; i < pts.length; i++) {\n      const d = Math.hypot(pts[i].x - pts[i - 1].x, pts[i].y - pts[i - 1].y)\n      segLen.push(d)\n      total += d\n    }\n    if (total === 0) return pts\n\n    let target = total * p\n    const out: Vector2[] = [pts[0]]\n    for (let i = 0; i < segLen.length; i++) {\n      if (target >= segLen[i]) {\n        out.push(pts[i + 1])\n        target -= segLen[i]\n      } else {\n        const t = segLen[i] === 0 ? 0 : target / segLen[i]\n        out.push({\n          x: pts[i].x + (pts[i + 1].x - pts[i].x) * t,\n          y: pts[i].y + (pts[i + 1].y - pts[i].y) * t,\n        })\n        break\n      }\n    }\n    return out\n  }\n\n  /**\n   * Trace the line in from its left end to its right over `duration` seconds.\n   * Drives `progress` `0 → 1`.\n   *\n   * A `Command` rather than a generator, so the trace can be *evaluated* at a\n   * time instead of run to one — which is what lets a scene containing this\n   * chart be scrubbed in constant time. It no longer needs to prime `progress`\n   * to 0 first: the value at `t` is a function of `t`, so a repeat call re-traces\n   * by definition rather than by having reset something.\n   */\n  @command()\n  enter(args: CommandArgs<Record<string, never>> & { duration: number }): Command<ChartLineProps> {\n    return this.enterFrom(0, args.duration, args.easing ?? easeOut())\n  }\n\n  /**\n   * The trace, with both ends stated: `progress` runs `from` → `to`.\n   *\n   * What {@link LineChart.showSeries} and `hideSeries` are both made of — they\n   * are the same motion in opposite directions, and expressing them as one thing\n   * with endpoints is what stops the pair drifting apart.\n   *\n   * `enabled` rides along in the same value rather than being set before or after\n   * the command. A line is drawable for every `t` the trace covers and undrawn\n   * outside it, which is what makes arriving at a time backwards show what\n   * arriving forwards does — a flag flipped by a side effect would not.\n   */\n  enterFrom(\n    from: number,\n    duration: number,\n    easing: EasingFunction = easeOut(),\n    to = 1\n  ): Command<ChartLineProps> {\n    return this.command<ChartLineProps>(\n      (t) => {\n        const progress = from + (to - from) * t\n        // Hidden only once it has fully retraced, so the last frame of a hide is\n        // the empty plot rather than a line that vanished a frame early.\n        return { progress, enabled: progress > 0 }\n      },\n      duration,\n      easing\n    )\n  }\n}\n"]}

package/dist/line-chart/chart-region.d.ts

@@ -0,0 +1,47 @@
+import { type AssetScope, Node2D, type Fill, type Node2DProps, type RenderContext2D, type Stroke } from "@motionscript/core";
+import { type RegionBox } from "./shared.js";
+export interface ChartRegionProps extends Node2DProps {
+    /**
+     * The highlighted slice, already resolved into this node's local pixel space
+     * (origin at centre, y-up) by the parent {@link LineChart}. A degenerate box
+     * draws nothing.
+     */
+    box: RegionBox;
+    /** Dashed rule marking each *bounded* edge of the box. */
+    stroke: Stroke;
+    /** Wash filling the box, under the series lines. */
+    fill: Fill;
+    /**
+     * Reveal of the annotation in `[0, 1]`: 0 hides it, 1 draws it fully. Driven
+     * by the chart's own `regionReveal`, so the rules and the series' dimming move
+     * as one.
+     */
+    reveal: number;
+}
+/**
+ * The **region call-out** of a {@link LineChart}: a washed rectangle over the
+ * plot with a dashed rule down each edge the author actually bounded. Sized and
+ * positioned entirely from the pre-mapped {@link ChartRegionProps.box} rather
+ * than its own `layoutBounds` — the box already carries the plot geometry.
+ *
+ * It draws only the *marking*; fading the series outside the region is
+ * {@link ChartLine}'s job (it clips its own polyline against the same box), so
+ * the two can't disagree about where the boundary is.
+ *
+ * Only bounded edges get a rule: a region given just an `x` range spans the full
+ * plot height, so its top and bottom edges are the plot's own border, not a data
+ * bound — drawing dashes there would assert a limit the author didn't set.
+ */
+export declare class ChartRegion extends Node2D<ChartRegionProps> {
+    box: RegionBox;
+    stroke: Stroke;
+    fill: Fill;
+    reveal: number;
+    /**
+     * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
+     * paint props it carries — see {@link declarePaints}.
+     */
+    declareAssets(assets: AssetScope): void;
+    protected renderSelf(ctx: RenderContext2D): void;
+}
+//# sourceMappingURL=chart-region.d.ts.map

package/dist/line-chart/chart-region.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-region.d.ts","sourceRoot":"","sources":["../../src/line-chart/chart-region.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EAEf,MAAM,EAIN,KAAK,IAAI,EAET,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,MAAM,EAEZ,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,UAAU,CAAA;AAGjB,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD;;;;OAIG;IACH,GAAG,EAAE,SAAS,CAAA;IACd,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,IAAI,EAAE,IAAI,CAAA;IACV;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,SAAQ,MAAM,CAAC,gBAAgB,CAAC;IACA,GAAG,EAAE,SAAS,CAAA;IAM7D,MAAM,EAAE,MAAM,CAAA;IAMd,IAAI,EAAE,IAAI,CAAA;IACgB,MAAM,EAAE,MAAM,CAAA;IAEhD;;;OAGG;IACM,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAKhD,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;CAqDjD"}

package/dist/line-chart/chart-region.js

@@ -0,0 +1,101 @@
+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 { Graphics2D, Node2D, fillOps, strokeOps, property, } from "@motionscript/core";
+import { DEFAULT_CHART_THEME, EMPTY_REGION_BOX, hasRegion, } from "./shared.js";
+import { declarePaints } from "@motionscript/core/component";
+/**
+ * The **region call-out** of a {@link LineChart}: a washed rectangle over the
+ * plot with a dashed rule down each edge the author actually bounded. Sized and
+ * positioned entirely from the pre-mapped {@link ChartRegionProps.box} rather
+ * than its own `layoutBounds` — the box already carries the plot geometry.
+ *
+ * It draws only the *marking*; fading the series outside the region is
+ * {@link ChartLine}'s job (it clips its own polyline against the same box), so
+ * the two can't disagree about where the boundary is.
+ *
+ * Only bounded edges get a rule: a region given just an `x` range spans the full
+ * plot height, so its top and bottom edges are the plot's own border, not a data
+ * bound — drawing dashes there would assert a limit the author didn't set.
+ */
+export class ChartRegion extends Node2D {
+    /**
+     * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
+     * paint props it carries — see {@link declarePaints}.
+     */
+    declareAssets(assets) {
+        super.declareAssets(assets);
+        declarePaints(this, assets);
+    }
+    renderSelf(ctx) {
+        const box = this.box;
+        if (!hasRegion(box))
+            return;
+        const r = Math.max(0, Math.min(1, this.reveal));
+        if (r <= 0)
+            return;
+        const width = box.right - box.left;
+        const height = box.top - box.bottom;
+        const cx = (box.left + box.right) / 2;
+        const cy = (box.bottom + box.top) / 2;
+        // Wash first, so the rules sit over their own tint.
+        const layers = this.fill;
+        if (layers.length > 0) {
+            ctx.draw(new Graphics2D()
+                .rect({ x: cx, y: cy, width, height })
+                .fill(this.fill)
+                .opacity(r));
+        }
+        // One rule per bounded edge, growing from the region's centre outward as
+        // `reveal` climbs — the same "trace it in" beat as the series lines.
+        const stroke = this.stroke;
+        if (stroke.length === 0)
+            return;
+        // One `draw` per rule rather than four line ops under a single paint:
+        // shapes chained before a `stroke()` are combined into one surface, and
+        // stroking a union of disjoint open paths doesn't paint.
+        const rule = (points) => ctx.draw(new Graphics2D().line({ points }).stroke(this.stroke).opacity(r));
+        if (box.xBounded) {
+            const half = (height / 2) * r;
+            for (const x of [box.left, box.right]) {
+                rule([
+                    { x, y: cy - half },
+                    { x, y: cy + half },
+                ]);
+            }
+        }
+        if (box.yBounded) {
+            const half = (width / 2) * r;
+            for (const y of [box.bottom, box.top]) {
+                rule([
+                    { x: cx - half, y },
+                    { x: cx + half, y },
+                ]);
+            }
+        }
+    }
+}
+__decorate([
+    property({ default: () => EMPTY_REGION_BOX })
+], ChartRegion.prototype, "box", void 0);
+__decorate([
+    property({
+        default: DEFAULT_CHART_THEME.region.stroke,
+        mapper: strokeOps.resolve,
+        tween: strokeOps.lerp,
+    })
+], ChartRegion.prototype, "stroke", void 0);
+__decorate([
+    property({
+        default: DEFAULT_CHART_THEME.region.fill,
+        mapper: fillOps.resolve,
+        tween: fillOps.lerp,
+    })
+], ChartRegion.prototype, "fill", void 0);
+__decorate([
+    property({ default: 0 })
+], ChartRegion.prototype, "reveal", void 0);
+//# sourceMappingURL=chart-region.js.map