@motionscript/charts 0.1.0 → 0.1.1-alpha.0

package/src/line-chart/line-chart.ts

@@ -5,13 +5,11 @@ import {
   easeOut,
   type ChildView,
   type DataRecord,
-  type EntryOptions,
   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,
-  type Node2DProps,
+  type Node2DProps as _Node2DProps,
   type Size2D,
-  type Timeline,
   type Vector2,
 } from "@motionscript/sdk"
 import { formatNumber } from "@motionscript/sdk/component"
@@ -20,8 +18,8 @@ import { cartesianFrame, cartesianViews, laidOutSize } from "../kit/cartesian"
 import { ChartBorder } from "../kit/chart-border"
 import { ChartCanvas } from "../kit/chart-canvas"
 import { ChartLegend } from "../kit/chart-legend"
-import { asParts, fresh } from "../kit/entries"
-import { beats, type Beat } from "../kit/motion"
+import { SERIES_ARG, asParts, fresh } from "../kit/entries"
+import { DEFAULT_MARKERS, ENTER_SHARE, LEGEND_SLIDE, beats, type AnyTimeline, type Beat } from "../kit/motion"
 import { VerticalAxis } from "../kit/vertical-axis"
 import {
   SPOTLIGHT_DIM,
@@ -36,6 +34,7 @@ import {
   settleAxisDomain,
   type AxisDomainConfig,
   type Range,
+  type ResolvedAxisDomain,
 } from "../kit/shared"
 import { ChartLine } from "./chart-line"
 import { ChartRegion } from "./chart-region"
@@ -55,41 +54,10 @@ import {
 } from "./shared"
 import { resolveXScale, type XScale } from "./x-scale"
 
-export interface LineChartProps extends Node2DProps {
-  /** One row per sample — a plain record of field name to value. */
-  data: DataRecord[]
-  /**
-   * Key into each row for its x value, shared by every series. Named `xField`
-   * rather than `x` because every node already has an `x` — its position.
-   */
-  xField: string
-  /** One polyline per entry: which field it plots, its legend `label`, its `fill`. */
-  series: LineSeries[]
-  /** X-axis data domain: caption, scale range, and tick placement. */
-  xAxis?: AxisDomainConfig
-  /** Y-axis data domain: caption, scale range, and tick placement. */
-  yAxis?: AxisDomainConfig
-  /**
-   * A slice of the plot to spotlight, in **data units**. Dashed rules mark the
-   * bounded edges and every series fades outside the box — see
-   * `spotlightRegion`, which animates the same thing. `null` (the default) is no
-   * region.
-   */
-  region?: PlotRegion | null
-  /**
-   * The chart's visual theme — series palette, axis text/grid/gutters, plot
-   * panel paint, and legend styling. Every branch is optional and deep-merged
-   * onto {@link DEFAULT_CHART_THEME}, so pass only what you want to override.
-   */
-  theme?: ChartTheme
-  /** Whether the legend row below the plot is drawn at all. */
-  showLegend?: boolean
-}
-
 /** Both axes' domains with their ranges and ticks resolved. */
 export interface LineChartDomains {
-  readonly x: AxisDomainConfig & { readonly range: Range; readonly ticks: number[] }
-  readonly y: AxisDomainConfig & { readonly range: Range; readonly ticks: number[] }
+  readonly x: ResolvedAxisDomain
+  readonly y: ResolvedAxisDomain
 }
 
 /** What a line chart plots, as its entries hold it. */
@@ -101,12 +69,6 @@ export interface LineChartValues {
   readonly yAxis: AxisDomainConfig
 }
 
-/**
- * The argument every per-series command takes: an index into `series`. Its own
- * kind rather than `number` so a host can offer the series by name.
- */
-const SERIES_ARG = Types.custom<number, number, EntryOptions & { readonly min: number; readonly step: number }>(0, { kind: "series", min: 0, step: 1 })
-
 /** One argument, two controls: the commands take a `PlotRegion`, so the x and y spans a host draws are declared inside it. */
 const REGION_ARG = Types.custom<PlotRegion | undefined>(undefined, {
   kind: "region",
@@ -116,21 +78,6 @@ const REGION_ARG = Types.custom<PlotRegion | undefined>(undefined, {
   },
 })
 
-/** How far the legend starts below its slot when it enters, in px. */
-const LEGEND_SLIDE = 20
-
-/** Fallback marker count when neither axis's ticks are given. */
-const DEFAULT_MARKERS = 5
-
-/**
- * How `enter` divides its duration between its three beats: the axes arriving,
- * the lines tracing, and the legend coming up. Shares of the whole, so they must
- * sum to 1 — the entrance takes exactly the time it was given.
- */
-const AXES_SHARE = 0.35
-const LINES_SHARE = 0.5
-const LEGEND_SHARE = 0.15
-
 /** What the chart's own commands read: its entries, and the private `home` a zoom remembers. */
 interface LineState extends LineChartValues {
   readonly theme: ChartConfig
@@ -139,30 +86,19 @@ interface LineState extends LineChartValues {
   readonly home: LineChartDomains | null
 }
 
-/**
- * What the x column *is* — a number, an instant, or a place in the file — and
- * with it how each row is positioned, ticked and captioned. See `x-scale.ts`.
- */
+/** What the x column is (a number, an instant, or a place in the file), and so how rows are positioned, ticked and captioned. */
 function columnOf(s: LineChartValues, format = s.xAxis.format): XScale {
   return resolveXScale(s.data, s.xField, format)
 }
 
-/**
- * The horizontal axis with its range and ticks resolved: the explicit ones, else
- * the column's extent and five ticks across it, asked of the column because only
- * a numeric one has round numbers between its samples.
- */
+/** The explicit range and ticks, else the column's extent and ticks: only a numeric column has round numbers between its samples. */
 function drawnX(s: LineChartValues, domain: AxisDomainConfig): AxisDomainConfig {
   const column = columnOf(s, domain.format)
   const range = domain.range ?? column.extent
   return { ...domain, range, ticks: domain.ticks ?? column.ticks(range, DEFAULT_MARKERS - 1) }
 }
 
-/**
- * The vertical axis with its range and ticks resolved. Auto-ranging steps into
- * one fewer segment than the intended marker count, so the tidy bounds frame the
- * ticks the axis draws.
- */
+/** Auto-ranging steps into one fewer segment than the marker count, so the tidy bounds frame the ticks drawn. */
 function drawnY(s: LineChartValues, domain: AxisDomainConfig): AxisDomainConfig {
   const divisions = (domain.ticks?.length ?? DEFAULT_MARKERS) - 1
   const range = resolveYScale(s.data, s.series, domain.range, divisions)
@@ -175,7 +111,7 @@ const domainsDrawn = new WeakMap<
   Pick<LineChartValues, "xField" | "xAxis" | "yAxis" | "series"> & { readonly domains: LineChartDomains }
 >()
 
-/** Both axes as a line chart draws them now, an auto range or tick row read back as itself. */
+/** Both axes as drawn now. */
 export function lineChartDomains(s: LineChartValues): LineChartDomains {
   const { data, xField, xAxis, yAxis, series } = s
   const kept = domainsDrawn.get(data)
@@ -190,10 +126,7 @@ export function lineChartDomains(s: LineChartValues): LineChartDomains {
   return domains
 }
 
-/**
- * Map one series' data points into the plot's **centred** pixel space (origin at
- * the plot centre, y-up): x runs `[-w/2, +w/2]`, y runs `[-h/2, +h/2]`.
- */
+/** One series' points in the plot's centred pixel space (origin at its centre, y-up). */
 function seriesPixels(s: LineChartValues, domains: LineChartDomains, index: number, plot: Size2D): Vector2[] {
   const series = s.series[index]
   if (!series) return []
@@ -204,46 +137,37 @@ function seriesPixels(s: LineChartValues, domains: LineChartDomains, index: numb
   const [yMin, yMax] = domains.y.range
   const xToPx = (x: number) => (xMax <= xMin ? 0 : ((x - xMin) / (xMax - xMin) - 0.5) * w)
   const yToPx = (y: number) => (yMax <= yMin ? 0 : ((y - yMin) / (yMax - yMin) - 0.5) * h)
-  // `seriesPoints` already sorted them along x.
   return points.map(([x, y]) => ({ x: xToPx(x), y: yToPx(y) }))
 }
 
-/** `region` mapped into the plot's centred pixel space, against the live scales, so it travels with a zoom. */
+/** `region` in centred pixel space against the live scales, so it travels with a zoom. */
 function regionBox(s: LineChartValues & { readonly region: PlotRegion | null }, domains: LineChartDomains, plot: Size2D): RegionBox {
   const { width: w, height: h } = plot
   return resolveRegionBox(s.region, { left: -w / 2, right: w / 2, bottom: -h / 2, top: h / 2 }, domains.x.range, domains.y.range)
 }
 
-/**
- * Whether a call-out is authored at all. Not whether it resolves to pixels: a
- * command is built before the first layout, and a region on a chart not yet
- * measured is a real one. A region bounding neither axis is none, as `null` is.
- */
+/** Whether a call-out is authored, not whether it resolves to pixels: a command is built before the first layout. A region bounding neither axis is none. */
 function hasCallout(s: { readonly region: PlotRegion | null }): boolean {
   const region = s.region
   return region != null && (region.x !== undefined || region.y !== undefined)
 }
 
-/** The `region` a document handed a command, or `{}`: a command is added before its arguments are filled in. */
+/** The `region` argument, or `{}`: a command is added before its arguments are filled in. */
 function regionArg(region: PlotRegion | null | undefined): PlotRegion {
   return region != null && typeof region === "object" ? region : {}
 }
 
-/** A range read as a span, whichever way round the author wrote it. */
+/** A range ordered low to high. */
 function span([a, b]: Range): Range {
   return a <= b ? [a, b] : [b, a]
 }
 
-/**
- * Rescale an axis to `range`, keeping the tick *count* it already has, so each
- * marker slides from its old value to its new one instead of the row popping.
- */
+/** Rescale to `range` keeping the tick count, so each marker slides rather than the row popping. */
 function rescale(range: Range, ticks: readonly number[]): AxisDomainConfig {
   const to = span(range)
   return { range: to, ticks: markerValues(to, Math.max(2, ticks.length) - 1) }
 }
 
-/** The axis writes of a move from `from` toward `to` at `t`. */
 function axesAt(from: LineChartDomains, to: Partial<Record<"x" | "y", AxisDomainConfig>>, t: number) {
   return {
     ...(to.x && { xAxis: lerpAxisDomain(from.x, to.x, t) }),
@@ -251,8 +175,6 @@ function axesAt(from: LineChartDomains, to: Partial<Record<"x" | "y", AxisDomain
   }
 }
 
-type AnyTimeline = Timeline<any, any>
-
 /** The parts a line chart's commands drive, found through its children. */
 function partsOf(children: readonly ChildView[]) {
   const frame = cartesianViews(children)
@@ -267,17 +189,15 @@ function partsOf(children: readonly ChildView[]) {
   }
 }
 
-/** Drop the call-out: the rules retract, the wash fades, and every series comes back to full. */
 function clearing(timeline: AnyTimeline, state: LineState) {
   const from = state.regionReveal
   const region = state.region
-  // Nothing to retract, but the call still takes its slot on the timeline.
+  // Nothing to retract, but the call still takes its slot.
   if (from === 0) return timeline.animate(() => ({ region: null, regionReveal: 0 }), { eased: false })
   // `region` is held until the retraction lands, or there would be nothing left to retract.
   return timeline.animate((t) => (t >= 1 ? { region: null, regionReveal: 0 } : { region, regionReveal: from * (1 - t) }))
 }
 
-/** Trace series `index`'s line in (`show`) or back out, in lockstep with its legend entry. */
 function toggling(timeline: AnyTimeline, children: readonly ChildView[], index: number, show: boolean) {
   const parts = partsOf(children)
   const line = parts?.lines[index]
@@ -289,62 +209,35 @@ function toggling(timeline: AnyTimeline, children: readonly ChildView[], index:
 }
 
 /**
- * A multi-series line chart, composed from five independent parts rather than
- * one monolithic draw:
- *
- * - {@link ChartCanvas} — the plot panel with a two-way grid, under everything.
- * - {@link VerticalAxis} / {@link HorizontalAxis} — columns/rows of real text
- *   markers that stagger in, each carrying its own axis caption.
- * - {@link ChartRegion} — the optional call-out marking a spotlit slice of the
- *   plot: dashed rules on its bounded edges, and every series faded outside it.
- * - {@link ChartLine} (one per series) — the traced polylines over the canvas.
- * - {@link ChartLegend} — a row of entries below the chart, one per series.
+ * A multi-series line chart composed of {@link ChartCanvas}, {@link VerticalAxis} /
+ * {@link HorizontalAxis}, {@link ChartRegion}, one {@link ChartLine} per series and
+ * {@link ChartLegend}. Every part reads the chart's entries through bindings and
+ * maps against the plot panel's own laid-out box.
  *
- * Every part reads the chart's entries through bindings, and the lines, the
- * region and the grid all map against the plot panel's own laid-out box, so
- * points land exactly on their markers and the chart re-flows if its box
- * changes.
- *
- * **Resting state is the finished chart**: an editor paints a node's Initial
- * state on a paused canvas. `enter` arms every part on its first frame.
- *
- * Past the entrance, `showSeries`/`hideSeries`/`spotlightSeries` pick out a
- * *series*, `spotlightRegion` marks a *slice of the plot* without changing the
- * scale, and `zoomTo` rescales the axes so a slice fills the plot. A spotlit
- * region resolves against the live scales, so it travels with a zoom. A `to` of
- * an axis `range` or `ticks` tweens from the domain as drawn (see
- * {@link lerpAxisEntry}), so an auto axis rescales continuously.
+ * Resting state is the finished chart; `enter` arms every part on its first
+ * frame. A `to` of an axis `range` or `ticks` tweens from the domain as drawn
+ * (see {@link lerpAxisEntry}), so an auto axis rescales continuously.
  */
 export const LineChart = component2d({
   key: "lineChart",
   state: {
     data: fresh<DataRecord[]>(() => [], { kind: "dataset" }),
+    // Not `x`: every node already has an `x`, its position.
     xField: "",
     series: fresh<LineSeries[]>(() => [], { kind: "series" }),
     xAxis: Types.custom<AxisDomainConfig>({}, { resolve: resolveAxisDomain, lerp: lerpAxisEntry }),
     yAxis: Types.custom<AxisDomainConfig>({}, { resolve: resolveAxisDomain, lerp: lerpAxisEntry }),
     theme: Types.custom<ChartTheme, ChartConfig>(DEFAULT_CHART_THEME, { resolve: resolveChartTheme, lerp: lerpChartTheme }),
-    /**
-     * The spotlit slice of the plot in data units, or `null` for none. The box
-     * snaps; the animation is {@link regionReveal} drawing the rules on.
-     */
+    /** The spotlit slice in data units, or `null`. The box snaps; {@link regionReveal} animates it. */
     region: Types.custom<PlotRegion | null>(null),
-    /**
-     * How far the `region` call-out is drawn in, `[0, 1]`: the rules grow out and
-     * the wash fades up as it climbs, while every line's out-of-region stretch
-     * fades to the theme's `region.dimOpacity`.
-     */
+    /** How far the `region` call-out is drawn in, `[0, 1]`: rules grow, wash fades up, out-of-region stretches fade to `region.dimOpacity`. */
     regionReveal: 0,
     /** Read as the chart is built: the legend is a part the chart builds or doesn't. */
     showLegend: Types.boolean(true, { animatable: false }),
-    /**
-     * The domain `zoomTo` first left, so `resetZoom` restores the chart as it
-     * stood, auto-derived ticks included. Cleared by `resetZoom`, so the next zoom
-     * remembers wherever the chart rests then.
-     */
+    /** The domain `zoomTo` first left, so `resetZoom` restores it, auto-derived ticks included. */
     home: Types.custom<LineChartDomains | null>(null, { private: true }),
   },
-  // Its parts fill it; a node made of them would hug them.
+  // A node made of parts that fill would otherwise hug them.
   defaults: { width: "fill", height: "fill" },
   allowedChildren: [],
   children: (state) => {
@@ -359,7 +252,6 @@ export const LineChart = component2d({
     const vAxis = new VerticalAxis({
       range: () => domains().y.range,
       markers: () => domains().y.ticks,
-      // The y axis is always numbers, so its format is simply the pattern.
       captions: () => {
         const markers = domains().y.ticks
         const format = state.yAxis.format
@@ -374,8 +266,7 @@ export const LineChart = component2d({
     const hAxis = new HorizontalAxis({
       range: () => domains().x.range,
       markers: () => domains().x.ticks,
-      // A tick on a month or category column is captioned with the cell it came
-      // out of — `Jan`, not the instant it parsed to.
+      // A month or category tick is captioned with its cell (`Jan`), not the instant it parsed to.
       captions: () => {
         const column = columnOf(state)
         return domains().x.ticks.map((value) => column.label(value))
@@ -392,10 +283,8 @@ export const LineChart = component2d({
           points: () => seriesPixels(state, domains(), i, plotSize()),
           stroke: () => resolveSeriesStroke(theme().seriesStyles, s, i),
           enabled: enabled[i],
-          // Each line clips itself against the box the rules are drawn from, so
-          // the dim/bright boundary can't drift from the dashes.
+          // The box the rules are drawn from, so the dim boundary cannot drift from the dashes.
           spotlight: () => regionBox(state, domains(), plotSize()),
-          // Ramped by the reveal that draws the rules: one signal, both halves.
           dimOpacity: () => 1 - (1 - theme().region.dimOpacity) * state.regionReveal,
         }) as unknown as Node2D
     )
@@ -405,12 +294,9 @@ export const LineChart = component2d({
       below.push(
         new ChartLegend({
           series: state.series,
-          // The legend paints a swatch, not a line, so it is handed the colour each
-          // stroke resolves to rather than the stroke itself.
           swatches: () => state.series.map((s, i) => resolveSeriesFill(theme().seriesStyles, s, i)),
           legend: () => theme().legend,
-          // The row's spacing is the theme's as the chart was built, like the
-          // entries' type and chips: a theme tween re-paints the swatches only.
+          // Spacing is fixed as built; a theme tween re-paints the swatches only.
           gap: state.theme.legend.itemGap,
           padding: state.theme.legend.padding,
         }) as unknown as Node2D
@@ -425,14 +311,12 @@ export const LineChart = component2d({
           shadow: () => theme().plotArea.shadow,
           xGridStroke: () => theme().xAxis.lineStyle,
           yGridStroke: () => theme().yAxis.lineStyle,
-          // A grid line under every axis marker; the canvas skips the edges.
           xMarkers: () => domains().x.ticks,
           yMarkers: () => domains().y.ticks,
           xExtent: () => domains().x.range,
           yExtent: () => domains().y.range,
         }),
-        // Over the grid, under the lines, so a spotlit stretch of a series isn't
-        // tinted by the highlight meant to pick it out.
+        // Under the lines, so the highlight does not tint the stretch it picks out.
         new ChartRegion({
           box: () => regionBox(state, domains(), plotSize()),
           stroke: () => theme().region.stroke,
@@ -458,17 +342,13 @@ export const LineChart = component2d({
   },
   commands: {
     /**
-     * Animate the whole chart in: the two axes stagger their markers in, the
-     * series lines trace left to right, and the legend fades up last. Its first
-     * frame arms every part: markers shifted and transparent, lines untraced,
-     * the legend dropped and transparent.
-     *
-     * `duration` is the **whole** entrance; the beats are shares of it. A chart
-     * authored with a `region` lands its call-out last, in the final quarter.
+     * Axes stagger in, lines trace left to right, the legend fades up last.
+     * `duration` is the whole entrance; a chart with a `region` lands its
+     * call-out in the final quarter.
      */
     enter: {
       args: {},
-      // Held from the chart's arrival, so it never shows finished ahead of its draw.
+      // Held from arrival, so it never shows finished ahead of its draw.
       entrance: true,
       easing: easeOut(),
       run: (timeline, state, children) => {
@@ -477,8 +357,8 @@ export const LineChart = component2d({
         const duration = timeline.duration
         const revealing = hasCallout(state) && state.regionReveal === 0
         const body = revealing ? duration * 0.75 : duration
-        const axes = body * AXES_SHARE
-        const traced = body * LINES_SHARE
+        const axes = body * ENTER_SHARE.axes
+        const traced = body * ENTER_SHARE.marks
         const { legend } = parts
         const at0 = (piece: Beat["piece"]): Beat => ({ at: 0, duration: 0, piece })
         // The first frame arms what every later beat moves: a beat ahead of the
@@ -490,17 +370,15 @@ export const LineChart = component2d({
           { at: 0, duration: axes, piece: parts.vAxis.run("enter", { slide: 24 }) },
           { at: 0, duration: axes, piece: parts.hAxis.run("enter", { slide: 24 }) },
           ...parts.lines.map((line) => ({ at: axes, duration: traced, piece: line.run("enter") })),
-          ...(legend ? [{ at: axes + traced, duration: body * LEGEND_SHARE, piece: legend.to({ opacity: 1, y: 0 }) }] : []),
+          ...(legend ? [{ at: axes + traced, duration: body * ENTER_SHARE.legend, piece: legend.to({ opacity: 1, y: 0 }) }] : []),
           ...(revealing ? [{ at: body, duration: duration * 0.25, piece: timeline.animate((t) => ({ regionReveal: t })) }] : []),
         ])
       },
     },
     /**
-     * Spotlight a rectangular slice of the plot given in **data units**: dashed
-     * rules draw onto each bounded edge while every series fades outside the box.
-     * Either axis alone is a band; both are a box. Called while another region is
-     * up, the old call-out retracts over the first half and the new one draws in
-     * over the second, each half eased on its own.
+     * Spotlight a slice of the plot in data units; either axis alone is a band.
+     * Over a region already up, the old one retracts in the first half and the
+     * new one draws in over the second, each half eased on its own.
      */
     spotlightRegion: {
       args: { region: REGION_ARG },
@@ -521,18 +399,13 @@ export const LineChart = component2d({
         )
       },
     },
-    /** Drop the region call-out. A no-op when nothing is spotlit, which still takes its slot. */
+    /** Drop the call-out. A no-op when nothing is spotlit, which still takes its slot. */
     clearRegion: {
       args: {},
       easing: easeOut(),
       run: (timeline, state) => clearing(timeline, state),
     },
-    /**
-     * Zoom the plot to a slice of itself, given in **data units**: the named axes
-     * rescale so that slice fills the plot, the grid, both marker rows and every
-     * series following. An omitted axis is left as it is. The first zoom
-     * remembers the domain it left, for `resetZoom`.
-     */
+    /** Rescale the named axes so a slice (data units) fills the plot; an omitted axis is left. The first zoom remembers the domain for `resetZoom`. */
     zoomTo: {
       args: { region: REGION_ARG },
       easing: easeOut(),
@@ -548,7 +421,7 @@ export const LineChart = component2d({
         return timeline.animate((t) => ({ home, ...axesAt(from, to, t) }))
       },
     },
-    /** Pull back out to the domain the first zoom left — the mirror of `zoomTo`, and a hold if it never zoomed. */
+    /** Back to the domain the first zoom left; a hold if it never zoomed. */
     resetZoom: {
       args: {},
       easing: easeOut(),
@@ -559,26 +432,19 @@ export const LineChart = component2d({
         return timeline.animate((t) => ({ home: null, ...axesAt(from, home, t) }))
       },
     },
-    /**
-     * Show series `index`: **trace** its line in left to right, in lockstep with
-     * its legend entry growing in.
-     */
+    /** Trace series `index` in, with its legend entry growing in. */
     showSeries: {
       args: { seriesIndex: SERIES_ARG },
       easing: easeOut(),
       run: (timeline, _state, children) => toggling(timeline, children, timeline.args.seriesIndex, true),
     },
-    /** Hide series `index`: **retrace** its line back out as its legend entry shrinks away. */
+    /** Retrace series `index` out as its legend entry shrinks away. */
     hideSeries: {
       args: { seriesIndex: SERIES_ARG },
       easing: easeOut(),
       run: (timeline, _state, children) => toggling(timeline, children, timeline.args.seriesIndex, false),
     },
-    /**
-     * Fade every other series — each line **and its legend entry** — to focus on
-     * `index`, which comes back to full. The legend dims in place, so the row
-     * doesn't reflow.
-     */
+    /** Fade every other series, line and legend entry, to focus on `index`. The legend dims in place, so the row does not reflow. */
     spotlightSeries: {
       args: { seriesIndex: SERIES_ARG },
       easing: easeOut(),