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

package/src/kit/vertical-axis.ts

@@ -1,18 +1,18 @@
 import {
-  command,
-  Node2D,
   Rect,
   RotatedBox,
   Text,
-  easeOut,
-  property,
+  Types,
+  component2d,
   insetsOps,
   textOps,
-  type CommandArgs,
-  type NodeConfig,
+  type NodeOf,
+  type Node2D,
   type Node2DProps,
 } from "@motionscript/sdk"
 
+import { asParts, fresh } from "./entries"
+import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "./motion"
 import {
   DEFAULT_Y_AXIS,
   enterBudget,
@@ -20,7 +20,6 @@ import {
   type AxisConfig,
   type Range,
 } from "./shared"
-import { at, compose, type Seekable } from "@motionscript/sdk/component"
 
 export interface VerticalAxisProps extends Node2DProps {
   /** `[min, max]` of the vertical scale the markers are positioned within. */
@@ -31,6 +30,12 @@ export interface VerticalAxisProps extends Node2DProps {
    * the ends.
    */
   markers: number[]
+  /**
+   * How each marker is captioned, one per entry of `markers` and in its order.
+   * Empty (the default), or short, captions a marker with its bare numeric
+   * reading; a chart with a number format on this axis writes them through it.
+   */
+  captions: string[]
   /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */
   axis: AxisConfig
   /**
@@ -44,9 +49,15 @@ export interface VerticalAxisProps extends Node2DProps {
 /** 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}. */
+/** How a tick value is captioned — see {@link VerticalAxisProps.captions}. */
 export type MarkerLabel = (value: number) => string
 
+/** What a marker's caption reads: the one listed for its value, else its bare reading. */
+export function markerCaption(s: { readonly markers: readonly number[]; readonly captions: readonly string[] }, value: number): string {
+  const index = s.markers.indexOf(value)
+  return (index >= 0 ? s.captions[index] : undefined) ?? formatMarker(value)
+}
+
 /**
  * The numeric vertical axis shared by the cartesian charts: a **column of
  * {@link Text} nodes**, one per marker value, running top-to-bottom (highest
@@ -60,73 +71,54 @@ export type MarkerLabel = (value: number) => string
  * 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
+ * `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
+export const VerticalAxis = component2d({
+  key: "verticalAxis",
+  state: {
+    range: fresh<Range>(() => [0, 1]),
+    markers: fresh<number[]>(() => []),
+    captions: fresh<string[]>(() => []),
+    axis: Types.custom<AxisConfig>(DEFAULT_Y_AXIS),
+    label: "",
+    arrivals: arrivalsEntry(),
+  },
+  // A plain node filled its parent; one made of its markers would hug them.
+  defaults: { width: "fill", height: "fill" },
+  children: (state) => {
+    // Composed from plain entries (range/markers/label), so it's built once here.
+    const tickPad = insetsOps.resolve(state.axis.tickPadding).right
+    const titlePad = insetsOps.resolve(state.axis.titlePadding).right
+
+    const row: Node2D[] = []
+    // The row's parent is the axis: its box is what the markers are placed in.
+    const box = () => (row[0]?.parent as Node2D | null | undefined)?.layoutBounds ?? { width: 0, height: 0 }
+    /** The live tick values, top → bottom (highest first) — re-read every frame. */
+    const sorted = () => [...state.markers].sort((a, b) => b - a)
+    /** Tick `i`'s fraction across the live `range`, 0 at the bottom edge. */
+    const fracAt = (value: number | undefined) => {
+      if (value === undefined) return 0
+      const [min, max] = state.range
+      return max <= min ? 0 : (value - min) / (max - min)
+    }
 
-    this.markerNodes = this.markers.map((_, i) => {
-      const marker: Text = new Text({
-        ...textOps.styleProps(this.axis.labelStyle),
+    // One text node per marker, ordered top → bottom. A slot with no value (the
+    // live list is shorter than the column built for it) renders as empty text
+    // rather than repeating its neighbour.
+    const markers = state.markers.map((_, i) => {
+      const marker: Node2D = new Text({
+        ...textOps.styleProps(state.axis.labelStyle),
         text: () => {
-          const v = this.valueAt(i)
-          return v === undefined ? "" : this.labelFor(v)
+          const value = sorted()[i]
+          return value === undefined ? "" : markerCaption(state, value)
         },
         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
+          const height = box().height
+          const centred = (fracAt(sorted()[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
@@ -134,91 +126,69 @@ export class VerticalAxis extends Node2D<VerticalAxisProps> {
           const limit = height / 2 - marker.layoutBounds.height / 2
           return Math.min(centred, limit)
         },
+        opacity: () => arrivalOf(state.arrivals, i).opacity,
+        x: () => arrivalOf(state.arrivals, i).shift,
       })
       return marker
     })
 
     const children: Node2D[] = []
-    if (this.label !== "") {
-      this.labelNode = new Text({
-        ...textOps.styleProps(this.axis.titleStyle),
-        text: this.label,
-      })
+    if (state.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: new Text({
+            ...textOps.styleProps(state.axis.titleStyle),
+            text: state.label,
+            opacity: () => arrivalOf(state.arrivals, "label").opacity,
+            x: () => arrivalOf(state.arrivals, "label").shift,
+          }),
         })
       )
     }
-    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 }))]
-        : []),
-    ])
-  }
-}
+    children.push(new Rect({ height: "fill", width: "hug", padding: { right: tickPad }, children: markers }))
+    row.push(new Rect({ flow: "horizontal", gap: titlePad, children }))
+    return asParts(row)
+  },
+  commands: {
+    /**
+     * Stagger the markers in bottom to top, then slide the caption in from the
+     * right after them. Its first frame arms them all: shifted right by `slide`
+     * and transparent.
+     *
+     * The timeline's 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.
+     *
+     * `stagger` is seconds between successive markers (derived when omitted);
+     * `slide` is the starting rightward offset in px.
+     */
+    enter: {
+      args: {
+        stagger: Types.custom<number | undefined>(undefined),
+        slide: Types.number(SLIDE),
+      },
+      run: (timeline, state) => {
+        const { stagger, slide } = timeline.args
+        const count = state.markers.length
+        const captioned = state.label !== ""
+        const from: Arrival = { opacity: 0, shift: slide }
+        const keys = [...state.markers.keys(), ...(captioned ? ["label"] : [])]
+        const arm = timeline.animate(() => ({ arrivals: armed(keys, from) }))
+        if (count === 0) return arm
+        const { step, per, caption } = enterBudget(timeline.duration, count, captioned, stagger)
+        const ease = frameEase(timeline)
+        // Bottom marker leads: the column is top → bottom, so walk it in reverse.
+        const markers = state.markers.map((_, i) => ({ at: (count - 1 - i) * step, duration: per, piece: arrival(timeline, i, from, ease) }))
+        // Once every marker has landed, the caption slides in from the right.
+        const label = captioned ? [{ at: (count - 1) * step + per, duration: caption, piece: arrival(timeline, "label", from, ease) }] : []
+        return timeline.together([arm, beats(timeline, [...markers, ...label])])
+      },
+    },
+  },
+})
+
+export type VerticalAxis = NodeOf<typeof VerticalAxis>

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

@@ -1,21 +1,20 @@
 import {
-  type AssetScope,
   Graphics2D,
-  Node2D,
-  command,
-  easeOut,
+  Types,
+  component2d,
   strokeOps,
-  property,
-  type Command,
-  type CommandArgs,
-  type EasingFunction,
+  type NodeOf,
+  // Named so this component's emitted type reaches `Node2D` through the sdk, not core.
+  type Node2D as _Node2D,
   type Node2DProps,
-  type RenderContext2D,
   type Stroke,
   type StrokeResolved,
   type Vector2,
 } from "@motionscript/sdk"
 
+import { fresh } from "../kit/entries"
+import { frameEase } from "../kit/motion"
+import { loadPaints } from "../kit/paints"
 import { SPOTLIGHT_DIM } from "../kit/shared"
 import {
   EMPTY_REGION_BOX,
@@ -23,7 +22,6 @@ import {
   hasRegion,
   type RegionBox,
 } from "./shared"
-import { declarePaints } from "@motionscript/sdk/component"
 
 export interface ChartLineProps extends Node2DProps {
   /**
@@ -40,8 +38,8 @@ export interface ChartLineProps extends Node2DProps {
    * 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.
+   * ChartLine.enter} drives it from 0 regardless of where it rests, so the
+   * animation is unchanged.
    */
   progress: number
   /**
@@ -59,46 +57,101 @@ export interface ChartLineProps extends Node2DProps {
   dimOpacity: number
 }
 
+/**
+ * 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.
+ */
+function 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
+}
+
 /**
  * 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.
+ * (animated by `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
+export const ChartLine = component2d({
+  key: "chartLine",
+  state: {
+    points: fresh<Vector2[]>(() => []),
+    stroke: Types.custom<Stroke, StrokeResolved[]>([], { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
+    progress: 1,
+    enabled: true,
+    spotlight: fresh<RegionBox>(() => EMPTY_REGION_BOX),
+    dimOpacity: SPOTLIGHT_DIM,
+  },
+  load: (loader, state) => loadPaints(loader, { strokes: [state.stroke] }),
+  commands: {
+    /**
+     * Trace the line from `from` to `to` over the command — by default in from
+     * its left end to its right. `showSeries` and `hideSeries` are the same
+     * motion in opposite directions, so both are this with their ends stated.
+     *
+     * `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.
+     */
+    enter: {
+      args: { from: Types.number(0, { min: 0, max: 1 }), to: Types.number(1, { min: 0, max: 1 }) },
+      run: (timeline) => {
+        const { from, to } = timeline.args
+        const ease = frameEase(timeline)
+        return timeline.animate((t) => {
+          const progress = from + (to - from) * ease(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 }
+        })
+      },
+    },
+  },
+  render: (ctx, state) => {
+    if (!state.enabled) return
+    const pts = state.points
     if (pts.length < 2) return
 
-    const p = Math.max(0, Math.min(1, this.progress))
+    const p = Math.max(0, Math.min(1, state.progress))
     if (p <= 0) return
 
-    const drawn = this.tracePoints(pts, p)
+    const drawn = tracePoints(pts, p)
     if (drawn.length < 2) return
-    const stroke = this.stroke as StrokeResolved[]
+    const stroke = state.stroke
     const radius = (stroke[0]?.weight ?? 0) * 2 // round the joins
 
-    const box = this.spotlight
+    const box = state.spotlight
     if (!hasRegion(box)) {
       ctx.draw(new Graphics2D().line({ points: drawn, radius }).stroke(stroke))
       return
@@ -113,7 +166,7 @@ export class ChartLine extends Node2D<ChartLineProps> {
       new Graphics2D()
         .line({ points: drawn, radius })
         .stroke(stroke)
-        .opacity(Math.max(0, Math.min(1, this.dimOpacity)))
+        .opacity(Math.max(0, Math.min(1, state.dimOpacity)))
     )
 
     // One `draw` per run: shapes chained before a `stroke()` are combined into a
@@ -122,87 +175,7 @@ export class ChartLine extends Node2D<ChartLineProps> {
     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
-    )
-  }
-}
+export type ChartLine = NodeOf<typeof ChartLine>