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

package/src/bar-chart/chart-bars.ts

@@ -1,310 +1,310 @@
-import {
-  command,
-  type AssetScope,
-  Graphics2D,
-  Node2D,
-  Text,
-  easeOut,
-  fillOps,
-  shadowOps,
-  strokeOps,
-  property,
-  textOps,
-  type Command,
-  type CommandArgs,
-  type Fill,
-  type NodeConfig,
-  type Node2DProps,
-  type RenderContext2D,
-  type Shadow,
-  type ShadowResolved,
-  type Stroke,
-  type StrokeResolved,
-  type TextStyle,
-} from "@motionscript/sdk"
-
-import { clampUnit, formatMarker } from "../kit/shared"
-import type { MarkerLabel } from "../kit/vertical-axis"
-import { DEFAULT_BAR_CHART_THEME } from "./shared"
-import { declarePaints } from "@motionscript/sdk/component"
-
-/**
- * One drawn column, already mapped into the plot's **centred pixel space**
- * (origin at the plot centre, y-up) by the parent {@link BarChart}.
- *
- * `from`/`to` are the two ends of the column rather than a base and a height,
- * for the same reason {@link BarSpan} is a span: it is the one shape that fits a
- * grouped bar, a stacked segment and a negative value without a special case.
- */
-export interface BarGeometry {
-  /** Centre x of the column. */
-  x: number
-  /** Column width in px. */
-  width: number
-  /** Pixel y of the column's base — the baseline when grouped, the running stack top when stacked. */
-  from: number
-  /** Pixel y of its far end, at full {@link ChartBars.growth}. */
-  to: number
-  /** Whether the far end takes the theme's corner radius (the stack's cap). */
-  round: boolean
-  /** The value this column plots, for the figure printed on it. */
-  value: number
-}
-
-/** Gap between a grouped column's end and the figure printed over it, in px. */
-const VALUE_GAP = 10
-/** A segment shorter than this many multiples of the type size prints no figure. */
-const VALUE_FIT = 1.6
-/** Fallback type size when the theme's value style leaves it unset or autofit. */
-const VALUE_SIZE = 24
-
-export interface ChartBarsProps extends Node2DProps {
-  /** This series' columns, one per row of the chart's data. */
-  bars: BarGeometry[]
-  /** Pixel y of value 0 — where every column grows *from*. */
-  baseline: number
-  /** Column paint — this series' own, or the theme palette's entry for its index. */
-  fill: Fill
-  /** Optional outline on every column. */
-  barStroke: Stroke
-  /** Optional drop shadow on every column. */
-  barShadow: Shadow
-  /** Radius of the far-end corners, in px. */
-  cornerRadius: number
-  /**
-   * Rise of every column in `[0, 1]`, measured **about the baseline**: 0
-   * collapses them all onto it, 1 draws them at full length.
-   *
-   * Scaling about the baseline rather than about each column's own base is what
-   * keeps a stack flush mid-animation — every segment's base and end travel by
-   * the same factor, so the segments stay stacked instead of the upper ones
-   * floating above the still-growing lower ones. It also means a negative
-   * column grows *down* out of the same signal.
-   */
-  growth: number
-  /**
-   * Per-column opacity multiplier, by row index — how the chart's category
-   * spotlight reaches a single column without touching the series it belongs
-   * to. Missing entries read as 1.
-   */
-  dims: number[]
-  /** Whether the figure each column plots is printed on it. */
-  showValues: boolean
-  /** Type style for those figures. */
-  valueStyle: TextStyle
-  /**
-   * Whether this series draws at all — the wholesale switch behind
-   * `BarChart.showSeries`/`hideSeries`, alongside the slot weight that animates
-   * the reflow. Off skips the columns *and* their figures.
-   */
-  enabled: boolean
-}
-
-/**
- * One **series** of a {@link BarChart}, drawn as one command list: its column in
- * every category, plus the figures printed on them.
- *
- * A node per series rather than a node per bar, deliberately — it is the same
- * unit `ChartLine` is, which is what lets `showSeries`/`hideSeries`/
- * `spotlightSeries` mean exactly the same thing on a bar chart as on a line
- * chart: enable the node, or tween its opacity. The columns' *positions* come
- * from the parent (it owns the slot arithmetic both modes share), so this part
- * only has to know how to draw a span and grow it.
- *
- * The figures are real {@link Text} children rather than glyphs in the command
- * list, so they take the theme's type style, are measured by the layout engine,
- * and ride the node's own opacity — which is why hiding the series takes its
- * figures with it for free.
- */
-export class ChartBars extends Node2D<ChartBarsProps> {
-  @property({ default: () => [] as BarGeometry[] }) declare bars: BarGeometry[]
-  @property({ default: 0 }) declare baseline: number
-  @property({
-    default: [],
-    mapper: fillOps.resolve,
-    tween: fillOps.lerp,
-  })
-  declare fill: Fill
-  @property({
-    default: DEFAULT_BAR_CHART_THEME.bar.stroke,
-    mapper: strokeOps.resolve,
-    tween: strokeOps.lerp,
-  })
-  declare barStroke: Stroke
-  @property({
-    default: DEFAULT_BAR_CHART_THEME.bar.shadow,
-    mapper: shadowOps.resolve,
-    tween: shadowOps.lerp,
-  })
-  declare barShadow: Shadow
-  @property({ default: DEFAULT_BAR_CHART_THEME.bar.cornerRadius })
-  declare cornerRadius: number
-  @property({ default: 1 }) declare growth: number
-  @property({ default: () => [] as number[] }) declare dims: number[]
-  @property({ default: false }) declare showValues: boolean
-  @property({ default: DEFAULT_BAR_CHART_THEME.valueStyle })
-  declare valueStyle: TextStyle
-  @property({ default: true }) declare enabled: boolean
-
-  /**
-   * How a column's figure is written down — the same seam the two axes carry,
-   * so a chart's value axis and the numbers printed on its bars can't end up
-   * saying `$1,200` in one place and `1200` in the other.
-   */
-  labelFor: MarkerLabel = formatMarker
-
-  constructor(props?: NodeConfig<ChartBars, ChartBarsProps>) {
-    super(props)
-
-    // One caption per column, built once (the row count is fixed at
-    // construction, like an axis's marker count) and bound to the live geometry
-    // so it travels with its column as the chart grows, rescales or reflows.
-    if (!this.showValues) return
-    for (let i = 0; i < this.bars.length; i++) {
-      this.add(
-        new Text({
-          ...textOps.styleProps(this.valueStyle),
-          text: () => this.captionAt(i),
-          x: () => this.bars[i]?.x ?? 0,
-          y: () => this.captionY(i),
-          opacity: () => this.dimAt(i),
-        })
-      )
-    }
-  }
-
-  /**
-   * How far column `i` is dimmed — the chart's category spotlight, and the
-   * series switch on top of it.
-   *
-   * The captions read this rather than being hidden by `renderSelf`'s guard:
-   * they are real child nodes, so a `return` in the draw pass would leave them
-   * on screen over a series that isn't there.
-   */
-  private dimAt(index: number): number {
-    if (!this.enabled) return 0
-    return clampUnit(this.dims[index] ?? 1)
-  }
-
-  /** The two ends of column `i` at the current {@link growth}. */
-  private endsAt(index: number): { base: number; end: number } | null {
-    const bar = this.bars[index]
-    if (!bar) return null
-    const g = clampUnit(this.growth)
-    const base = this.baseline + (bar.from - this.baseline) * g
-    const end = this.baseline + (bar.to - this.baseline) * g
-    return { base, end }
-  }
-
-  /** The type size the figures are set at, guarding the autofit/unset cases. */
-  private get valueSize(): number {
-    const size = this.valueStyle.fontSize
-    return typeof size === "number" ? size : VALUE_SIZE
-  }
-
-  /**
-   * The figure printed on column `i`, or `""` where there is no room for it.
-   *
-   * Blanking the text rather than dropping the node keeps the caption list
-   * index-aligned with the columns, so a chart that rescales into more room
-   * simply starts printing again.
-   */
-  private captionAt(index: number): string {
-    const bar = this.bars[index]
-    if (!bar || bar.value === 0) return ""
-    // An interior segment prints inside itself, so it has to be tall enough to
-    // hold a line of type; a grouped column prints in the headroom above its
-    // end, where the only constraint is the plot's own top.
-    if (this.insideAt(index)) {
-      const ends = this.endsAt(index)
-      if (!ends) return ""
-      if (Math.abs(ends.end - ends.base) < this.valueSize * VALUE_FIT) return ""
-    }
-    return this.labelFor(bar.value)
-  }
-
-  /** Whether column `i`'s figure sits inside the column (a stacked segment) or past its end. */
-  private insideAt(index: number): boolean {
-    const bar = this.bars[index]
-    return bar !== undefined && Math.abs(bar.from - this.baseline) > 0.5
-  }
-
-  /** Where column `i`'s figure sits, in the node's centred y-up space. */
-  private captionY(index: number): number {
-    const ends = this.endsAt(index)
-    if (!ends) return 0
-    if (this.insideAt(index)) return (ends.base + ends.end) / 2
-    // Text is centred on its `y`, so clear the column's end by the gap plus half
-    // a line — on whichever side of the baseline the column actually reached.
-    const direction = ends.end >= ends.base ? 1 : -1
-    return ends.end + direction * (VALUE_GAP + this.valueSize / 2)
-  }
-
-  /**
-   * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
-   * paint props it carries — see {@link declarePaints}. The column stroke and
-   * shadow are named past the conventional slots, so they are passed explicitly.
-   */
-  override declareAssets(assets: AssetScope): void {
-    super.declareAssets(assets)
-    declarePaints(this, assets, {
-      fills: (this.barShadow as ShadowResolved[]).map((shadow) => shadow.fill),
-      strokes: [this.barStroke as StrokeResolved[]],
-    })
-  }
-
-  protected renderSelf(ctx: RenderContext2D): void {
-    if (!this.enabled) return
-    for (let i = 0; i < this.bars.length; i++) {
-      const bar = this.bars[i]
-      const ends = this.endsAt(i)
-      if (!ends || bar.width <= 0) continue
-      const height = Math.abs(ends.end - ends.base)
-      if (height <= 0) continue
-
-      const radius = bar.round ? Math.min(this.cornerRadius, height) : 0
-      // A column per `Graphics2D` rather than one list for the series: the
-      // category spotlight dims individual columns, and opacity is a property
-      // of the command list rather than of a shape within it.
-      const g = new Graphics2D()
-      const rect = g.rect({
-        x: bar.x,
-        y: (ends.base + ends.end) / 2,
-        width: bar.width,
-        height,
-        // This node's space is y-up, but the renderer's corner-radius keys are
-        // labelled in canvas y-down space — so a column reaching *up* rounds
-        // through the `bottom*` keys, and one reaching down through the `top*`
-        // ones. Only the far end rounds, which is what makes a stack read as a
-        // single capped column.
-        cornerRadius:
-          radius > 0
-            ? ends.end >= ends.base
-              ? { bottomLeft: radius, bottomRight: radius, topLeft: 0, topRight: 0 }
-              : { topLeft: radius, topRight: radius, bottomLeft: 0, bottomRight: 0 }
-            : 0,
-      })
-      rect.shadow(this.barShadow)
-      rect.fill(this.fill)
-      rect.stroke(this.barStroke)
-      ctx.draw(g.opacity(this.dimAt(i)))
-    }
-  }
-
-  /**
-   * Raise every column from the baseline by tweening {@link growth} `0 → 1`.
-   *
-   * The mirror of `ChartLine.enter`: same signature, same contract that the
-   * resting state is the finished one, so the chart arms this back to 0 before
-   * animating rather than the node hiding itself at construction.
-   */
-  @command()
-  enter(args: CommandArgs<Record<string, never>> & { duration: number }): Command<ChartBarsGrowth> {
-    // No priming to 0 first: the value at `t` is a function of `t`, so a repeat
-    // call re-raises by definition rather than by having reset something.
-    return this.command<ChartBarsGrowth>((t) => ({ growth: t }), args.duration, args.easing ?? easeOut())
-  }
-}
-
-/** The one signal {@link ChartBars.enter} moves. */
-type ChartBarsGrowth = { growth: number }
+import {
+  command,
+  type AssetScope,
+  Graphics2D,
+  Node2D,
+  Text,
+  easeOut,
+  fillOps,
+  shadowOps,
+  strokeOps,
+  property,
+  textOps,
+  type Command,
+  type CommandArgs,
+  type Fill,
+  type NodeConfig,
+  type Node2DProps,
+  type RenderContext2D,
+  type Shadow,
+  type ShadowResolved,
+  type Stroke,
+  type StrokeResolved,
+  type TextStyle,
+} from "@motionscript/sdk"
+
+import { clampUnit, formatMarker } from "../kit/shared"
+import type { MarkerLabel } from "../kit/vertical-axis"
+import { DEFAULT_BAR_CHART_THEME } from "./shared"
+import { declarePaints } from "@motionscript/sdk/component"
+
+/**
+ * One drawn column, already mapped into the plot's **centred pixel space**
+ * (origin at the plot centre, y-up) by the parent {@link BarChart}.
+ *
+ * `from`/`to` are the two ends of the column rather than a base and a height,
+ * for the same reason {@link BarSpan} is a span: it is the one shape that fits a
+ * grouped bar, a stacked segment and a negative value without a special case.
+ */
+export interface BarGeometry {
+  /** Centre x of the column. */
+  x: number
+  /** Column width in px. */
+  width: number
+  /** Pixel y of the column's base — the baseline when grouped, the running stack top when stacked. */
+  from: number
+  /** Pixel y of its far end, at full {@link ChartBars.growth}. */
+  to: number
+  /** Whether the far end takes the theme's corner radius (the stack's cap). */
+  round: boolean
+  /** The value this column plots, for the figure printed on it. */
+  value: number
+}
+
+/** Gap between a grouped column's end and the figure printed over it, in px. */
+const VALUE_GAP = 10
+/** A segment shorter than this many multiples of the type size prints no figure. */
+const VALUE_FIT = 1.6
+/** Fallback type size when the theme's value style leaves it unset or autofit. */
+const VALUE_SIZE = 24
+
+export interface ChartBarsProps extends Node2DProps {
+  /** This series' columns, one per row of the chart's data. */
+  bars: BarGeometry[]
+  /** Pixel y of value 0 — where every column grows *from*. */
+  baseline: number
+  /** Column paint — this series' own, or the theme palette's entry for its index. */
+  fill: Fill
+  /** Optional outline on every column. */
+  barStroke: Stroke
+  /** Optional drop shadow on every column. */
+  barShadow: Shadow
+  /** Radius of the far-end corners, in px. */
+  cornerRadius: number
+  /**
+   * Rise of every column in `[0, 1]`, measured **about the baseline**: 0
+   * collapses them all onto it, 1 draws them at full length.
+   *
+   * Scaling about the baseline rather than about each column's own base is what
+   * keeps a stack flush mid-animation — every segment's base and end travel by
+   * the same factor, so the segments stay stacked instead of the upper ones
+   * floating above the still-growing lower ones. It also means a negative
+   * column grows *down* out of the same signal.
+   */
+  growth: number
+  /**
+   * Per-column opacity multiplier, by row index — how the chart's category
+   * spotlight reaches a single column without touching the series it belongs
+   * to. Missing entries read as 1.
+   */
+  dims: number[]
+  /** Whether the figure each column plots is printed on it. */
+  showValues: boolean
+  /** Type style for those figures. */
+  valueStyle: TextStyle
+  /**
+   * Whether this series draws at all — the wholesale switch behind
+   * `BarChart.showSeries`/`hideSeries`, alongside the slot weight that animates
+   * the reflow. Off skips the columns *and* their figures.
+   */
+  enabled: boolean
+}
+
+/**
+ * One **series** of a {@link BarChart}, drawn as one command list: its column in
+ * every category, plus the figures printed on them.
+ *
+ * A node per series rather than a node per bar, deliberately — it is the same
+ * unit `ChartLine` is, which is what lets `showSeries`/`hideSeries`/
+ * `spotlightSeries` mean exactly the same thing on a bar chart as on a line
+ * chart: enable the node, or tween its opacity. The columns' *positions* come
+ * from the parent (it owns the slot arithmetic both modes share), so this part
+ * only has to know how to draw a span and grow it.
+ *
+ * The figures are real {@link Text} children rather than glyphs in the command
+ * list, so they take the theme's type style, are measured by the layout engine,
+ * and ride the node's own opacity — which is why hiding the series takes its
+ * figures with it for free.
+ */
+export class ChartBars extends Node2D<ChartBarsProps> {
+  @property({ default: () => [] as BarGeometry[] }) declare bars: BarGeometry[]
+  @property({ default: 0 }) declare baseline: number
+  @property({
+    default: [],
+    mapper: fillOps.resolve,
+    tween: fillOps.lerp,
+  })
+  declare fill: Fill
+  @property({
+    default: DEFAULT_BAR_CHART_THEME.bar.stroke,
+    mapper: strokeOps.resolve,
+    tween: strokeOps.lerp,
+  })
+  declare barStroke: Stroke
+  @property({
+    default: DEFAULT_BAR_CHART_THEME.bar.shadow,
+    mapper: shadowOps.resolve,
+    tween: shadowOps.lerp,
+  })
+  declare barShadow: Shadow
+  @property({ default: DEFAULT_BAR_CHART_THEME.bar.cornerRadius })
+  declare cornerRadius: number
+  @property({ default: 1 }) declare growth: number
+  @property({ default: () => [] as number[] }) declare dims: number[]
+  @property({ default: false }) declare showValues: boolean
+  @property({ default: DEFAULT_BAR_CHART_THEME.valueStyle })
+  declare valueStyle: TextStyle
+  @property({ default: true }) declare enabled: boolean
+
+  /**
+   * How a column's figure is written down — the same seam the two axes carry,
+   * so a chart's value axis and the numbers printed on its bars can't end up
+   * saying `$1,200` in one place and `1200` in the other.
+   */
+  labelFor: MarkerLabel = formatMarker
+
+  constructor(props?: NodeConfig<ChartBars, ChartBarsProps>) {
+    super(props)
+
+    // One caption per column, built once (the row count is fixed at
+    // construction, like an axis's marker count) and bound to the live geometry
+    // so it travels with its column as the chart grows, rescales or reflows.
+    if (!this.showValues) return
+    for (let i = 0; i < this.bars.length; i++) {
+      this.add(
+        new Text({
+          ...textOps.styleProps(this.valueStyle),
+          text: () => this.captionAt(i),
+          x: () => this.bars[i]?.x ?? 0,
+          y: () => this.captionY(i),
+          opacity: () => this.dimAt(i),
+        })
+      )
+    }
+  }
+
+  /**
+   * How far column `i` is dimmed — the chart's category spotlight, and the
+   * series switch on top of it.
+   *
+   * The captions read this rather than being hidden by `renderSelf`'s guard:
+   * they are real child nodes, so a `return` in the draw pass would leave them
+   * on screen over a series that isn't there.
+   */
+  private dimAt(index: number): number {
+    if (!this.enabled) return 0
+    return clampUnit(this.dims[index] ?? 1)
+  }
+
+  /** The two ends of column `i` at the current {@link growth}. */
+  private endsAt(index: number): { base: number; end: number } | null {
+    const bar = this.bars[index]
+    if (!bar) return null
+    const g = clampUnit(this.growth)
+    const base = this.baseline + (bar.from - this.baseline) * g
+    const end = this.baseline + (bar.to - this.baseline) * g
+    return { base, end }
+  }
+
+  /** The type size the figures are set at, guarding the autofit/unset cases. */
+  private get valueSize(): number {
+    const size = this.valueStyle.fontSize
+    return typeof size === "number" ? size : VALUE_SIZE
+  }
+
+  /**
+   * The figure printed on column `i`, or `""` where there is no room for it.
+   *
+   * Blanking the text rather than dropping the node keeps the caption list
+   * index-aligned with the columns, so a chart that rescales into more room
+   * simply starts printing again.
+   */
+  private captionAt(index: number): string {
+    const bar = this.bars[index]
+    if (!bar || bar.value === 0) return ""
+    // An interior segment prints inside itself, so it has to be tall enough to
+    // hold a line of type; a grouped column prints in the headroom above its
+    // end, where the only constraint is the plot's own top.
+    if (this.insideAt(index)) {
+      const ends = this.endsAt(index)
+      if (!ends) return ""
+      if (Math.abs(ends.end - ends.base) < this.valueSize * VALUE_FIT) return ""
+    }
+    return this.labelFor(bar.value)
+  }
+
+  /** Whether column `i`'s figure sits inside the column (a stacked segment) or past its end. */
+  private insideAt(index: number): boolean {
+    const bar = this.bars[index]
+    return bar !== undefined && Math.abs(bar.from - this.baseline) > 0.5
+  }
+
+  /** Where column `i`'s figure sits, in the node's centred y-up space. */
+  private captionY(index: number): number {
+    const ends = this.endsAt(index)
+    if (!ends) return 0
+    if (this.insideAt(index)) return (ends.base + ends.end) / 2
+    // Text is centred on its `y`, so clear the column's end by the gap plus half
+    // a line — on whichever side of the baseline the column actually reached.
+    const direction = ends.end >= ends.base ? 1 : -1
+    return ends.end + direction * (VALUE_GAP + this.valueSize / 2)
+  }
+
+  /**
+   * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
+   * paint props it carries — see {@link declarePaints}. The column stroke and
+   * shadow are named past the conventional slots, so they are passed explicitly.
+   */
+  override declareAssets(assets: AssetScope): void {
+    super.declareAssets(assets)
+    declarePaints(this, assets, {
+      fills: (this.barShadow as ShadowResolved[]).map((shadow) => shadow.fill),
+      strokes: [this.barStroke as StrokeResolved[]],
+    })
+  }
+
+  protected renderSelf(ctx: RenderContext2D): void {
+    if (!this.enabled) return
+    for (let i = 0; i < this.bars.length; i++) {
+      const bar = this.bars[i]
+      const ends = this.endsAt(i)
+      if (!ends || bar.width <= 0) continue
+      const height = Math.abs(ends.end - ends.base)
+      if (height <= 0) continue
+
+      const radius = bar.round ? Math.min(this.cornerRadius, height) : 0
+      // A column per `Graphics2D` rather than one list for the series: the
+      // category spotlight dims individual columns, and opacity is a property
+      // of the command list rather than of a shape within it.
+      const g = new Graphics2D()
+      const rect = g.rect({
+        x: bar.x,
+        y: (ends.base + ends.end) / 2,
+        width: bar.width,
+        height,
+        // This node's space is y-up, but the renderer's corner-radius keys are
+        // labelled in canvas y-down space — so a column reaching *up* rounds
+        // through the `bottom*` keys, and one reaching down through the `top*`
+        // ones. Only the far end rounds, which is what makes a stack read as a
+        // single capped column.
+        cornerRadius:
+          radius > 0
+            ? ends.end >= ends.base
+              ? { bottomLeft: radius, bottomRight: radius, topLeft: 0, topRight: 0 }
+              : { topLeft: radius, topRight: radius, bottomLeft: 0, bottomRight: 0 }
+            : 0,
+      })
+      rect.shadow(this.barShadow)
+      rect.fill(this.fill)
+      rect.stroke(this.barStroke)
+      ctx.draw(g.opacity(this.dimAt(i)))
+    }
+  }
+
+  /**
+   * Raise every column from the baseline by tweening {@link growth} `0 → 1`.
+   *
+   * The mirror of `ChartLine.enter`: same signature, same contract that the
+   * resting state is the finished one, so the chart arms this back to 0 before
+   * animating rather than the node hiding itself at construction.
+   */
+  @command()
+  enter(args: CommandArgs<Record<string, never>> & { duration: number }): Command<ChartBarsGrowth> {
+    // No priming to 0 first: the value at `t` is a function of `t`, so a repeat
+    // call re-raises by definition rather than by having reset something.
+    return this.command<ChartBarsGrowth>((t) => ({ growth: t }), args.duration, args.easing ?? easeOut())
+  }
+}
+
+/** The one signal {@link ChartBars.enter} moves. */
+type ChartBarsGrowth = { growth: number }