@motionscript/charts 0.1.0 → 0.1.1-alpha.0

package/src/kit/chart-border.ts

@@ -4,9 +4,9 @@ import {
   component2d,
   strokeOps,
   type NodeOf,
-  // Named so this component's emitted type reaches `Node2D` through the sdk, not core.
+  // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.
   type Node2D as _Node2D,
-  type Node2DProps,
+  type Node2DProps as _Node2DProps,
   type Stroke,
   type StrokeResolved,
 } from "@motionscript/sdk"
@@ -14,35 +14,21 @@ import {
 import { loadPaints } from "./paints"
 import { DEFAULT_PLOT_AREA } from "./shared"
 
-export interface ChartBorderProps extends Node2DProps {
-  /**
-   * The plot's thick frame stroke. The stroke resolver's default `align` is
-   * `'inside'`, so the whole weight sits within the layout box unless the theme
-   * overrides it.
-   */
-  stroke: Stroke
-}
-
 /**
- * The thick **frame** around a cartesian chart's plot: an empty rect wearing an
- * inside stroke, sized from its box.
- *
- * Split out of {@link ChartCanvas} (the filled + gridded backdrop) so it can be
- * placed *after* the marks in the tree — the box then frames the plot **over**
- * them, so a line or a column running to the edge tucks cleanly under the border
- * rather than sitting on top of it.
+ * The frame around a cartesian plot: an empty rect with an inside stroke. Split
+ * from {@link ChartCanvas} so it is placed after the marks and frames the plot
+ * over them, tucking a line or column running to the edge under the border.
  */
 export const ChartBorder = component2d({
   key: "chartBorder",
   state: {
+    /** The stroke resolver's default `align` is `'inside'`, so the whole weight sits within the box unless the theme overrides it. */
     stroke: Types.custom<Stroke, StrokeResolved[]>(DEFAULT_PLOT_AREA.stroke, { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
   },
   load: (loader, state) => loadPaints(loader, { strokes: [state.stroke] }),
   render: (ctx, state) => {
     const { width, height } = ctx.size
     if (width <= 0 || height <= 0) return
-    // Empty rect (no fill) with the themed stroke, so the frame sits over the
-    // marks but the box interior stays clear.
     ctx.draw(new Graphics2D().rect({ x: 0, y: 0, width, height }).stroke(state.stroke))
   },
 })

package/src/kit/chart-canvas.ts

@@ -8,9 +8,9 @@ import {
   type Fill,
   type FillResolved,
   type NodeOf,
-  // Named so this component's emitted type reaches `Node2D` through the sdk, not core.
+  // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.
   type Node2D as _Node2D,
-  type Node2DProps,
+  type Node2DProps as _Node2DProps,
   type Shadow,
   type ShadowResolved,
   type Stroke,
@@ -26,44 +26,14 @@ import {
   type Range,
 } from "./shared"
 
-export interface ChartCanvasProps extends Node2DProps {
-  /** Fill of the plot panel behind the marks. */
-  fill: Fill
-  /** Drop shadow of the panel. Default none. */
-  shadow: Shadow
-  /** Stroke of the vertical grid lines (one per {@link xMarkers}). */
-  xGridStroke: Stroke
-  /** Stroke of the horizontal grid lines (one per {@link yMarkers}). */
-  yGridStroke: Stroke
-  /**
-   * Data-unit x positions to draw a vertical grid line at — one per horizontal
-   * axis marker, so a line lands under every marker regardless of spacing.
-   * Positions at (or past) an {@link xExtent} edge coincide with the border and
-   * are skipped. Pass an empty list for a chart whose horizontal axis is
-   * categorical and so has no numeric position to rule at.
-   */
-  xMarkers: number[]
-  /** Data-unit y positions to draw a horizontal grid line at. */
-  yMarkers: number[]
-  /** `[min, max]` of the horizontal scale — maps {@link xMarkers} into the panel. */
-  xExtent: Range
-  /** `[min, max]` of the vertical scale — maps {@link yMarkers} into the panel. */
-  yExtent: Range
-}
-
 const strokeEntry = (initial: Stroke) =>
   Types.custom<Stroke, StrokeResolved[]>(initial, { resolve: strokeOps.resolve, lerp: strokeOps.lerp })
 
 /**
- * The plot **backdrop** of a cartesian chart: a filled panel with a grid of
- * faint lines spanning both directions across it, sized from its box and centred
- * on its origin.
- *
- * The thick frame is a **separate** {@link ChartBorder} node so it can be drawn
- * *over* the marks while this panel sits under them. Grid lines are placed from
- * the axis marker positions (in data units) mapped into the panel through
- * {@link ChartCanvasProps.xExtent}/`yExtent` — so each line lands under its
- * marker whether or not the markers are evenly spaced.
+ * The plot backdrop: a filled panel and a grid, sized from its box. The frame is
+ * a separate {@link ChartBorder} drawn over the marks. Grid lines are placed from
+ * the axis markers' data-unit positions mapped through the extents, so each lands
+ * under its marker however the markers are spaced.
  */
 export const ChartCanvas = component2d({
   key: "chartCanvas",
@@ -72,27 +42,32 @@ export const ChartCanvas = component2d({
     shadow: Types.custom<Shadow, ShadowResolved[]>(DEFAULT_PLOT_AREA.shadow, { resolve: shadowOps.resolve, lerp: shadowOps.lerp }),
     xGridStroke: strokeEntry(DEFAULT_X_AXIS.lineStyle),
     yGridStroke: strokeEntry(DEFAULT_Y_AXIS.lineStyle),
+    /**
+     * Data-unit positions of the vertical grid lines, one per horizontal marker.
+     * Positions at or past an extent edge coincide with the border and are
+     * skipped. Empty for a categorical axis, which has no numeric position to rule at.
+     */
     xMarkers: fresh<number[]>(() => []),
     yMarkers: fresh<number[]>(() => []),
+    /** `[min, max]` of each scale, mapping the markers into the panel. */
     xExtent: fresh<Range>(() => [0, 1]),
     yExtent: fresh<Range>(() => [0, 1]),
   },
-  // The grid strokes are named past the conventional slots, so they are named here.
+  // The grid strokes sit past the conventional slots, so they are named here.
   load: (loader, state) =>
     loadPaints(loader, { fills: [state.fill], shadows: [state.shadow], strokes: [state.xGridStroke, state.yGridStroke] }),
   render: (ctx, state) => {
     const { width: W, height: H } = ctx.size
     if (W <= 0 || H <= 0) return
 
-    // Plot panel, centred on the origin (node space is y-up, origin centre).
     ctx.draw(new Graphics2D().rect({ x: 0, y: 0, width: W, height: H }).shadow(state.shadow).fill(state.fill))
 
     const [xMin, xMax] = state.xExtent
     const [yMin, yMax] = state.yExtent
-    // Fraction of a marker across its extent; guard a zero-width extent.
+    // A zero-width extent maps to 0.
     const xFrac = (v: number) => (xMax <= xMin ? 0 : (v - xMin) / (xMax - xMin))
     const yFrac = (v: number) => (yMax <= yMin ? 0 : (v - yMin) / (yMax - yMin))
-    // Skip markers landing on (or outside) the edges — they'd sit under the border.
+    // Markers on or past the edges would sit under the border.
     const interior = (f: number) => f > 1e-6 && f < 1 - 1e-6
 
     const xStroke = state.xGridStroke[0]

package/src/kit/chart-legend.ts

@@ -9,7 +9,6 @@ import {
   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,
@@ -38,36 +37,13 @@ import {
   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.
+ * One legend entry, hugging its caption and swatch; `shown` scales that width
+ * from nothing. The width is measured from the content at any reveal, so a frame
+ * never depends on the entry once having been fully shown (`"hug"` is not a
+ * number to scale until something measures it).
  */
 const LegendEntry = component2d({
   key: "legendEntry",
@@ -81,11 +57,7 @@ const LegendEntry = component2d({
   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.
- */
+/** Written whole, or one entry at a time as `{ [index]: reveal }`, which leaves the others as the frame left them so two series can move at once. */
 function revealOf(value: readonly number[] | Readonly<Record<number, number>>, previous?: number[]): number[] {
   if (Array.isArray(value)) return value as number[]
   const next = [...(previous ?? [])]
@@ -93,42 +65,23 @@ function revealOf(value: readonly number[] | Readonly<Record<number, number>>, p
   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.
- */
+/** A chart's legend: a horizontal row with one entry per series, each a caption and a colour swatch. This node is the row, so the parent places it. */
 export const ChartLegend = component2d({
   key: "chartLegend",
   state: {
     ...row,
     series: fresh<ChartSeries[]>(() => []),
+    /** Swatch colour by series index, resolved by the chart; a missing entry is white. */
     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`.
+     * How far each entry is shown, `0`-`1`, driving its width, opacity and gap
+     * together. Entries are never added or removed: "is this node a child" is not
+     * a function of time, while collapsed-but-present is.
      */
     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.
+  // The flow must be stated: a `Rect` with none lays children out `freeform`, stacking every entry on one spot.
   defaults: {
     flow: "horizontal",
     width: "hug",
@@ -137,9 +90,7 @@ export const ChartLegend = component2d({
     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.
+  // Every entry stays a child, so one always comes back where it belongs.
   children: (state) => {
     const marker = state.legend.markerStyle
     return state.series.map((series, index) =>
@@ -149,9 +100,7 @@ export const ChartLegend = component2d({
         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.
+        // The width follows the reveal in `measure`, and the flanking gap closes with the entry.
         opacity: () => state.reveal[index] ?? 0,
         gapScale: () => state.reveal[index] ?? 0,
         shown: () => state.reveal[index] ?? 0,
@@ -171,11 +120,7 @@ export const ChartLegend = component2d({
   },
   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`.
-     */
+    /** Grow series `index`'s entry back in at its position, the siblings sliding over. */
     showSeries: {
       args: { index: Types.number(0, { min: 0, step: 1 }) },
       // An index that is not a series takes its slot and moves nothing.
@@ -183,20 +128,14 @@ export const ChartLegend = component2d({
         ? 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`. */
+    /** 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.
-     */
+    /** Dim every entry but `index` to {@link SPOTLIGHT_DIM}, in place. A hidden series' entry is left as `hideSeries` left it. */
     spotlightSeries: {
       args: { index: Types.number(0, { min: 0, step: 1 }) },
       run: (timeline, state, children) =>
@@ -212,18 +151,10 @@ export const ChartLegend = component2d({
   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.
- */
+/** One entry's reveal ramping to `target` from where the command finds it, so a hide after 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

@@ -1,4 +1,4 @@
-import { Types, type Element, type Node2D, type Type } from "@motionscript/sdk"
+import { Types, type Element, type EntryOptions, type Node2D, type Type } from "@motionscript/sdk"
 
 /**
  * An entry made fresh for every node: each node gets its own array or box
@@ -18,3 +18,6 @@ export function fresh<T, In = T>(make: () => T, options?: { readonly resolve?: (
 export function asParts(nodes: readonly Node2D[]): readonly Element[] {
   return nodes as unknown as readonly Element[]
 }
+
+/** The argument every per-series command takes: an index into `series`, offered by name. */
+export const SERIES_ARG = Types.custom<number, number, EntryOptions & { readonly min: number; readonly step: number }>(0, { kind: "series", min: 0, step: 1 })

package/src/kit/motion.ts

@@ -3,7 +3,16 @@ import { Types, easeOut, type EasingFunction, type Piece, type Timeline } from "
 const identity: EasingFunction = (t) => t
 
 /** Any component's timeline: these helpers only build pieces, which every timeline builds alike. */
-type AnyTimeline = Timeline<any, any>
+export type AnyTimeline = Timeline<any, any>
+
+/** How far a legend starts below its slot when `enter` brings it in, in px. */
+export const LEGEND_SLIDE = 20
+
+/** Marker count when an axis states no ticks. */
+export const DEFAULT_MARKERS = 5
+
+/** How a cartesian `enter` splits its duration: axes arriving, marks drawing, legend coming up. Sums to 1. */
+export const ENTER_SHARE = { axes: 0.35, marks: 0.5, legend: 0.15 } as const
 
 /**
  * The ease a part's own frames apply to `t`: none when its command was given
@@ -49,7 +58,7 @@ export interface Arrival {
 /** 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 }
+const LANDED: Arrival = { opacity: 1, shift: 0 }
 
 /**
  * A part's private record of its pieces' arrivals. A write merges into it, so