@motionscript/charts 0.1.0-alpha.0 → 0.1.0-alpha.10

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,
-} from "@motionscript/core";
+  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/core/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

@@ -6,12 +6,12 @@
  * (the plot panel, the value axis, the legend); each part is exported too, so
  * another node type can reuse one on its own.
  *
- * These files are what `ms add line-chart` copies. Everything they reach for
+ * These files are what a copy of the line chart takes (`registry.json`). Everything they reach for
  * 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"