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

package/src/kit/chart-legend.ts

@@ -1,250 +1,245 @@
-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 })
-        )
-    )
-  }
-}
+import {
+  Rect,
+  Text,
+  command,
+  easeOut,
+  property,
+  textOps,
+  type CommandArgs,
+  type EasingFunction,
+  type Fill,
+  type MeasureContext2D,
+  type NodeConfig,
+  type RectProps,
+  type Size2D,
+  type SizeConstraints,
+} from "@motionscript/sdk"
+
+import { drive, hold, together, type Seekable } from "@motionscript/sdk/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
+}
+
+/**
+ * One legend entry. It hugs its caption and swatch; `shown` scales that width from
+ * nothing to the whole of it.
+ *
+ * The width is taken from the content on every measure, at any reveal, so a frame
+ * never depends on whether the entry was once seen fully shown. A collapse needs a
+ * number to scale, and `"hug"` is not one until something measures it — this is
+ * the something.
+ */
+class LegendEntry extends Rect {
+  constructor(props: NodeConfig<Rect, RectProps>, private readonly _shown: () => number) {
+    super(props)
+  }
+
+  override measure(constraints: SizeConstraints, scope: MeasureContext2D): Partial<Size2D> {
+    const size = super.measure(constraints, scope)
+    const shown = this._shown()
+    return shown >= 1 ? size : { ...size, width: shown * (size.width ?? 0) }
+  }
+}
+
+/**
+ * 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: LegendEntry[] = []
+  /**
+   * 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`.
+   *
+   * One array in one slot, because the count is the series count, which is data.
+   * It is replaced rather than mutated: a write is a slot write, so the timeline
+   * sees it and restores it to the authored reveal before the command starts
+   * and after a seek back. The entries' props are bound to it, so writing it
+   * still moves the layout.
+   */
+  @property({ default: () => [] as number[] }) private declare reveal: 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.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)
+  }
+
+  /** One entry: the series caption beside its colour swatch. */
+  private buildItem(series: ChartSeries, index: number): LegendEntry {
+    const marker = this.legend.markerStyle
+    const item = new LegendEntry({ 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. The width follows it in `measure`.
+      width: "hug",
+      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,
+        }),
+      ],
+    }, () => this.reveal[index] ?? 0)
+    // `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) => {
+      const next = [...this.reveal]
+      next[index] = from + (target - from) * easing(t)
+      this.reveal = next
+    })
+  }
+
+  /**
+   * 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 })
+        )
+    )
+  }
+}