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

package/src/kit/chart-legend.ts

@@ -1,250 +1,229 @@
-import {
-  Rect,
-  Text,
-  command,
-  easeOut,
-  property,
-  textOps,
-  type CommandArgs,
-  type EasingFunction,
-  type Fill,
-  type NodeConfig,
-  type RectProps,
-} 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
-}
-
-/**
- * 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 {
+  Flow,
+  Paint,
+  Rect,
+  Shapes,
+  Text,
+  Types,
+  component2d,
+  textOps,
+  type Fill,
+  type NodeOf,
+  type RectProps,
+  // Named so the row's emitted type reaches the Rect surface it spreads through the sdk, not core.
+  type Alignment as _Alignment,
+  type CornerRadiusResolved as _CornerRadiusResolved,
+  type CornerStyleResolved as _CornerStyleResolved,
+  type FillResolved as _FillResolved,
+  type FlowMode as _FlowMode,
+  type FlowResolved as _FlowResolved,
+  type GapSize as _GapSize,
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
+  type RectCornerRadius as _RectCornerRadius,
+  type RectCornerStyle as _RectCornerStyle,
+  type Shadow as _Shadow,
+  type ShadowResolved as _ShadowResolved,
+  type Stroke as _Stroke,
+  type StrokeResolved as _StrokeResolved,
+  type Vector2 as _Vector2,
+} from "@motionscript/sdk"
+
+import { fresh } from "./entries"
+import { frameEase } from "./motion"
+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 `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
+}
+
+/** A row's entries are a `Rect`'s: paint, the flow of its children, its corners. */
+const row = { ...Paint.state, ...Flow.state, ...Shapes.corners }
+
+/**
+ * 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.
+ */
+const LegendEntry = component2d({
+  key: "legendEntry",
+  state: { ...row, shown: Types.number(1) },
+  commands: { ...Paint.commands },
+  measure: (measurer, state, children) => {
+    const size = Flow.measure(measurer, state, children, Paint.inset(state))
+    return state.shown >= 1 ? size : { ...size, width: state.shown * size.width }
+  },
+  layout: (box, state, children) => Flow.layout(box, state, children, Paint.inset(state)),
+  render: (ctx, state) => Paint.draw(ctx, state, Shapes.rect(ctx.size, state)),
+})
+
+/**
+ * How far each entry is shown, written whole (a document, a `set`) or one
+ * entry at a time (a command, as `{ [index]: reveal }`), which leaves the others
+ * as the frame left them — so two series moving at once each move their own.
+ */
+function revealOf(value: readonly number[] | Readonly<Record<number, number>>, previous?: number[]): number[] {
+  if (Array.isArray(value)) return value as number[]
+  const next = [...(previous ?? [])]
+  for (const [index, reveal] of Object.entries(value)) next[Number(index)] = reveal
+  return next
+}
+
+/**
+ * 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.
+ *
+ * `showSeries`/`hideSeries` flip a series on or off — showing one grows its
+ * entry back in at its stable series position, hiding one shrinks it away. So
+ * the row only ever shows 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 const ChartLegend = component2d({
+  key: "chartLegend",
+  state: {
+    ...row,
+    series: fresh<ChartSeries[]>(() => []),
+    swatches: fresh<Fill[]>(() => []),
+    legend: Types.custom<LegendConfig>(DEFAULT_LEGEND),
+    /**
+     * 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: 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. Collapsed-but-present is the same picture reached
+     * by a route that *is* a function of `t`.
+     */
+    reveal: fresh<number[], number[] | Readonly<Record<number, number>>>(() => [], { resolve: revealOf }),
+  },
+  // This node *is* the row, so the direction is its own answer. It has to be
+  // stated — a `Rect` given no flow lays its children out `freeform`, which
+  // stacks every entry on the same spot. The gap and padding are the theme's.
+  defaults: {
+    flow: "horizontal",
+    width: "hug",
+    height: "hug",
+    gap: (state) => state.legend.itemGap,
+    padding: (state) => state.legend.padding,
+    reveal: (state) => state.series.map((s) => ((s.enabled ?? true) ? 1 : 0)),
+  },
+  // One entry per series, in series order, every one a child for good: order is
+  // fixed rather than depending on which siblings happen to be shown, so an entry
+  // always comes back where it belongs.
+  children: (state) => {
+    const marker = state.legend.markerStyle
+    return state.series.map((series, index) =>
+      LegendEntry({
+        flow: "horizontal",
+        gap: 12,
+        align: "center",
+        width: "hug",
+        height: "hug",
+        // 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`,
+        // and the flanking gap closes with the entry rather than snapping.
+        opacity: () => state.reveal[index] ?? 0,
+        gapScale: () => state.reveal[index] ?? 0,
+        shown: () => state.reveal[index] ?? 0,
+        children: [
+          Text({ ...textOps.styleProps(state.legend.textStyle), text: series.label }),
+          Rect({
+            width: marker.width,
+            height: marker.height,
+            cornerRadius: marker.borderRadius,
+            fill: state.swatches[index] ?? "white",
+            stroke: marker.stroke,
+            shadow: marker.shadow,
+          }),
+        ],
+      })
+    )
+  },
+  commands: {
+    ...Paint.commands,
+    /**
+     * 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, so the whole thing is a function of `t`.
+     */
+    showSeries: {
+      args: { index: Types.number(0, { min: 0, step: 1 }) },
+      // An index that is not a series takes its slot and moves nothing.
+      run: (timeline, state) => (timeline.args.index in state.series
+        ? timeline.animate(revealFrame(state, timeline.args.index, 1, frameEase(timeline)))
+        : timeline.wait(timeline.duration)),
+    },
+    /** Shrink series `index`'s entry away, the gap closing behind it — the mirror of `showSeries`. */
+    hideSeries: {
+      args: { index: Types.number(0, { min: 0, step: 1 }) },
+      run: (timeline, state) => (timeline.args.index in state.series
+        ? timeline.animate(revealFrame(state, timeline.args.index, 0, frameEase(timeline)))
+        : timeline.wait(timeline.duration)),
+    },
+    /**
+     * 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 entries shown when it is built are touched: a hidden series' entry is
+     * left as `hideSeries` left it.
+     */
+    spotlightSeries: {
+      args: { index: Types.number(0, { min: 0, step: 1 }) },
+      run: (timeline, state, children) =>
+        timeline.together(
+          children.flatMap((entry, i) =>
+            (state.reveal[i] ?? 0) > 0 ? [entry.to({ opacity: i === timeline.args.index ? 1 : SPOTLIGHT_DIM })] : []
+          )
+        ),
+    },
+  },
+  measure: (measurer, state, children) => Flow.measure(measurer, state, children, Paint.inset(state)),
+  layout: (box, state, children) => Flow.layout(box, state, children, Paint.inset(state)),
+  render: (ctx, state) => Paint.draw(ctx, state, Shapes.rect(ctx.size, state)),
+})
+
+/**
+ * One entry's reveal ramping to `target` from where the command finds it — so a
+ * hide that follows a show starts where the show left it.
+ */
+function revealFrame(state: { readonly reveal: readonly number[] }, index: number, target: number, ease: (t: number) => number) {
+  const from = state.reveal[index] ?? 0
+  return (t: number) => ({ reveal: { [index]: from + (target - from) * ease(t) } })
+}
+
+/** Whether series `index` is showing at all on `legend`. */
+export function legendShows(legend: { readonly reveal: readonly number[] }, index: number): boolean {
+  return (legend.reveal[index] ?? 0) > 0
+}
+
+export type ChartLegend = NodeOf<typeof ChartLegend>

package/src/kit/entries.ts

@@ -0,0 +1,20 @@
+import { Types, type Element, type Node2D, type Type } from "@motionscript/sdk"
+
+/**
+ * An entry made fresh for every node: each node gets its own array or box
+ * rather than one shared literal, and a host is told no default for it.
+ */
+export function fresh<T, In = T>(make: () => T, options?: { readonly resolve?: (value: In) => T; readonly kind?: string }): Type<In, T> {
+  // A function default is a factory: the component calls it once per node.
+  return Types.custom<In, T>(make as unknown as In, options)
+}
+
+/**
+ * Nodes a `children` builder made with `new`, as the elements it returns. A
+ * part built that way can be read in a binding — its own box, or its parent's,
+ * which is the component it was built for — where a call would hand back only
+ * the element.
+ */
+export function asParts(nodes: readonly Node2D[]): readonly Element[] {
+  return nodes as unknown as readonly Element[]
+}

package/src/kit/motion.ts

@@ -0,0 +1,90 @@
+import { Types, easeOut, type EasingFunction, type Piece, type Timeline } from "@motionscript/sdk"
+
+const identity: EasingFunction = (t) => t
+
+/** Any component's timeline: these helpers only build pieces, which every timeline builds alike. */
+type AnyTimeline = Timeline<any, any>
+
+/**
+ * The ease a part's own frames apply to `t`: none when its command was given
+ * one, which already eases every frame the command builds, and otherwise the
+ * ease-out every chart command defaults to.
+ */
+export function frameEase(timeline: { readonly easing: EasingFunction | undefined }): EasingFunction {
+  return timeline.easing ? identity : easeOut()
+}
+
+/** A piece of a command placed at its own time: from `at` seconds, for `duration` seconds. */
+export interface Beat {
+  readonly at: number
+  readonly duration: number
+  readonly piece: Piece
+}
+
+/**
+ * `beats` at their own offsets over the command, each eased on its own and held
+ * at its last frame once it is done. A beat ahead of the playhead writes nothing,
+ * so whatever stands before it is written by a piece ahead of these. Beats that
+ * run past the command are played faster to end with it.
+ */
+export function beats(timeline: AnyTimeline, parts: readonly Beat[]): Piece {
+  const total = timeline.duration
+  const natural = parts.reduce((end, part) => Math.max(end, part.at + part.duration), 0)
+  const k = natural > total && natural > 0 ? total / natural : 1
+  return timeline.together(
+    parts.map(({ at, duration, piece }) => {
+      const start = at * k
+      const length = duration * k
+      return timeline.sequence([timeline.wait(start), piece, timeline.wait(Math.max(0, total - start - length))])
+    })
+  )
+}
+
+/** How far one piece of a staggered entrance has come: its opacity, and how far it still sits off its place. */
+export interface Arrival {
+  readonly opacity: number
+  readonly shift: number
+}
+
+/** Each piece's arrival, by key. An unlisted piece has landed. */
+export type Arrivals = Readonly<Record<string, Arrival>>
+
+export const LANDED: Arrival = { opacity: 1, shift: 0 }
+
+/**
+ * A part's private record of its pieces' arrivals. A write merges into it, so
+ * beats placed apart each write their own piece and leave the others as the
+ * frame left them.
+ */
+export function arrivalsEntry() {
+  return Types.custom<Arrivals>({}, { private: true, resolve: (next: Arrivals, previous?: Arrivals) => ({ ...previous, ...next }) })
+}
+
+export function arrivalOf(arrivals: Arrivals, key: string | number): Arrival {
+  return arrivals[key] ?? LANDED
+}
+
+/** Every piece in `keys` armed at `from`: the first frame of their entrance. */
+export function armed(keys: readonly (string | number)[], from: Arrival): Arrivals {
+  const record: Record<string, Arrival> = {}
+  for (const key of keys) record[key] = from
+  return record
+}
+
+/**
+ * A piece arriving from `from` over its beat: a part armed at `from` tweened to
+ * `{ opacity: 1, [axis]: 0 }`, eased by `ease`.
+ */
+export function arrival(timeline: AnyTimeline, key: string | number, from: Arrival, ease: EasingFunction): Piece {
+  return timeline.animate((t) => {
+    const e = ease(t)
+    return {
+      arrivals: {
+        [key]: {
+          opacity: from.opacity + (LANDED.opacity - from.opacity) * e,
+          shift: from.shift + (LANDED.shift - from.shift) * e,
+        },
+      },
+    }
+  })
+}

package/src/kit/paints.ts

@@ -0,0 +1,15 @@
+import type { FillResolved, Loader, ShadowResolved, StrokeResolved } from "@motionscript/sdk"
+
+/** Paints a chart part holds in entries of its own, which no paint entry loads for it. */
+export interface PartPaints {
+  readonly fills?: readonly (readonly FillResolved[])[]
+  readonly strokes?: readonly (readonly StrokeResolved[])[]
+  readonly shadows?: readonly (readonly ShadowResolved[])[]
+}
+
+/** Declare `paints` from a component's `load`. */
+export function loadPaints(loader: Loader, paints: PartPaints): void {
+  for (const fill of paints.fills ?? []) loader.fill(fill)
+  for (const strokes of paints.strokes ?? []) for (const stroke of strokes) loader.fill(stroke.fill)
+  for (const shadows of paints.shadows ?? []) for (const shadow of shadows) loader.fill(shadow.fill)
+}