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

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

@@ -0,0 +1,177 @@
+import {
+  command,
+  Node2D,
+  Rect,
+  Text,
+  easeOut,
+  property,
+  insetsOps,
+  textOps,
+  type CommandArgs,
+  type NodeConfig,
+  type Node2DProps,
+} from "@motionscript/core"
+
+import {
+  DEFAULT_X_AXIS,
+  clampUnit,
+  enterBudget,
+  type AxisConfig,
+} from "../kit/shared"
+import { at, compose, hold, type Seekable } from "@motionscript/core/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 }))]
+        : []),
+    ])
+  }
+}

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

@@ -0,0 +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/core"
+
+import { clampUnit, formatMarker } from "../kit/shared"
+import type { MarkerLabel } from "../kit/vertical-axis"
+import { DEFAULT_BAR_CHART_THEME } from "./shared"
+import { declarePaints } from "@motionscript/core/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 }

package/src/bar-chart/index.ts

@@ -0,0 +1,31 @@
+/**
+ * The bar chart: grouped or stacked columns off a category axis.
+ *
+ * Shares the plot panel, the value axis and the legend with the line chart —
+ * which is what lets a scene swap one for the other without re-theming — and
+ * brings its own category axis, since a band scale is not a continuous one.
+ */
+export { BarChart } from "./bar-chart"
+export type { BarChartProps } from "./bar-chart"
+export { ChartBars } from "./chart-bars"
+export type { BarGeometry, ChartBarsProps } from "./chart-bars"
+export { CategoryAxis } from "./category-axis"
+export type { CategoryAxisProps } from "./category-axis"
+export {
+  DEFAULT_BAR_CHART_THEME,
+  barCategories,
+  barSpans,
+  barValueExtent,
+  lerpBarChartTheme,
+  resolveBarChartTheme,
+  resolveBarFill,
+  resolveBarScale,
+  stackCapIndex,
+} from "./shared"
+export type {
+  BarChartConfig,
+  BarChartTheme,
+  BarSeries,
+  BarSpan,
+  BarStyleConfig,
+} from "./shared"