@motionscript/charts 0.1.0 → 0.1.1-alpha.0

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

@@ -4,8 +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 as _Node2DProps,
   type Stroke,
   type StrokeResolved,
   type Vector2,
@@ -22,12 +23,7 @@ import {
   type RegionBox,
 } from "./shared"
 
-/**
- * The prefix of `pts` revealed at fraction `p ∈ [0, 1]`, measuring the reveal
- * by *cumulative arc length* so the line traces at a steady pace regardless of
- * uneven point spacing. Returns the whole-point prefix plus one interpolated
- * point partway along the active segment.
- */
+/** The prefix of `pts` revealed at fraction `p`, measured by cumulative arc length so the trace keeps a steady pace over uneven spacing. */
 function tracePoints(pts: Vector2[], p: number): Vector2[] {
   if (p >= 1 || pts.length < 2) return pts
   if (p <= 0) return []
@@ -59,45 +55,28 @@ function tracePoints(pts: Vector2[], p: number): Vector2[] {
   return out
 }
 
-/**
- * A single series line of a {@link LineChart}: one rounded polyline traced
- * through pre-mapped pixel `points`, drawn as one {@link Graphics2D} command list.
- * Sized and positioned by the parent, which shares the plot's coordinate frame.
- *
- * Two signals drive it: `progress` traces the line in
- * (animated by `enter`) and `enabled` shows or hides it wholesale.
- */
+/** One series of a {@link LineChart}: a rounded polyline through pre-mapped pixel `points`, one {@link Graphics2D} command list. `progress` traces it in; `enabled` shows or hides it wholesale. */
 export const ChartLine = component2d({
   key: "chartLine",
   state: {
-    /** The series polyline, already mapped into this node's local pixel space (origin at centre, y-up) by the parent {@link LineChart}. Ordered along x. */
+    /** In this node's pixel space (origin at centre, y-up), mapped by the parent and ordered along x. */
     points: fresh<Vector2[]>(() => []),
-    /** Line colour + weight (+ optional dash/cap/join) — the per-series stroke. */
     stroke: Types.custom<Stroke, StrokeResolved[]>([], { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
-    /**
-     * Reveal of the line in `[0, 1]`: 0 hides it, 1 traces it fully from its left
-     * end to its right. Defaults to 1, so the paused editor canvas paints the line;
-     * `enter` drives it from 0 regardless of where it rests.
-     */
+    /** Trace from the left end, `[0, 1]`. Rests at 1 so a paused editor canvas paints the line; `enter` drives it from 0. */
     progress: 1,
-    /** Whether this line is drawn at all: the switch the chart flips alongside its legend's per-series toggle. */
+    /** Whether the line is drawn at all, flipped alongside its legend entry. */
     enabled: true,
-    /** A slice of the plot to spotlight, in this node's own pixel space: outside it the line drops to `dimOpacity`. */
+    /** In this node's pixel space; outside it the line drops to `dimOpacity`. */
     spotlight: fresh<RegionBox>(() => EMPTY_REGION_BOX),
-    /** Opacity the out-of-region stretches fade to. */
     dimOpacity: SPOTLIGHT_DIM,
   },
   load: (loader, state) => loadPaints(loader, { strokes: [state.stroke] }),
   commands: {
     /**
-     * Trace the line from `from` to `to` over the command — by default in from
-     * its left end to its right. `showSeries` and `hideSeries` are the same
-     * motion in opposite directions, so both are this with their ends stated.
-     *
-     * `enabled` rides along in the same value rather than being set before or
-     * after the command: a line is drawable for every `t` the trace covers and
-     * undrawn outside it, which is what makes arriving at a time backwards show
-     * what arriving forwards does.
+     * Trace the line from `from` to `to`; `showSeries`/`hideSeries` are this with
+     * the ends stated. `enabled` rides along in the same value, so the line is
+     * drawable for every `t` the trace covers and arriving backwards matches
+     * arriving forwards.
      */
     enter: {
       args: { from: Types.number(0, { min: 0, max: 1 }), to: Types.number(1, { min: 0, max: 1 }) },
@@ -106,8 +85,7 @@ export const ChartLine = component2d({
         const ease = frameEase(timeline)
         return timeline.animate((t) => {
           const progress = from + (to - from) * ease(t)
-          // Hidden only once it has fully retraced, so the last frame of a hide is
-          // the empty plot rather than a line that vanished a frame early.
+          // Hidden only once fully retraced, so a hide does not vanish a frame early.
           return { progress, enabled: progress > 0 }
         })
       },
@@ -124,7 +102,7 @@ export const ChartLine = component2d({
     const drawn = tracePoints(pts, p)
     if (drawn.length < 2) return
     const stroke = state.stroke
-    const radius = (stroke[0]?.weight ?? 0) * 2 // round the joins
+    const radius = (stroke[0]?.weight ?? 0) * 2
 
     const box = state.spotlight
     if (!hasRegion(box)) {
@@ -132,11 +110,7 @@ export const ChartLine = component2d({
       return
     }
 
-    // Spotlit: the whole line goes down to `dimOpacity`, then the stretches
-    // inside the region are re-drawn over it at full strength. Two passes rather
-    // than one dim + one bright *complementary* pair, so the bright run has
-    // continuous geometry through the region and its joins round the way an
-    // unspotlit line's do — and so the boundary lands exactly on the region edge.
+    // Dim the whole line, then redraw the stretches inside the region at full strength: the bright run keeps continuous geometry and round joins, and the boundary lands on the region edge.
     ctx.draw(
       new Graphics2D()
         .line({ points: drawn, radius })
@@ -144,9 +118,7 @@ export const ChartLine = component2d({
         .opacity(Math.max(0, Math.min(1, state.dimOpacity)))
     )
 
-    // One `draw` per run: shapes chained before a `stroke()` are combined into a
-    // single surface, and stroking a union of disjoint open paths doesn't paint
-    // — so a line that leaves the region and comes back would lose both halves.
+    // One `draw` per run: shapes chained before `stroke()` combine into one surface, and stroking a union of disjoint open paths paints nothing.
     for (const run of clipPolylineToBox(drawn, box)) {
       ctx.draw(new Graphics2D().line({ points: run, radius }).stroke(stroke))
     }

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

@@ -7,8 +7,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 as _Node2DProps,
   type Stroke,
   type StrokeResolved,
 } from "@motionscript/sdk"
@@ -23,29 +24,20 @@ import {
 } from "./shared"
 
 /**
- * The **region call-out** of a {@link LineChart}: a washed rectangle over the
- * plot with a dashed rule down each edge the author actually bounded. Sized and
- * positioned entirely from the pre-mapped `box` rather
- * than its own box — the region already carries the plot geometry.
- *
- * It draws only the *marking*; fading the series outside the region is
- * {@link ChartLine}'s job (it clips its own polyline against the same box), so
- * the two can't disagree about where the boundary is.
- *
- * Only bounded edges get a rule: a region given just an `x` range spans the full
- * plot height, so its top and bottom edges are the plot's own border, not a data
- * bound — drawing dashes there would assert a limit the author didn't set.
+ * The call-out of a {@link LineChart}: a washed rectangle with a dashed rule on
+ * each bounded edge, drawn from the pre-mapped `box`. Dimming the series outside
+ * is {@link ChartLine}'s job, clipped against the same box so the two agree on
+ * the boundary. An unbounded edge is the plot's own border, and a rule there
+ * would assert a limit the author did not set.
  */
 export const ChartRegion = component2d({
   key: "chartRegion",
   state: {
-    /** The highlighted slice, already resolved into this node's local pixel space (origin at centre, y-up) by the parent {@link LineChart}. A degenerate box draws nothing. */
+    /** In this node's pixel space (origin at centre, y-up), mapped by the parent. A degenerate box draws nothing. */
     box: fresh<RegionBox>(() => EMPTY_REGION_BOX),
-    /** Dashed rule marking each *bounded* edge of the box. */
     stroke: Types.custom<Stroke, StrokeResolved[]>(DEFAULT_CHART_THEME.region.stroke, { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
-    /** Wash filling the box, under the series lines. */
     fill: Types.custom<Fill, FillResolved[]>(DEFAULT_CHART_THEME.region.fill, { resolve: fillOps.resolve, lerp: fillOps.lerp }),
-    /** Reveal of the annotation in `[0, 1]`, driven by the chart's own `regionReveal` so the rules and the series' dimming move as one. */
+    /** Driven by the chart's `regionReveal`, so the rules and the series' dimming move as one. */
     reveal: 0,
   },
   load: (loader, state) => loadPaints(loader, { fills: [state.fill], strokes: [state.stroke] }),
@@ -61,18 +53,13 @@ export const ChartRegion = component2d({
     const cx = (box.left + box.right) / 2
     const cy = (box.bottom + box.top) / 2
 
-    // Wash first, so the rules sit over their own tint.
     if (state.fill.length > 0) {
       ctx.draw(new Graphics2D().rect({ x: cx, y: cy, width, height }).fill(state.fill).opacity(r))
     }
 
-    // One rule per bounded edge, growing from the region's centre outward as
-    // `reveal` climbs — the same "trace it in" beat as the series lines.
     if (state.stroke.length === 0) return
 
-    // One `draw` per rule rather than four line ops under a single paint:
-    // shapes chained before a `stroke()` are combined into one surface, and
-    // stroking a union of disjoint open paths doesn't paint.
+    // One `draw` per rule: stroking a union of disjoint open paths paints nothing.
     const rule = (points: { x: number; y: number }[]) =>
       ctx.draw(new Graphics2D().line({ points }).stroke(state.stroke).opacity(r))
 

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

@@ -7,67 +7,50 @@ import {
   textOps,
   type NodeOf,
   type Node2D,
+  type Node2DProps as _Node2DProps,
 } from "@motionscript/sdk";
+import { enterBudget } from "@motionscript/sdk/component";
 
 import { asParts, fresh } from "../kit/entries";
 import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "../kit/motion";
 import {
   DEFAULT_X_AXIS,
-  enterBudget,
   type AxisConfig,
   type Range,
 } from "../kit/shared";
 import { markerCaption } from "../kit/vertical-axis";
 
-/** How far a marker starts above its slot when it enters, in px. */
 const SLIDE = 24;
 
 /**
- * The horizontal axis of a {@link LineChart}: a **row of {@link Text} nodes**,
- * one per marker value, running left-to-right. Pure layout — the mirror of the
- * kit's `VerticalAxis`, including its bound (not snapshotted) marker text and
- * positions, and its landed resting state.
- *
- * Markers are always placed **by value** across the range, whatever they say:
- * `2026-03` sits three months along, not three slots along. That is what keeps
- * it distinct from a bar chart's bottom axis, which centres a caption on each
- * slot and has no scale at all — the two only look alike. What the values are
- * captioned *as* is the chart's to decide, in `captions`.
- *
- * `enter` staggers the markers in **left-to-right**: each starts lifted a
- * little above its slot and transparent, then fades and slides down into place.
+ * The horizontal axis of a {@link LineChart}: a row of {@link Text} markers, the
+ * mirror of `VerticalAxis` (bound text and positions, landed resting state).
+ * Markers are placed by value across the range, whatever they say: `2026-03`
+ * sits three months along, not three slots along, unlike a bar chart's axis.
  */
 export const HorizontalAxis = component2d({
   key: "horizontalAxis",
   state: {
-    /** `[min, max]` of the horizontal scale the markers are positioned within. */
     range: fresh<Range>(() => [0, 1]),
-    /** Tick values (in data units) to draw along the axis. */
+    /** Tick values in data units. */
     markers: fresh<number[]>(() => []),
-    /**
-     * How each marker is captioned, one per entry of `markers` and in its order.
-     * Empty (the default), or short, captions a marker with its bare numeric
-     * reading; a chart whose x column names months or categories writes those.
-     */
+    /** One caption per marker in its order; a missing one reads as the bare numeric value. */
     captions: fresh<string[]>(() => []),
-    /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */
     axis: Types.custom<AxisConfig>(DEFAULT_X_AXIS),
-    /** Caption drawn centred in the gutter beneath the marker row; empty (the default) hides it. */
+    /** Caption centred beneath the markers; empty hides it. */
     label: "",
     arrivals: arrivalsEntry(),
   },
-  // A plain node filled its parent; one made of its markers would hug them.
+  // A node made of markers would otherwise hug them.
   defaults: { width: "fill", height: "fill" },
   children: (state) => {
     const tickPad = insetsOps.resolve(state.axis.tickPadding).top;
     const titlePad = insetsOps.resolve(state.axis.titlePadding).top;
 
     const column: Node2D[] = [];
-    // The column's parent is the axis: its box is what the markers are placed in.
+    // The column's parent is the axis, whose box the markers are placed in.
     const box = () => (column[0]?.parent as Node2D | null | undefined)?.layoutBounds ?? { width: 0, height: 0 };
-    /** The live tick values, left → right — re-read every frame, not snapshotted. */
     const sorted = () => [...state.markers].sort((a, b) => a - b);
-    /** Tick `i`'s fraction across the live `range`, 0 at the left edge. */
     const fracAt = (value: number | undefined) => {
       if (value === undefined) return 0;
       const [min, max] = state.range;
@@ -84,12 +67,7 @@ export const HorizontalAxis = component2d({
         x: () => {
           const width = box().width;
           const centred = (fracAt(sorted()[i]) - 0.5) * width;
-          // Held inside the axis's right edge, which is also the *chart's*: the
-          // last marker is centred on the last grid line, so half of `2026-06`
-          // — or of `3300` — would be drawn outside the node's box and outside
-          // the rectangle the editor draws around it. Only the right edge is
-          // held, because the left one has the vertical axis's whole gutter
-          // beyond it, and a marker overhanging into that is inside the chart.
+          // Held inside the right edge, the chart's own: the last marker is centred on the last grid line, so half of it would fall outside the box. The left edge has the vertical axis's gutter beyond it.
           const limit = width / 2 - marker.layoutBounds.width / 2;
           return Math.min(centred, limit);
         },
@@ -117,13 +95,7 @@ export const HorizontalAxis = component2d({
     return asParts(column);
   },
   commands: {
-    /**
-     * Stagger the markers in left to right, then slide the caption in after
-     * them. Its first frame arms them all: lifted by `slide` and transparent.
-     *
-     * The timeline's duration is the **whole** entrance — see
-     * `VerticalAxis.enter` and {@link enterBudget}.
-     */
+    /** Stagger markers in left to right, then the caption. The duration is the whole entrance ({@link enterBudget}). */
     enter: {
       args: {
         stagger: Types.custom<number | undefined>(undefined),
@@ -139,7 +111,6 @@ export const HorizontalAxis = component2d({
         if (count === 0) return arm;
         const { step, per, caption } = enterBudget(timeline.duration, count, captioned, stagger);
         const ease = frameEase(timeline);
-        // Left marker leads: the row is already left → right.
         const markers = state.markers.map((_, i) => ({ at: i * step, duration: per, piece: arrival(timeline, i, from, ease) }));
         const label = captioned ? [{ at: (count - 1) * step + per, duration: caption, piece: arrival(timeline, "label", from, ease) }] : [];
         return timeline.together([arm, beats(timeline, [...markers, ...label])]);

package/src/line-chart/index.ts

@@ -1,17 +1,5 @@
-/**
- * The line chart: a cartesian plot with a traced polyline, spotlit regions and
- * a staggered entrance.
- *
- * {@link LineChart} composes the parts below plus the shared ones in the kit
- * (the plot panel, the value axis, the legend); each part is exported too, so
- * another node type can reuse one on its own.
- *
- * These files are what a copy of the line chart takes (`registry.json`). Everything they reach for
- * that is *not* here comes from the kit and stays a dependency — see
- * `../engine.ts` for why that line is where it is.
- */
 export { LineChart, lineChartDomains } from "./line-chart"
-export type { LineChartDomains, LineChartProps, LineChartValues } from "./line-chart"
+export type { LineChartDomains, LineChartValues } from "./line-chart"
 export { ChartRegion } from "./chart-region"
 export { ChartLine } from "./chart-line"
 export { HorizontalAxis } from "./horizontal-axis"