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

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

@@ -1,50 +1,32 @@
 import {
-  type AssetScope,
   Graphics2D,
-  Node2D,
+  Types,
+  component2d,
   fillOps,
   strokeOps,
-  property,
   type Fill,
   type FillResolved,
-  type Node2DProps,
-  type RenderContext2D,
+  type NodeOf,
+  // Named so this component's emitted type reaches `Node2D` through the sdk, not core.
+  type Node2D as _Node2D,
   type Stroke,
   type StrokeResolved,
 } from "@motionscript/sdk"
 
+import { fresh } from "../kit/entries"
+import { loadPaints } from "../kit/paints"
 import {
   DEFAULT_CHART_THEME,
   EMPTY_REGION_BOX,
   hasRegion,
   type RegionBox,
 } from "./shared"
-import { declarePaints } from "@motionscript/sdk/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.
+ * positioned entirely from the pre-mapped `box` rather
+ * than its own box — the region 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
@@ -54,36 +36,24 @@ export interface ChartRegionProps extends Node2DProps {
  * 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
+export const ChartRegion = component2d({
+  key: "chartRegion",
+  state: {
+    /** 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: fresh<RegionBox>(() => EMPTY_REGION_BOX),
+    /** Dashed rule marking each *bounded* edge of the box. */
+    stroke: Types.custom<Stroke, StrokeResolved[]>(DEFAULT_CHART_THEME.region.stroke, { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
+    /** Wash filling the box, under the series lines. */
+    fill: Types.custom<Fill, FillResolved[]>(DEFAULT_CHART_THEME.region.fill, { resolve: fillOps.resolve, lerp: fillOps.lerp }),
+    /** Reveal of the annotation in `[0, 1]`, driven by the chart's own `regionReveal` so the rules and the series' dimming move as one. */
+    reveal: 0,
+  },
+  load: (loader, state) => loadPaints(loader, { fills: [state.fill], strokes: [state.stroke] }),
+  render: (ctx, state) => {
+    const box = state.box
     if (!hasRegion(box)) return
 
-    const r = Math.max(0, Math.min(1, this.reveal))
+    const r = Math.max(0, Math.min(1, state.reveal))
     if (r <= 0) return
 
     const width = box.right - box.left
@@ -92,44 +62,29 @@ export class ChartRegion extends Node2D<ChartRegionProps> {
     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)
-      )
+    if (state.fill.length > 0) {
+      ctx.draw(new Graphics2D().rect({ x: cx, y: cy, width, height }).fill(state.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
+    if (state.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))
+      ctx.draw(new Graphics2D().line({ points }).stroke(state.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 },
-        ])
-      }
+      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 },
-        ])
-      }
+      for (const y of [box.bottom, box.top]) rule([{ x: cx - half, y }, { x: cx + half, y }])
     }
-  }
-}
+  },
+})
+
+export type ChartRegion = NodeOf<typeof ChartRegion>

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

@@ -1,46 +1,27 @@
 import {
-  command,
-  Node2D,
   Rect,
   Text,
-  easeOut,
-  property,
+  Types,
+  component2d,
   insetsOps,
   textOps,
-  type CommandArgs,
-  type NodeConfig,
-  type Node2DProps,
+  type NodeOf,
+  type Node2D,
 } from "@motionscript/sdk";
 
+import { asParts, fresh } from "../kit/entries";
+import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "../kit/motion";
 import {
   DEFAULT_X_AXIS,
   enterBudget,
-  formatMarker,
   type AxisConfig,
   type Range,
 } from "../kit/shared";
-import { at, compose, type Seekable } from "@motionscript/sdk/component"
-
-export interface HorizontalAxisProps extends Node2DProps {
-  /** `[min, max]` of the horizontal scale the markers are positioned within. */
-  range: Range;
-  /** Tick values (in data units) to draw along the axis. */
-  markers: number[];
-  /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */
-  axis: AxisConfig;
-  /**
-   * Caption drawn centred in the gutter beneath the marker row. Empty string
-   * (the default) hides it.
-   */
-  label: string;
-}
+import { markerCaption } from "../kit/vertical-axis";
 
 /** How far a marker starts above its slot when it enters, in px. */
 const SLIDE = 24;
 
-/** How a tick value is captioned — see {@link HorizontalAxis.labelFor}. */
-export type MarkerLabel = (value: number) => string;
-
 /**
  * The horizontal axis of a {@link LineChart}: a **row of {@link Text} nodes**,
  * one per marker value, running left-to-right. Pure layout — the mirror of the
@@ -51,68 +32,58 @@ export type MarkerLabel = (value: number) => string;
  * `2026-03` sits three months along, not three slots along. That is what keeps
  * it distinct from a bar chart's bottom axis, which centres a caption on each
  * slot and has no scale at all — the two only look alike. What the values are
- * captioned *as* is the chart's to decide; see {@link labelFor}.
+ * captioned *as* is the chart's to decide, in `captions`.
  *
- * {@link enter} staggers the markers in **left-to-right**: each starts lifted a
+ * `enter` staggers the markers in **left-to-right**: each starts lifted a
  * little above its slot and transparent, then fades and slides down into place.
  */
-export class HorizontalAxis extends Node2D<HorizontalAxisProps> {
-  @property({ default: () => [0, 1] as Range }) declare range: Range;
-  @property({ default: () => [] as number[] }) declare markers: number[];
-  @property({ default: DEFAULT_X_AXIS }) declare axis: AxisConfig;
-  @property({ default: "" }) declare label: string;
-
-  /**
-   * How a tick value is captioned. Defaults to the numeric formatting the
-   * vertical axis uses; a chart whose x column names months or categories
-   * replaces it (see `x-scale.ts`).
-   *
-   * A plain field rather than a `@property`, because it is a **policy, not a
-   * value**: there is nothing to tween between two formatters, and a signal
-   * holding a function is a signal every `set`/`to` on this node would have to
-   * know not to touch. Read inside each marker's `text` binding, so replacing it
-   * before the first frame is enough — which is when the chart does it.
-   */
-  labelFor: MarkerLabel = formatMarker;
-
-  /** One text node per marker, ordered left → right, for the staggered enter. */
-  private markerNodes: Text[] = [];
-  /** The caption node, or null when `label` is empty. */
-  private labelNode: Text | null = null;
-
-  /** The live tick values, left → right — re-read every frame, not snapshotted. */
-  private get sortedMarkers(): number[] {
-    return [...this.markers].sort((a, b) => a - b);
-  }
-
-  private valueAt(index: number): number | undefined {
-    return this.sortedMarkers[index];
-  }
-
-  /** Tick `i`'s fraction across the live `range`, 0 at the left 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<HorizontalAxis, HorizontalAxisProps>) {
-    super(props);
-
-    const tickPad = insetsOps.resolve(this.axis.tickPadding).top;
-    const titlePad = insetsOps.resolve(this.axis.titlePadding).top;
-
-    this.markerNodes = this.markers.map((_, i) => {
-      const marker: Text = new Text({
-        ...textOps.styleProps(this.axis.labelStyle),
+export const HorizontalAxis = component2d({
+  key: "horizontalAxis",
+  state: {
+    /** `[min, max]` of the horizontal scale the markers are positioned within. */
+    range: fresh<Range>(() => [0, 1]),
+    /** Tick values (in data units) to draw along the axis. */
+    markers: fresh<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 whose x column names months or categories writes those.
+     */
+    captions: fresh<string[]>(() => []),
+    /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */
+    axis: Types.custom<AxisConfig>(DEFAULT_X_AXIS),
+    /** Caption drawn centred in the gutter beneath the marker row; empty (the default) hides it. */
+    label: "",
+    arrivals: arrivalsEntry(),
+  },
+  // A plain node filled its parent; one made of its markers would hug them.
+  defaults: { width: "fill", height: "fill" },
+  children: (state) => {
+    const tickPad = insetsOps.resolve(state.axis.tickPadding).top;
+    const titlePad = insetsOps.resolve(state.axis.titlePadding).top;
+
+    const column: Node2D[] = [];
+    // The column's parent is the axis: its box is what the markers are placed in.
+    const box = () => (column[0]?.parent as Node2D | null | undefined)?.layoutBounds ?? { width: 0, height: 0 };
+    /** The live tick values, left → right — re-read every frame, not snapshotted. */
+    const sorted = () => [...state.markers].sort((a, b) => a - b);
+    /** Tick `i`'s fraction across the live `range`, 0 at the left edge. */
+    const fracAt = (value: number | undefined) => {
+      if (value === undefined) return 0;
+      const [min, max] = state.range;
+      return max <= min ? 0 : (value - min) / (max - min);
+    };
+
+    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);
         },
         x: () => {
-          const width = this.layoutBounds.width;
-          const centred = (this.fracAt(i) - 0.5) * width;
+          const width = box().width;
+          const centred = (fracAt(sorted()[i]) - 0.5) * width;
           // Held inside the axis's right edge, which is also the *chart's*: the
           // last marker is centred on the last grid line, so half of `2026-06`
           // — or of `3300` — would be drawn outside the node's box and outside
@@ -122,81 +93,59 @@ export class HorizontalAxis extends Node2D<HorizontalAxisProps> {
           const limit = width / 2 - marker.layoutBounds.width / 2;
           return Math.min(centred, limit);
         },
+        opacity: () => arrivalOf(state.arrivals, i).opacity,
+        y: () => arrivalOf(state.arrivals, i).shift,
       });
       return marker;
     });
 
     const children: Node2D[] = [
-      new Rect({
-        width: "fill",
-        height: "hug",
-        padding: { top: tickPad },
-        children: this.markerNodes,
-      }),
+      new Rect({ width: "fill", height: "hug", padding: { top: tickPad }, children: markers }),
     ];
-    if (this.label !== "") {
-      this.labelNode = new Text({
-        ...textOps.styleProps(this.axis.titleStyle),
-        text: this.label,
-      });
-      children.push(this.labelNode);
+    if (state.label !== "") {
+      children.push(
+        new Text({
+          ...textOps.styleProps(state.axis.titleStyle),
+          text: state.label,
+          opacity: () => arrivalOf(state.arrivals, "label").opacity,
+          y: () => arrivalOf(state.arrivals, "label").shift,
+        }),
+      );
     }
 
-    this.add(
-      new Rect({ flow: "vertical", gap: titlePad, height: "hug", width: "fill", children }),
-    );
-  }
-
-  /**
-   * Primes every marker (and the caption) at its pre-entrance state: lifted
-   * above its slot and transparent. Idempotent — see {@link VerticalAxis.arm}.
-   */
-  arm(slide = SLIDE): void {
-    for (const marker of this.markerNodes) marker.set({ opacity: 0, y: slide });
-    this.labelNode?.set({ opacity: 0, y: slide });
-  }
-
-  /**
-   * Stagger the markers in left to right, then slide the caption in after them.
-   *
-   * A {@link Seekable} rather than a generator. The offsets were always static —
-   * `i * step` per marker — but expressed as `wait` inside a generator they only
-   * existed while it ran, so knowing what the axis looked like partway through
-   * meant running it from zero. Placed explicitly, the same stagger can be asked
-   * for a time, which is what lets a chart scene scrub in constant time.
-   *
-   * `duration` is the **whole** entrance — see {@link VerticalAxis.enter} and
-   * {@link enterBudget}.
-   */
-  @command()
-  enter(
-    args: CommandArgs<{ stagger?: number; slide?: number }> & { duration: number },
-  ): Seekable {
-    const { stagger, slide = SLIDE } = args.data ?? {};
-    const duration = args.duration;
-    const easing = args.easing ?? easeOut();
-    const nodes = this.markerNodes;
-    if (nodes.length === 0) return compose([]);
-    const { step, per, caption } = enterBudget(
-      duration,
-      nodes.length,
-      this.labelNode !== null,
-      stagger,
-    );
-
-    this.arm(slide);
-
-    // Left marker leads: markerNodes is already left → right.
-    const markers = nodes.map((node, i) =>
-      at(i * step, node.to({ data: { opacity: 1, y: 0 }, duration: per, easing })),
-    );
-    const lastMarkerEnds = nodes.length === 0 ? 0 : (nodes.length - 1) * step + per;
-
-    return compose([
-      ...markers,
-      ...(this.labelNode
-        ? [at(lastMarkerEnds, this.labelNode.to({ data: { opacity: 1, y: 0 }, duration: caption, easing }))]
-        : []),
-    ]);
-  }
-}
+    column.push(new Rect({ flow: "vertical", gap: titlePad, height: "hug", width: "fill", children }));
+    return asParts(column);
+  },
+  commands: {
+    /**
+     * Stagger the markers in left to right, then slide the caption in after
+     * them. Its first frame arms them all: lifted by `slide` and transparent.
+     *
+     * The timeline's duration is the **whole** entrance — see
+     * `VerticalAxis.enter` and {@link enterBudget}.
+     */
+    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);
+        // Left marker leads: the row is already left → right.
+        const markers = state.markers.map((_, i) => ({ at: i * step, duration: per, piece: arrival(timeline, i, from, ease) }));
+        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 HorizontalAxis = NodeOf<typeof HorizontalAxis>;

package/src/line-chart/index.ts

@@ -10,8 +10,8 @@
  * that is *not* here comes from the kit and stays a dependency — see
  * `../engine.ts` for why that line is where it is.
  */
-export { LineChart } from "./line-chart"
-export type { LineChartProps } from "./line-chart"
+export { LineChart, lineChartDomains } from "./line-chart"
+export type { LineChartDomains, LineChartProps, LineChartValues } from "./line-chart"
 export { ChartRegion } from "./chart-region"
 export { ChartLine } from "./chart-line"
 export { HorizontalAxis } from "./horizontal-axis"