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

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

@@ -1,135 +1,135 @@
-import {
-  type AssetScope,
-  Graphics2D,
-  Node2D,
-  fillOps,
-  strokeOps,
-  property,
-  type Fill,
-  type FillResolved,
-  type Node2DProps,
-  type RenderContext2D,
-  type Stroke,
-  type StrokeResolved,
-} from "@motionscript/core"
-
-import {
-  DEFAULT_CHART_THEME,
-  EMPTY_REGION_BOX,
-  hasRegion,
-  type RegionBox,
-} from "./shared"
-import { declarePaints } from "@motionscript/core/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.
- *
- * 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
- * the two can't disagree about where the boundary is.
- *
- * Only bounded edges get a rule: a region given just an `x` range spans the full
- * 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
-    if (!hasRegion(box)) return
-
-    const r = Math.max(0, Math.min(1, this.reveal))
-    if (r <= 0) return
-
-    const width = box.right - box.left
-    const height = box.top - box.bottom
-    const cx = (box.left + box.right) / 2
-    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)
-      )
-    }
-
-    // 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
-
-    // 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))
-
-    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 },
-        ])
-      }
-    }
-    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 },
-        ])
-      }
-    }
-  }
-}
+import {
+  type AssetScope,
+  Graphics2D,
+  Node2D,
+  fillOps,
+  strokeOps,
+  property,
+  type Fill,
+  type FillResolved,
+  type Node2DProps,
+  type RenderContext2D,
+  type Stroke,
+  type StrokeResolved,
+} from "@motionscript/sdk"
+
+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.
+ *
+ * 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
+ * the two can't disagree about where the boundary is.
+ *
+ * Only bounded edges get a rule: a region given just an `x` range spans the full
+ * 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
+    if (!hasRegion(box)) return
+
+    const r = Math.max(0, Math.min(1, this.reveal))
+    if (r <= 0) return
+
+    const width = box.right - box.left
+    const height = box.top - box.bottom
+    const cx = (box.left + box.right) / 2
+    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)
+      )
+    }
+
+    // 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
+
+    // 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))
+
+    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 },
+        ])
+      }
+    }
+    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 },
+        ])
+      }
+    }
+  }
+}

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

@@ -1,202 +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 }))]
-        : []),
-    ]);
-  }
-}
+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 }))]
+        : []),
+    ]);
+  }
+}