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

package/src/kit/chart-legend.ts

@@ -0,0 +1,250 @@
+import {
+  Rect,
+  Text,
+  command,
+  easeOut,
+  property,
+  textOps,
+  type CommandArgs,
+  type EasingFunction,
+  type Fill,
+  type NodeConfig,
+  type RectProps,
+} from "@motionscript/core"
+
+import { drive, hold, together, type Seekable } from "@motionscript/core/component"
+
+import {
+  DEFAULT_LEGEND,
+  SPOTLIGHT_DIM,
+  type ChartSeries,
+  type LegendConfig,
+} from "./shared"
+
+export interface ChartLegendProps extends RectProps {
+  /**
+   * One entry per series: legend `label`, its `enabled` default, and — through
+   * {@link ChartLegendProps.swatches} — the colour its chip is painted. A series
+   * that starts enabled (the default) is added to the row up front; one that
+   * starts `false` is hidden until a later {@link ChartLegend.showSeries}.
+   */
+  series: ChartSeries[]
+  /**
+   * The swatch colour for each series, by index — resolved by the chart, whose
+   * business it is whether a series' colour comes out of a stroke palette (a
+   * line) or a fill palette (a bar). Shorter than the series list means the
+   * missing entries fall back to white.
+   */
+  swatches: Fill[]
+  /** Padding, caption style, gaps, and swatch geometry — see {@link LegendConfig}. */
+  legend: LegendConfig
+}
+
+/**
+ * The legend of a chart: a **horizontal-flow row of entries**, one per series, laid out
+ * left-to-right with the theme's `itemGap`. Each entry pairs the series label
+ * with a rounded colour swatch; only the swatch carries the series colour, the
+ * caption reads in the legend's neutral ink.
+ *
+ * {@link showSeries}/{@link hideSeries} flip a series on or off — showing one
+ * adds its entry back into the row at its stable series position and grows it
+ * in, hiding one shrinks it away and removes it. So the row only ever holds the
+ * currently-enabled series, in series order, and closes the gap when one leaves.
+ *
+ * This node *is* the row, so the parent places it (centred below the chart) and
+ * it hugs its entries.
+ */
+export class ChartLegend extends Rect {
+  @property({ default: () => [] as ChartSeries[] }) declare series: ChartSeries[]
+  @property({ default: () => [] as Fill[] }) declare swatches: Fill[]
+  @property({ default: DEFAULT_LEGEND }) declare legend: LegendConfig
+
+  /** One entry per series. **Every** entry is a child — see {@link reveal}. */
+  private items: Rect[] = []
+  /**
+   * How far each entry is shown, `0`–`1`. Drives its width, opacity and gap
+   * together, so `0` is an entry that takes no room and `1` is one at its
+   * natural size.
+   *
+   * This replaces adding and removing the entry from the row, which is what
+   * `showSeries`/`hideSeries` used to do. That could not be a command: a command
+   * is asked what it looks like at a time, and "is this node a child" is not a
+   * value a time can produce — the tree either contains it or it doesn't, and
+   * getting there means having run the add. Collapsed-but-present is the same
+   * picture reached by a route that *is* a function of `t`.
+   *
+   * A plain array rather than reactive props because the count is the series
+   * count, which is data. The entries' props are bound to it, so writing one
+   * still moves the layout.
+   */
+  private reveal: number[] = []
+  /**
+   * Each entry's natural width, last time it was fully shown.
+   *
+   * A collapse needs numeric endpoints — `lerpSizeInput` snaps between a token
+   * and a number rather than interpolating — and `"hug"` is not a number until
+   * something measures it. Refreshed on every frame an entry is at full reveal
+   * (see {@link widthFor}), so it is current by the time a hide starts, and it
+   * tracks a relabelled series or a restyled legend without being told.
+   */
+  private natural: number[] = []
+
+  constructor(props?: NodeConfig<ChartLegend, ChartLegendProps>) {
+    // `flow` after the spread, with the rest of the geometry: this class *is*
+    // the row, so the direction is its own answer and not the caller's. It has
+    // to be stated — a `Rect` given no flow lays its children out `freeform`,
+    // which stacks every entry on the same spot. One series looks perfect that
+    // way and three look like one smeared caption, so the failure only shows up
+    // on the charts that most need a legend.
+    super({
+      ...(props as RectProps),
+      flow: "horizontal",
+      align: "center",
+      width: "hug",
+      height: "hug",
+    })
+
+    // Structure is one entry per series, so it's composed here from the resolved
+    // props super() applied. Fixed row geometry last, so it wins over super().
+    this.set({ gap: this.legend.itemGap, padding: this.legend.padding })
+
+    this.reveal = this.series.map((s) => ((s.enabled ?? true) ? 1 : 0))
+    this.natural = this.series.map(() => 0)
+    this.items = this.series.map((s, i) => this.buildItem(s, i))
+
+    // All of them, in series order. Order is now fixed rather than depending on
+    // which siblings happen to be shown, so an entry always comes back where it
+    // belongs and `insertionIndex` has nothing left to compute.
+    for (const item of this.items) this.add(item)
+  }
+
+  /**
+   * An entry's width for its current reveal.
+   *
+   * `"hug"` at full reveal rather than the pinned number, so a shown entry stays
+   * responsive to its own content; the number only takes over while it is
+   * collapsing, which is the only time a token cannot express it.
+   *
+   * Records the natural width as a side effect, which is the honest place for it:
+   * this runs inside a binding, so it is already reading the layout every frame,
+   * and the value it wants is the one the layout just produced. It writes a plain
+   * array rather than a signal, so nothing is invalidated by it.
+   */
+  private widthFor(index: number): number | "hug" {
+    const shown = this.reveal[index] ?? 0
+    if (shown >= 1) {
+      const measured = this.items[index]?.measuredWidth ?? 0
+      if (measured > 0) this.natural[index] = measured
+      return "hug"
+    }
+    return shown * (this.natural[index] ?? 0)
+  }
+
+  /** One entry: the series caption beside its colour swatch. */
+  private buildItem(series: ChartSeries, index: number): Rect {
+    const marker = this.legend.markerStyle
+    const item = new Rect({ flow: "horizontal",
+      gap: 12,
+      align: "center",
+      // Bound to the reveal, so showing and hiding is a number moving rather
+      // than a child arriving and leaving.
+      width: () => this.widthFor(index),
+      opacity: () => this.reveal[index] ?? 0,
+      height: "hug",
+      children: [
+        new Text({
+          ...textOps.styleProps(this.legend.textStyle),
+          text: series.label,
+        }),
+        new Rect({
+          width: marker.width,
+          height: marker.height,
+          cornerRadius: marker.borderRadius,
+          fill: this.swatches[index] ?? "white",
+          stroke: marker.stroke,
+          shadow: marker.shadow,
+        }),
+      ],
+    })
+    // `gapScale` is a `Node` prop rather than a container one, so it is bound here
+    // instead of in the config. It tracks the reveal so the flanking gap closes
+    // with the entry rather than snapping when it reaches zero.
+    item.set({ gapScale: () => this.reveal[index] ?? 0 })
+    return item
+  }
+
+  /** True if series `index` is showing at all — see {@link reveal}. */
+  isEnabled(index: number): boolean {
+    return (this.reveal[index] ?? 0) > 0
+  }
+
+  /**
+   * Grow series `index`'s entry back in at its series-order position, the
+   * siblings sliding over to make room.
+   *
+   * A reveal tween rather than an animated `addChildAt`. The entry never left —
+   * see {@link reveal} — so there is no add to have happened, and the whole
+   * thing is a function of `t`.
+   */
+  @command()
+  showSeries(args: CommandArgs<{ index: number }>): Seekable {
+    const { index = 0 } = args.data ?? {}
+    return this.revealTo(index, 1, args.duration ?? 0.35, args.easing ?? easeOut())
+  }
+
+  /**
+   * Shrink series `index`'s entry away, the gap closing behind it — the mirror
+   * of {@link showSeries}.
+   */
+  @command()
+  hideSeries(args: CommandArgs<{ index: number }>): Seekable {
+    const { index = 0 } = args.data ?? {}
+    return this.revealTo(index, 0, args.duration ?? 0.35, args.easing ?? easeOut())
+  }
+
+  /**
+   * Ramp one entry's reveal to `target`.
+   *
+   * `from` is read when the command is built, which for a driven scene is with
+   * the node in the state its own start time implies — so a hide that follows a
+   * show starts where the show left it rather than at whatever the node happens
+   * to hold now.
+   */
+  private revealTo(
+    index: number,
+    target: number,
+    duration: number,
+    easing: EasingFunction
+  ): Seekable {
+    if (this.items[index] === undefined) return hold(duration)
+    const from = this.reveal[index] ?? 0
+    return drive(duration, (t) => {
+      this.reveal[index] = from + (target - from) * easing(t)
+    })
+  }
+
+  /**
+   * Dim every entry but series `index` to {@link SPOTLIGHT_DIM} and bring that
+   * one back to full — the legend half of a chart's `spotlightSeries`. Entries
+   * stay in place; only their opacity moves, so the row doesn't reflow.
+   *
+   * Only the currently-shown entries are touched — a hidden series' entry is
+   * left as {@link hideSeries} left it.
+   */
+  @command()
+  spotlightSeries(args: CommandArgs<{ index: number }>): Seekable {
+    const { index = 0 } = args.data ?? {}
+    const duration = args.duration ?? 0.35
+    const easing = args.easing ?? easeOut()
+    // Opacity only, on entries that are already in the row — no membership
+    // changes, so unlike {@link showSeries} this is a plain function of `t`.
+    return together(
+      ...this.items
+        .map((item, i) => ({ item, i }))
+        .filter(({ i }) => this.isEnabled(i))
+        .map(({ item, i }) =>
+          item.to({ data: { opacity: i === index ? 1 : SPOTLIGHT_DIM }, duration, easing })
+        )
+    )
+  }
+}