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

package/src/kit/chart-legend.ts

@@ -0,0 +1,229 @@
+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)
+}