@motionscript/charts 0.1.0-alpha.3 → 0.1.0-alpha.5

package/src/line-chart/chart-line.ts

@@ -1,208 +1,208 @@
-import {
-  type AssetScope,
-  Graphics2D,
-  Node2D,
-  command,
-  easeOut,
-  strokeOps,
-  property,
-  type Command,
-  type CommandArgs,
-  type EasingFunction,
-  type Node2DProps,
-  type RenderContext2D,
-  type Stroke,
-  type StrokeResolved,
-  type Vector2,
-} from "@motionscript/sdk"
-
-import { SPOTLIGHT_DIM } from "../kit/shared"
-import {
-  EMPTY_REGION_BOX,
-  clipPolylineToBox,
-  hasRegion,
-  type RegionBox,
-} from "./shared"
-import { declarePaints } from "@motionscript/sdk/component"
-
-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 class ChartLine extends Node2D<ChartLineProps> {
-  @property({ default: () => [] as Vector2[] }) declare points: Vector2[]
-  @property({ default: [], mapper: strokeOps.resolve, tween: strokeOps.lerp })
-  declare stroke: Stroke
-  @property({ default: 1 }) declare progress: number
-  @property({ default: true }) declare enabled: boolean
-  @property({ default: () => EMPTY_REGION_BOX }) declare spotlight: RegionBox
-  @property({ default: SPOTLIGHT_DIM }) declare dimOpacity: number
-
-  /**
-   * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
-   * paint props it carries — see {@link declarePaints}.
-   */
-  override declareAssets(assets: AssetScope): void {
-    super.declareAssets(assets)
-    declarePaints(this, assets)
-  }
-
-  protected renderSelf(ctx: RenderContext2D): void {
-    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 as StrokeResolved[]
-    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.
-   */
-  private tracePoints(pts: Vector2[], p: number): Vector2[] {
-    if (p >= 1 || pts.length < 2) return pts
-    if (p <= 0) return []
-
-    const segLen: number[] = []
-    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: Vector2[] = [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.
-   */
-  @command()
-  enter(args: CommandArgs<Record<string, never>> & { duration: number }): Command<ChartLineProps> {
-    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: number,
-    duration: number,
-    easing: EasingFunction = easeOut(),
-    to = 1
-  ): Command<ChartLineProps> {
-    return this.command<ChartLineProps>(
-      (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
-    )
-  }
-}
+import {
+  type AssetScope,
+  Graphics2D,
+  Node2D,
+  command,
+  easeOut,
+  strokeOps,
+  property,
+  type Command,
+  type CommandArgs,
+  type EasingFunction,
+  type Node2DProps,
+  type RenderContext2D,
+  type Stroke,
+  type StrokeResolved,
+  type Vector2,
+} from "@motionscript/sdk"
+
+import { SPOTLIGHT_DIM } from "../kit/shared"
+import {
+  EMPTY_REGION_BOX,
+  clipPolylineToBox,
+  hasRegion,
+  type RegionBox,
+} from "./shared"
+import { declarePaints } from "@motionscript/sdk/component"
+
+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 an
+   * editor 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 class ChartLine extends Node2D<ChartLineProps> {
+  @property({ default: () => [] as Vector2[] }) declare points: Vector2[]
+  @property({ default: [], mapper: strokeOps.resolve, tween: strokeOps.lerp })
+  declare stroke: Stroke
+  @property({ default: 1 }) declare progress: number
+  @property({ default: true }) declare enabled: boolean
+  @property({ default: () => EMPTY_REGION_BOX }) declare spotlight: RegionBox
+  @property({ default: SPOTLIGHT_DIM }) declare dimOpacity: number
+
+  /**
+   * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
+   * paint props it carries — see {@link declarePaints}.
+   */
+  override declareAssets(assets: AssetScope): void {
+    super.declareAssets(assets)
+    declarePaints(this, assets)
+  }
+
+  protected renderSelf(ctx: RenderContext2D): void {
+    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 as StrokeResolved[]
+    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.
+   */
+  private tracePoints(pts: Vector2[], p: number): Vector2[] {
+    if (p >= 1 || pts.length < 2) return pts
+    if (p <= 0) return []
+
+    const segLen: number[] = []
+    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: Vector2[] = [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.
+   */
+  @command()
+  enter(args: CommandArgs<Record<string, never>> & { duration: number }): Command<ChartLineProps> {
+    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: number,
+    duration: number,
+    easing: EasingFunction = easeOut(),
+    to = 1
+  ): Command<ChartLineProps> {
+    return this.command<ChartLineProps>(
+      (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
+    )
+  }
+}