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

package/src/kit/vertical-axis.ts

@@ -1,224 +1,224 @@
-import {
-  command,
-  Node2D,
-  Rect,
-  RotatedBox,
-  Text,
-  easeOut,
-  property,
-  insetsOps,
-  textOps,
-  type CommandArgs,
-  type NodeConfig,
-  type Node2DProps,
-} from "@motionscript/core"
-
-import {
-  DEFAULT_Y_AXIS,
-  enterBudget,
-  formatMarker,
-  type AxisConfig,
-  type Range,
-} from "./shared"
-import { at, compose, type Seekable } from "@motionscript/core/component"
-
-export interface VerticalAxisProps extends Node2DProps {
-  /** `[min, max]` of the vertical scale the markers are positioned within. */
-  range: Range
-  /**
-   * Tick values (in data units) to draw up the axis, each placed by its fraction
-   * across {@link VerticalAxisProps.range}. Need not be evenly spaced or include
-   * the ends.
-   */
-  markers: number[]
-  /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */
-  axis: AxisConfig
-  /**
-   * Rotated caption drawn in the gutter to the left of the marker column. Empty
-   * string (the default) hides it — no caption node is built and no label gutter
-   * is reserved.
-   */
-  label: string
-}
-
-/** How far a marker starts to the right of its slot when it enters, in px. */
-const SLIDE = 24
-
-/** How a tick value is captioned — see {@link VerticalAxis.labelFor}. */
-export type MarkerLabel = (value: number) => string
-
-/**
- * The numeric vertical axis shared by the cartesian charts: a **column of
- * {@link Text} nodes**, one per marker value, running top-to-bottom (highest
- * value at the top). Pure layout — no `Graphics` — so the markers are real text
- * nodes the scene can measure, restyle, or animate individually.
- *
- * Each marker is positioned so its centre lands exactly on its value's fraction
- * across `range` within the axis's filled height, so unevenly-spaced markers
- * land where their values fall. Both the caption and the position are *bound*,
- * not snapshotted: a chart that rescales its axes (see `LineChart.zoomTo`)
- * tweens `range`/`markers` live. Only the marker **count** is fixed at
- * construction.
- *
- * {@link enter} staggers them in **bottom-to-top**: each marker starts pushed a
- * little to the right and transparent, then fades and slides left into place.
- * The resting state is the landed one, so a chart that is never told to enter
- * still reads as a finished chart.
- */
-export class VerticalAxis extends Node2D<VerticalAxisProps> {
-  @property({ default: () => [0, 1] as Range }) declare range: Range
-  @property({ default: () => [] as number[] }) declare markers: number[]
-  @property({ default: DEFAULT_Y_AXIS }) declare axis: AxisConfig
-  @property({ default: "" }) declare label: string
-
-  /**
-   * How a tick value is captioned. Defaults to the bare numeric reading; a
-   * chart with a number format on this axis replaces it (see `number-format`).
-   *
-   * A plain field rather than a `@property`, for the reason the horizontal
-   * axis's twin spells out: it is a policy, not a value, and there is nothing
-   * to tween between two formatters.
-   */
-  labelFor: MarkerLabel = formatMarker
-
-  /** One text node per marker, ordered top → bottom, for the staggered enter. */
-  private markerNodes: Text[] = []
-  /** The caption node, or null when `label` is empty. Entered after the markers. */
-  private labelNode: Text | null = null
-
-  /** The live tick values, top → bottom (highest first) — re-read every frame. */
-  private get sortedMarkers(): number[] {
-    return [...this.markers].sort((a, b) => b - a)
-  }
-
-  /**
-   * Tick `i`'s value, or `undefined` once the live `markers` list is shorter
-   * than the column of text nodes built for it — a slot with no value renders as
-   * empty text rather than repeating its neighbour.
-   */
-  private valueAt(index: number): number | undefined {
-    return this.sortedMarkers[index]
-  }
-
-  /** Tick `i`'s fraction across the live `range`, 0 at the bottom 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<VerticalAxis, VerticalAxisProps>) {
-    super(props)
-
-    // Composed from plain props (range/markers/label) — no context needed, so
-    // it's built here. super() applied the props, so the reads below resolve.
-    const tickPad = insetsOps.resolve(this.axis.tickPadding).right
-    const titlePad = insetsOps.resolve(this.axis.titlePadding).right
-
-    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)
-        },
-        y: () => {
-          // Node2D space is y-up, so the fraction runs from the bottom.
-          const height = this.layoutBounds.height
-          const centred = (this.fracAt(i) - 0.5) * height
-          // Held inside the axis's top edge — the backstop for a chart whose
-          // headroom is smaller than its marker text is tall, which a theme with
-          // much larger markers can arrange. Only the top, because what lies
-          // below the axis is the chart's own horizontal axis and legend.
-          const limit = height / 2 - marker.layoutBounds.height / 2
-          return Math.min(centred, limit)
-        },
-      })
-      return marker
-    })
-
-    const children: Node2D[] = []
-    if (this.label !== "") {
-      this.labelNode = new Text({
-        ...textOps.styleProps(this.axis.titleStyle),
-        text: this.label,
-      })
-      // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
-      children.push(
-        new RotatedBox({
-          angle: -90,
-          width: "hug",
-          height: "hug",
-          children: this.labelNode,
-        })
-      )
-    }
-    children.push(
-      new Rect({
-        height: "fill",
-        width: "hug",
-        padding: { right: tickPad },
-        children: this.markerNodes,
-      })
-    )
-
-    this.add(new Rect({ flow: "horizontal", gap: titlePad, children }))
-  }
-
-  /**
-   * Primes every marker (and the caption) at its pre-entrance state: shifted
-   * right and transparent. Idempotent, and separate from {@link enter} so the
-   * chart can arm its whole composition before the first frame is drawn.
-   */
-  arm(slide = SLIDE): void {
-    for (const marker of this.markerNodes) marker.set({ opacity: 0, x: slide })
-    this.labelNode?.set({ opacity: 0, x: slide })
-  }
-
-  /**
-   * Stagger the markers in bottom to top, then slide the caption in from the
-   * right after them.
-   *
-   * A {@link Seekable} rather than a generator — see the note on the horizontal
-   * axis's `enter`. The offsets were always static; expressing them as `wait`
-   * inside a generator is what made them reachable only by running it.
-   *
-   * `args.duration` is the **whole** entrance, not one marker's slide: the
-   * stagger and the caption are carved out of it rather than added on top. See
-   * {@link enterBudget} for why that distinction matters here.
-   *
-   * `args.data.stagger` is seconds between successive markers (derived when
-   * omitted); `args.data.slide` is the starting rightward offset in px.
-   */
-  @command()
-  enter(args: CommandArgs<{ stagger?: number; slide?: number }> & { duration: number }): Seekable {
-    const { stagger, slide = SLIDE } = args.data ?? {}
-    const easing = args.easing ?? easeOut()
-    const nodes = this.markerNodes
-    if (nodes.length === 0) return compose([])
-    const { step, per, caption } = enterBudget(
-      args.duration,
-      nodes.length,
-      this.labelNode !== null,
-      stagger
-    )
-
-    this.arm(slide)
-
-    // Bottom marker leads: markerNodes is top → bottom, so walk it in reverse.
-    const markers = nodes.map((node, i) => {
-      const order = nodes.length - 1 - i // bottom-most = 0
-      return at(order * step, node.to({ data: { opacity: 1, x: 0 }, duration: per, easing }))
-    })
-    const lastMarkerEnds = (nodes.length - 1) * step + per
-
-    // Once every marker has landed, the caption slides in from the right.
-    return compose([
-      ...markers,
-      ...(this.labelNode
-        ? [at(lastMarkerEnds, this.labelNode.to({ data: { opacity: 1, x: 0 }, duration: caption, easing }))]
-        : []),
-    ])
-  }
-}
+import {
+  command,
+  Node2D,
+  Rect,
+  RotatedBox,
+  Text,
+  easeOut,
+  property,
+  insetsOps,
+  textOps,
+  type CommandArgs,
+  type NodeConfig,
+  type Node2DProps,
+} from "@motionscript/sdk"
+
+import {
+  DEFAULT_Y_AXIS,
+  enterBudget,
+  formatMarker,
+  type AxisConfig,
+  type Range,
+} from "./shared"
+import { at, compose, type Seekable } from "@motionscript/sdk/component"
+
+export interface VerticalAxisProps extends Node2DProps {
+  /** `[min, max]` of the vertical scale the markers are positioned within. */
+  range: Range
+  /**
+   * Tick values (in data units) to draw up the axis, each placed by its fraction
+   * across {@link VerticalAxisProps.range}. Need not be evenly spaced or include
+   * the ends.
+   */
+  markers: number[]
+  /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */
+  axis: AxisConfig
+  /**
+   * Rotated caption drawn in the gutter to the left of the marker column. Empty
+   * string (the default) hides it — no caption node is built and no label gutter
+   * is reserved.
+   */
+  label: string
+}
+
+/** How far a marker starts to the right of its slot when it enters, in px. */
+const SLIDE = 24
+
+/** How a tick value is captioned — see {@link VerticalAxis.labelFor}. */
+export type MarkerLabel = (value: number) => string
+
+/**
+ * The numeric vertical axis shared by the cartesian charts: a **column of
+ * {@link Text} nodes**, one per marker value, running top-to-bottom (highest
+ * value at the top). Pure layout — no `Graphics` — so the markers are real text
+ * nodes the scene can measure, restyle, or animate individually.
+ *
+ * Each marker is positioned so its centre lands exactly on its value's fraction
+ * across `range` within the axis's filled height, so unevenly-spaced markers
+ * land where their values fall. Both the caption and the position are *bound*,
+ * not snapshotted: a chart that rescales its axes (see `LineChart.zoomTo`)
+ * tweens `range`/`markers` live. Only the marker **count** is fixed at
+ * construction.
+ *
+ * {@link enter} staggers them in **bottom-to-top**: each marker starts pushed a
+ * little to the right and transparent, then fades and slides left into place.
+ * The resting state is the landed one, so a chart that is never told to enter
+ * still reads as a finished chart.
+ */
+export class VerticalAxis extends Node2D<VerticalAxisProps> {
+  @property({ default: () => [0, 1] as Range }) declare range: Range
+  @property({ default: () => [] as number[] }) declare markers: number[]
+  @property({ default: DEFAULT_Y_AXIS }) declare axis: AxisConfig
+  @property({ default: "" }) declare label: string
+
+  /**
+   * How a tick value is captioned. Defaults to the bare numeric reading; a
+   * chart with a number format on this axis replaces it (see `number-format`).
+   *
+   * A plain field rather than a `@property`, for the reason the horizontal
+   * axis's twin spells out: it is a policy, not a value, and there is nothing
+   * to tween between two formatters.
+   */
+  labelFor: MarkerLabel = formatMarker
+
+  /** One text node per marker, ordered top → bottom, for the staggered enter. */
+  private markerNodes: Text[] = []
+  /** The caption node, or null when `label` is empty. Entered after the markers. */
+  private labelNode: Text | null = null
+
+  /** The live tick values, top → bottom (highest first) — re-read every frame. */
+  private get sortedMarkers(): number[] {
+    return [...this.markers].sort((a, b) => b - a)
+  }
+
+  /**
+   * Tick `i`'s value, or `undefined` once the live `markers` list is shorter
+   * than the column of text nodes built for it — a slot with no value renders as
+   * empty text rather than repeating its neighbour.
+   */
+  private valueAt(index: number): number | undefined {
+    return this.sortedMarkers[index]
+  }
+
+  /** Tick `i`'s fraction across the live `range`, 0 at the bottom 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<VerticalAxis, VerticalAxisProps>) {
+    super(props)
+
+    // Composed from plain props (range/markers/label) — no context needed, so
+    // it's built here. super() applied the props, so the reads below resolve.
+    const tickPad = insetsOps.resolve(this.axis.tickPadding).right
+    const titlePad = insetsOps.resolve(this.axis.titlePadding).right
+
+    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)
+        },
+        y: () => {
+          // Node2D space is y-up, so the fraction runs from the bottom.
+          const height = this.layoutBounds.height
+          const centred = (this.fracAt(i) - 0.5) * height
+          // Held inside the axis's top edge — the backstop for a chart whose
+          // headroom is smaller than its marker text is tall, which a theme with
+          // much larger markers can arrange. Only the top, because what lies
+          // below the axis is the chart's own horizontal axis and legend.
+          const limit = height / 2 - marker.layoutBounds.height / 2
+          return Math.min(centred, limit)
+        },
+      })
+      return marker
+    })
+
+    const children: Node2D[] = []
+    if (this.label !== "") {
+      this.labelNode = new Text({
+        ...textOps.styleProps(this.axis.titleStyle),
+        text: this.label,
+      })
+      // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
+      children.push(
+        new RotatedBox({
+          angle: -90,
+          width: "hug",
+          height: "hug",
+          children: this.labelNode,
+        })
+      )
+    }
+    children.push(
+      new Rect({
+        height: "fill",
+        width: "hug",
+        padding: { right: tickPad },
+        children: this.markerNodes,
+      })
+    )
+
+    this.add(new Rect({ flow: "horizontal", gap: titlePad, children }))
+  }
+
+  /**
+   * Primes every marker (and the caption) at its pre-entrance state: shifted
+   * right and transparent. Idempotent, and separate from {@link enter} so the
+   * chart can arm its whole composition before the first frame is drawn.
+   */
+  arm(slide = SLIDE): void {
+    for (const marker of this.markerNodes) marker.set({ opacity: 0, x: slide })
+    this.labelNode?.set({ opacity: 0, x: slide })
+  }
+
+  /**
+   * Stagger the markers in bottom to top, then slide the caption in from the
+   * right after them.
+   *
+   * A {@link Seekable} rather than a generator — see the note on the horizontal
+   * axis's `enter`. The offsets were always static; expressing them as `wait`
+   * inside a generator is what made them reachable only by running it.
+   *
+   * `args.duration` is the **whole** entrance, not one marker's slide: the
+   * stagger and the caption are carved out of it rather than added on top. See
+   * {@link enterBudget} for why that distinction matters here.
+   *
+   * `args.data.stagger` is seconds between successive markers (derived when
+   * omitted); `args.data.slide` is the starting rightward offset in px.
+   */
+  @command()
+  enter(args: CommandArgs<{ stagger?: number; slide?: number }> & { duration: number }): Seekable {
+    const { stagger, slide = SLIDE } = args.data ?? {}
+    const easing = args.easing ?? easeOut()
+    const nodes = this.markerNodes
+    if (nodes.length === 0) return compose([])
+    const { step, per, caption } = enterBudget(
+      args.duration,
+      nodes.length,
+      this.labelNode !== null,
+      stagger
+    )
+
+    this.arm(slide)
+
+    // Bottom marker leads: markerNodes is top → bottom, so walk it in reverse.
+    const markers = nodes.map((node, i) => {
+      const order = nodes.length - 1 - i // bottom-most = 0
+      return at(order * step, node.to({ data: { opacity: 1, x: 0 }, duration: per, easing }))
+    })
+    const lastMarkerEnds = (nodes.length - 1) * step + per
+
+    // Once every marker has landed, the caption slides in from the right.
+    return compose([
+      ...markers,
+      ...(this.labelNode
+        ? [at(lastMarkerEnds, this.labelNode.to({ data: { opacity: 1, x: 0 }, duration: caption, easing }))]
+        : []),
+    ])
+  }
+}