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

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

@@ -1,202 +1,166 @@
-import {
-  command,
-  Node2D,
-  Rect,
-  Text,
-  easeOut,
-  property,
-  insetsOps,
-  textOps,
-  type CommandArgs,
-  type NodeConfig,
-  type Node2DProps,
-} from "@motionscript/sdk";
-
-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;
-}
-
-/** 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
- * kit's `VerticalAxis`, including its bound (not snapshotted) marker text and
- * positions, and its landed resting state.
- *
- * Markers are always placed **by value** across the range, whatever they say:
- * `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}.
- *
- * {@link 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),
-        text: () => {
-          const v = this.valueAt(i);
-          return v === undefined ? "" : this.labelFor(v);
-        },
-        x: () => {
-          const width = this.layoutBounds.width;
-          const centred = (this.fracAt(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
-          // the rectangle the editor draws around it. Only the right edge is
-          // held, because the left one has the vertical axis's whole gutter
-          // beyond it, and a marker overhanging into that is inside the chart.
-          const limit = width / 2 - marker.layoutBounds.width / 2;
-          return Math.min(centred, limit);
-        },
-      });
-      return marker;
-    });
-
-    const children: Node2D[] = [
-      new Rect({
-        width: "fill",
-        height: "hug",
-        padding: { top: tickPad },
-        children: this.markerNodes,
-      }),
-    ];
-    if (this.label !== "") {
-      this.labelNode = new Text({
-        ...textOps.styleProps(this.axis.titleStyle),
-        text: this.label,
-      });
-      children.push(this.labelNode);
-    }
-
-    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 }))]
-        : []),
-    ]);
-  }
-}
+import {
+  Rect,
+  Text,
+  Types,
+  component2d,
+  insetsOps,
+  textOps,
+  type NodeOf,
+  type Node2D,
+  type Node2DProps,
+} 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,
+  type AxisConfig,
+  type Range,
+} from "../kit/shared";
+import { markerCaption } from "../kit/vertical-axis";
+
+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[];
+  /**
+   * 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: string[];
+  /** 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;
+}
+
+/** How far a marker starts above its slot when it enters, in px. */
+const SLIDE = 24;
+
+/** How a tick value is captioned — see {@link HorizontalAxisProps.captions}. */
+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
+ * kit's `VerticalAxis`, including its bound (not snapshotted) marker text and
+ * positions, and its landed resting state.
+ *
+ * Markers are always placed **by value** across the range, whatever they say:
+ * `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 HorizontalAxisProps.captions}.
+ *
+ * `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 const HorizontalAxis = component2d({
+  key: "horizontalAxis",
+  state: {
+    range: fresh<Range>(() => [0, 1]),
+    markers: fresh<number[]>(() => []),
+    captions: fresh<string[]>(() => []),
+    axis: Types.custom<AxisConfig>(DEFAULT_X_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) => {
+    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 value = sorted()[i];
+          return value === undefined ? "" : markerCaption(state, value);
+        },
+        x: () => {
+          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
+          // the rectangle the editor draws around it. Only the right edge is
+          // held, because the left one has the vertical axis's whole gutter
+          // beyond it, and a marker overhanging into that is inside the chart.
+          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: markers }),
+    ];
+    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,
+        }),
+      );
+    }
+
+    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

@@ -1,39 +1,39 @@
-/**
- * The line chart: a cartesian plot with a traced polyline, spotlit regions and
- * a staggered entrance.
- *
- * {@link LineChart} composes the parts below plus the shared ones in the kit
- * (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
- * 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 { ChartRegion } from "./chart-region"
-export { ChartLine } from "./chart-line"
-export { HorizontalAxis } from "./horizontal-axis"
-export {
-  DEFAULT_CHART_THEME,
-  EMPTY_REGION_BOX,
-  clipPolylineToBox,
-  hasRegion,
-  lerpChartTheme,
-  resolveChartTheme,
-  resolveRegionBox,
-  resolveYScale,
-  seriesPoints,
-  yExtent,
-} from "./shared"
-export type {
-  ChartConfig,
-  ChartTheme,
-  LineSeries,
-  PlotRegion,
-  RegionBox,
-  RegionConfig,
-} from "./shared"
-export { formatInstant, parseInstant, resolveXScale } from "./x-scale"
-export type { XScale, XScaleKind } from "./x-scale"
+/**
+ * The line chart: a cartesian plot with a traced polyline, spotlit regions and
+ * a staggered entrance.
+ *
+ * {@link LineChart} composes the parts below plus the shared ones in the kit
+ * (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
+ * 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, 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"
+export {
+  DEFAULT_CHART_THEME,
+  EMPTY_REGION_BOX,
+  clipPolylineToBox,
+  hasRegion,
+  lerpChartTheme,
+  resolveChartTheme,
+  resolveRegionBox,
+  resolveYScale,
+  seriesPoints,
+  yExtent,
+} from "./shared"
+export type {
+  ChartConfig,
+  ChartTheme,
+  LineSeries,
+  PlotRegion,
+  RegionBox,
+  RegionConfig,
+} from "./shared"
+export { formatInstant, parseInstant, resolveXScale } from "./x-scale"
+export type { XScale, XScaleKind } from "./x-scale"