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

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

@@ -0,0 +1,202 @@
+import {
+  command,
+  Node2D,
+  Rect,
+  Text,
+  easeOut,
+  property,
+  insetsOps,
+  textOps,
+  type CommandArgs,
+  type NodeConfig,
+  type Node2DProps,
+} from "@motionscript/core";
+
+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;
+}
+
+/** 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 }))]
+        : []),
+    ]);
+  }
+}

package/src/line-chart/index.ts

@@ -0,0 +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"