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

package/src/bar-chart/category-axis.ts

@@ -1,177 +1,177 @@
-import {
-  command,
-  Node2D,
-  Rect,
-  Text,
-  easeOut,
-  property,
-  insetsOps,
-  textOps,
-  type CommandArgs,
-  type NodeConfig,
-  type Node2DProps,
-} from "@motionscript/sdk"
-
-import {
-  DEFAULT_X_AXIS,
-  clampUnit,
-  enterBudget,
-  type AxisConfig,
-} from "../kit/shared"
-import { at, compose, hold, type Seekable } from "@motionscript/sdk/component"
-
-export interface CategoryAxisProps extends Node2DProps {
-  /** One caption per category slot, left to right — the chart's rows, in order. */
-  categories: string[]
-  /** Caption/title text style and gutters — see {@link AxisConfig}. */
-  axis: AxisConfig
-  /**
-   * Caption drawn centred in the gutter beneath the category row. Empty string
-   * (the default) hides it.
-   */
-  label: string
-  /**
-   * Per-category opacity multiplier — how the chart's category spotlight reaches
-   * the captions, so the name under a dimmed column dims with it. Missing
-   * entries read as 1.
-   */
-  dims: number[]
-}
-
-/** How far a caption starts above its slot when it enters, in px. */
-const SLIDE = 24
-
-/**
- * The **categorical** horizontal axis of a {@link BarChart}: a row of
- * {@link Text} captions, one per row of the data, each centred on its slot
- * beneath the baseline.
- *
- * Not a variant of the line chart's `HorizontalAxis` and deliberately not
- * folded into it: that axis places markers by *value* across a numeric range,
- * this one divides its width into equal slots and centres a name in each. The
- * two look alike on screen and share nothing underneath — one reads a scale,
- * the other counts rows.
- *
- * The slot arithmetic is the same as the plot's, because this node is laid out
- * to exactly the plot's width (the chart reserves the axis gutter with an
- * invisible twin of the value axis, as the line chart does), so a caption lands
- * under the columns it names without either side being told about the other.
- *
- * {@link enter} staggers the captions in left-to-right, each lifted a little
- * above its slot and transparent; the resting state is the landed one, so a
- * chart that is never told to enter still reads as finished.
- */
-export class CategoryAxis extends Node2D<CategoryAxisProps> {
-  @property({ default: () => [] as string[] }) declare categories: string[]
-  @property({ default: DEFAULT_X_AXIS }) declare axis: AxisConfig
-  @property({ default: "" }) declare label: string
-  @property({ default: () => [] as number[] }) declare dims: number[]
-
-  /** One caption per category, ordered left → right, for the staggered enter. */
-  private captionNodes: Text[] = []
-  /** The axis title, or null when `label` is empty. */
-  private labelNode: Text | null = null
-
-  /** Centre x of slot `i`, in the node's centred space. */
-  private slotCenter(index: number): number {
-    const n = this.categories.length
-    if (n <= 0) return 0
-    const width = this.layoutBounds.width
-    return -width / 2 + (width / n) * (index + 0.5)
-  }
-
-  constructor(props?: NodeConfig<CategoryAxis, CategoryAxisProps>) {
-    super(props)
-
-    const tickPad = insetsOps.resolve(this.axis.tickPadding).top
-    const titlePad = insetsOps.resolve(this.axis.titlePadding).top
-
-    // Each caption sits in a hug box carrying the spotlight dim, so the
-    // entrance can animate the text's own opacity without the two fighting over
-    // one value — opacity multiplies down the tree, which is exactly the
-    // composition wanted here.
-    const slots = this.categories.map((caption, i) => {
-      const text = new Text({
-        ...textOps.styleProps(this.axis.labelStyle),
-        text: caption,
-      })
-      this.captionNodes.push(text)
-      return new Rect({
-        width: "hug",
-        height: "hug",
-        flow: "freeform",
-        opacity: () => clampUnit(this.dims[i] ?? 1),
-        x: () => this.slotCenter(i),
-        children: [text],
-      })
-    })
-
-    const children: Node2D[] = [
-      new Rect({
-        width: "fill",
-        height: "hug",
-        padding: { top: tickPad },
-        children: slots,
-      }),
-    ]
-    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 caption (and the title) at its pre-entrance state: lifted above
-   * its slot and transparent. Idempotent, so the chart can arm its whole
-   * composition before the first frame is drawn.
-   */
-  arm(slide = SLIDE): void {
-    for (const caption of this.captionNodes) caption.set({ opacity: 0, y: slide })
-    this.labelNode?.set({ opacity: 0, y: slide })
-  }
-
-  /**
-   * Slide + fade every caption in from above, staggered left-to-right, then
-   * bring the title down behind them.
-   *
-   * `args.duration` is the **whole** entrance — the stagger and the title are
-   * carved out of it rather than added on top. See {@link enterBudget}.
-   *
-   * `args.data.stagger` is seconds between successive captions (derived when
-   * omitted); `args.data.slide` is the starting upward offset in px (node space
-   * is y-up, so a positive start slides *down* into place).
-   */
-  @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.captionNodes
-    if (nodes.length === 0) return hold(args.duration)
-    const { step, per, caption } = enterBudget(
-      args.duration,
-      nodes.length,
-      this.labelNode !== null,
-      stagger
-    )
-
-    this.arm(slide)
-
-    // The stagger was `wait(i * step)` inside a generator, so its offsets only
-    // existed while it ran. They were always `i * step`; placed, the same
-    // entrance can be asked what it looks like partway through.
-    const lastCaptionEnds = (nodes.length - 1) * step + per
-    return compose([
-      ...nodes.map((node, i) =>
-        at(i * step, node.to({ data: { opacity: 1, y: 0 }, duration: per, easing }))
-      ),
-      ...(this.labelNode
-        ? [at(lastCaptionEnds, 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,
+  clampUnit,
+  enterBudget,
+  type AxisConfig,
+} from "../kit/shared"
+import { at, compose, hold, type Seekable } from "@motionscript/sdk/component"
+
+export interface CategoryAxisProps extends Node2DProps {
+  /** One caption per category slot, left to right — the chart's rows, in order. */
+  categories: string[]
+  /** Caption/title text style and gutters — see {@link AxisConfig}. */
+  axis: AxisConfig
+  /**
+   * Caption drawn centred in the gutter beneath the category row. Empty string
+   * (the default) hides it.
+   */
+  label: string
+  /**
+   * Per-category opacity multiplier — how the chart's category spotlight reaches
+   * the captions, so the name under a dimmed column dims with it. Missing
+   * entries read as 1.
+   */
+  dims: number[]
+}
+
+/** How far a caption starts above its slot when it enters, in px. */
+const SLIDE = 24
+
+/**
+ * The **categorical** horizontal axis of a {@link BarChart}: a row of
+ * {@link Text} captions, one per row of the data, each centred on its slot
+ * beneath the baseline.
+ *
+ * Not a variant of the line chart's `HorizontalAxis` and deliberately not
+ * folded into it: that axis places markers by *value* across a numeric range,
+ * this one divides its width into equal slots and centres a name in each. The
+ * two look alike on screen and share nothing underneath — one reads a scale,
+ * the other counts rows.
+ *
+ * The slot arithmetic is the same as the plot's, because this node is laid out
+ * to exactly the plot's width (the chart reserves the axis gutter with an
+ * invisible twin of the value axis, as the line chart does), so a caption lands
+ * under the columns it names without either side being told about the other.
+ *
+ * {@link enter} staggers the captions in left-to-right, each lifted a little
+ * above its slot and transparent; the resting state is the landed one, so a
+ * chart that is never told to enter still reads as finished.
+ */
+export class CategoryAxis extends Node2D<CategoryAxisProps> {
+  @property({ default: () => [] as string[] }) declare categories: string[]
+  @property({ default: DEFAULT_X_AXIS }) declare axis: AxisConfig
+  @property({ default: "" }) declare label: string
+  @property({ default: () => [] as number[] }) declare dims: number[]
+
+  /** One caption per category, ordered left → right, for the staggered enter. */
+  private captionNodes: Text[] = []
+  /** The axis title, or null when `label` is empty. */
+  private labelNode: Text | null = null
+
+  /** Centre x of slot `i`, in the node's centred space. */
+  private slotCenter(index: number): number {
+    const n = this.categories.length
+    if (n <= 0) return 0
+    const width = this.layoutBounds.width
+    return -width / 2 + (width / n) * (index + 0.5)
+  }
+
+  constructor(props?: NodeConfig<CategoryAxis, CategoryAxisProps>) {
+    super(props)
+
+    const tickPad = insetsOps.resolve(this.axis.tickPadding).top
+    const titlePad = insetsOps.resolve(this.axis.titlePadding).top
+
+    // Each caption sits in a hug box carrying the spotlight dim, so the
+    // entrance can animate the text's own opacity without the two fighting over
+    // one value — opacity multiplies down the tree, which is exactly the
+    // composition wanted here.
+    const slots = this.categories.map((caption, i) => {
+      const text = new Text({
+        ...textOps.styleProps(this.axis.labelStyle),
+        text: caption,
+      })
+      this.captionNodes.push(text)
+      return new Rect({
+        width: "hug",
+        height: "hug",
+        flow: "freeform",
+        opacity: () => clampUnit(this.dims[i] ?? 1),
+        x: () => this.slotCenter(i),
+        children: [text],
+      })
+    })
+
+    const children: Node2D[] = [
+      new Rect({
+        width: "fill",
+        height: "hug",
+        padding: { top: tickPad },
+        children: slots,
+      }),
+    ]
+    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 caption (and the title) at its pre-entrance state: lifted above
+   * its slot and transparent. Idempotent, so the chart can arm its whole
+   * composition before the first frame is drawn.
+   */
+  arm(slide = SLIDE): void {
+    for (const caption of this.captionNodes) caption.set({ opacity: 0, y: slide })
+    this.labelNode?.set({ opacity: 0, y: slide })
+  }
+
+  /**
+   * Slide + fade every caption in from above, staggered left-to-right, then
+   * bring the title down behind them.
+   *
+   * `args.duration` is the **whole** entrance — the stagger and the title are
+   * carved out of it rather than added on top. See {@link enterBudget}.
+   *
+   * `args.data.stagger` is seconds between successive captions (derived when
+   * omitted); `args.data.slide` is the starting upward offset in px (node space
+   * is y-up, so a positive start slides *down* into place).
+   */
+  @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.captionNodes
+    if (nodes.length === 0) return hold(args.duration)
+    const { step, per, caption } = enterBudget(
+      args.duration,
+      nodes.length,
+      this.labelNode !== null,
+      stagger
+    )
+
+    this.arm(slide)
+
+    // The stagger was `wait(i * step)` inside a generator, so its offsets only
+    // existed while it ran. They were always `i * step`; placed, the same
+    // entrance can be asked what it looks like partway through.
+    const lastCaptionEnds = (nodes.length - 1) * step + per
+    return compose([
+      ...nodes.map((node, i) =>
+        at(i * step, node.to({ data: { opacity: 1, y: 0 }, duration: per, easing }))
+      ),
+      ...(this.labelNode
+        ? [at(lastCaptionEnds, this.labelNode.to({ data: { opacity: 1, y: 0 }, duration: caption, easing }))]
+        : []),
+    ])
+  }
+}