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

package/src/kit/vertical-axis.ts

@@ -0,0 +1,224 @@
+import {
+  command,
+  Node2D,
+  Rect,
+  RotatedBox,
+  Text,
+  easeOut,
+  property,
+  insetsOps,
+  textOps,
+  type CommandArgs,
+  type NodeConfig,
+  type Node2DProps,
+} from "@motionscript/core"
+
+import {
+  DEFAULT_Y_AXIS,
+  enterBudget,
+  formatMarker,
+  type AxisConfig,
+  type Range,
+} from "./shared"
+import { at, compose, type Seekable } from "@motionscript/core/component"
+
+export interface VerticalAxisProps extends Node2DProps {
+  /** `[min, max]` of the vertical scale the markers are positioned within. */
+  range: Range
+  /**
+   * Tick values (in data units) to draw up the axis, each placed by its fraction
+   * across {@link VerticalAxisProps.range}. Need not be evenly spaced or include
+   * the ends.
+   */
+  markers: number[]
+  /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */
+  axis: AxisConfig
+  /**
+   * Rotated caption drawn in the gutter to the left of the marker column. Empty
+   * string (the default) hides it — no caption node is built and no label gutter
+   * is reserved.
+   */
+  label: string
+}
+
+/** How far a marker starts to the right of its slot when it enters, in px. */
+const SLIDE = 24
+
+/** How a tick value is captioned — see {@link VerticalAxis.labelFor}. */
+export type MarkerLabel = (value: number) => string
+
+/**
+ * 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<VerticalAxisProps> {
+  @property({ default: () => [0, 1] as Range }) declare range: Range
+  @property({ default: () => [] as number[] }) declare markers: number[]
+  @property({ default: DEFAULT_Y_AXIS }) declare axis: AxisConfig
+  @property({ default: "" }) declare label: string
+
+  /**
+   * 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: MarkerLabel = formatMarker
+
+  /** One text node per marker, ordered top → bottom, for the staggered enter. */
+  private markerNodes: Text[] = []
+  /** The caption node, or null when `label` is empty. Entered after the markers. */
+  private labelNode: Text | null = null
+
+  /** The live tick values, top → bottom (highest first) — re-read every frame. */
+  private get sortedMarkers(): number[] {
+    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.
+   */
+  private valueAt(index: number): number | undefined {
+    return this.sortedMarkers[index]
+  }
+
+  /** Tick `i`'s fraction across the live `range`, 0 at the bottom edge. */
+  private fracAt(index: number): number {
+    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?: NodeConfig<VerticalAxis, VerticalAxisProps>) {
+    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: Text = 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: Node2D[] = []
+    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): void {
+    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.
+   */
+  @command()
+  enter(args: CommandArgs<{ stagger?: number; slide?: number }> & { duration: number }): Seekable {
+    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 }))]
+        : []),
+    ])
+  }
+}

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

@@ -0,0 +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/core"
+
+import { SPOTLIGHT_DIM } from "../kit/shared"
+import {
+  EMPTY_REGION_BOX,
+  clipPolylineToBox,
+  hasRegion,
+  type RegionBox,
+} from "./shared"
+import { declarePaints } from "@motionscript/core/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
+    )
+  }
+}

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

@@ -0,0 +1,135 @@
+import {
+  type AssetScope,
+  Graphics2D,
+  Node2D,
+  fillOps,
+  strokeOps,
+  property,
+  type Fill,
+  type FillResolved,
+  type Node2DProps,
+  type RenderContext2D,
+  type Stroke,
+  type StrokeResolved,
+} from "@motionscript/core"
+
+import {
+  DEFAULT_CHART_THEME,
+  EMPTY_REGION_BOX,
+  hasRegion,
+  type RegionBox,
+} from "./shared"
+import { declarePaints } from "@motionscript/core/component"
+
+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 class ChartRegion extends Node2D<ChartRegionProps> {
+  @property({ default: () => EMPTY_REGION_BOX }) declare box: RegionBox
+  @property({
+    default: DEFAULT_CHART_THEME.region.stroke,
+    mapper: strokeOps.resolve,
+    tween: strokeOps.lerp,
+  })
+  declare stroke: Stroke
+  @property({
+    default: DEFAULT_CHART_THEME.region.fill,
+    mapper: fillOps.resolve,
+    tween: fillOps.lerp,
+  })
+  declare fill: Fill
+  @property({ default: 0 }) declare reveal: 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 {
+    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 as FillResolved[]
+    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 as StrokeResolved[]
+    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: { x: number; y: number }[]) =>
+      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 },
+        ])
+      }
+    }
+  }
+}