@motionscript/charts 0.1.1-alpha.0 → 0.1.1-alpha.1

package/dist/kit/vertical-axis.js

@@ -1,5 +1,6 @@
-import { Rect, RotatedBox, Text, Types, component2d, insetsOps, textOps, } from "@motionscript/sdk";
+import { Rect, RotatedBox, Text, Types, component2d, insetsOps, } from "@motionscript/sdk";
 import { enterBudget } from "@motionscript/sdk/component";
+import { boundText } from "./cartesian.js";
 import { asParts, fresh } from "./entries.js";
 import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase } from "./motion.js";
 import { DEFAULT_Y_AXIS, formatMarker, } from "./shared.js";
@@ -9,11 +10,53 @@ export function markerCaption(s, value) {
     const index = s.markers.indexOf(value);
     return (index >= 0 ? s.captions[index] : undefined) ?? formatMarker(value);
 }
+/** The gap between an axis's markers and the plot, and between the markers and the caption, read off its config. */
+export function axisPads(axis, side) {
+    return { tick: insetsOps.resolve(axis.tickPadding)[side], title: insetsOps.resolve(axis.titlePadding)[side] };
+}
+/**
+ * A column of right-aligned captions beside the plot: `place(i)` is caption
+ * `i`'s centre height in the column (y-up), whose height it is handed. The
+ * value axis and a horizontal bar chart's category axis are both this column.
+ */
+export function captionColumn(spec) {
+    const pads = () => axisPads(spec.axis(), "right");
+    const markers = Array.from({ length: spec.count }, (_, i) => {
+        const column = () => marker.parent?.layoutBounds ?? { width: 0, height: 0 };
+        const marker = new Text({
+            ...boundText(() => spec.axis().labelStyle),
+            text: () => spec.text(i),
+            // Right-aligned against the tick padding: freeform children sit on the content box's centre.
+            x: () => (column().width - pads().tick) / 2 - marker.layoutBounds.width / 2 + arrivalOf(spec.arrivals(), i).shift,
+            y: () => spec.place(i, column().height),
+            opacity: () => arrivalOf(spec.arrivals(), i).opacity * (spec.opacity?.(i) ?? 1),
+        });
+        return marker;
+    });
+    const children = [];
+    if (spec.label !== "") {
+        // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
+        children.push(new RotatedBox({
+            angle: -90,
+            width: "hug",
+            height: "hug",
+            children: new Text({
+                ...boundText(() => spec.axis().titleStyle),
+                text: spec.label,
+                opacity: () => arrivalOf(spec.arrivals(), "label").opacity,
+                x: () => arrivalOf(spec.arrivals(), "label").shift,
+            }),
+        }));
+    }
+    children.push(new Rect({ height: "fill", width: "hug", padding: () => ({ right: pads().tick }), children: markers }));
+    return new Rect({ flow: "horizontal", gap: () => pads().title, height: "fill", children });
+}
 /**
  * The numeric vertical axis the cartesian charts share: a column of {@link Text}
  * markers, highest at the top, each centred on its value's fraction across
- * `range`. Caption and position are bound, so a rescale tweens live; only the
- * marker count is fixed at construction. The resting state is landed.
+ * `range` and right-aligned against the plot. Caption and position are bound, so
+ * a rescale tweens live; only the marker count is fixed at construction. The
+ * resting state is landed.
  */
 export const VerticalAxis = component2d({
     key: "verticalAxis",
@@ -31,11 +74,6 @@ export const VerticalAxis = component2d({
     // A node made of markers would otherwise hug them.
     defaults: { width: "fill", height: "fill" },
     children: (state) => {
-        const tickPad = insetsOps.resolve(state.axis.tickPadding).right;
-        const titlePad = insetsOps.resolve(state.axis.titlePadding).right;
-        const row = [];
-        // The row's parent is the axis, whose box the markers are placed in.
-        const box = () => row[0]?.parent?.layoutBounds ?? { width: 0, height: 0 };
         const sorted = () => [...state.markers].sort((a, b) => b - a);
         const fracAt = (value) => {
             if (value === undefined)
@@ -44,44 +82,19 @@ export const VerticalAxis = component2d({
             return max <= min ? 0 : (value - min) / (max - min);
         };
         // A slot with no value (the live list is shorter than the column built) renders empty, not its neighbour.
-        const markers = state.markers.map((_, i) => {
-            const marker = new Text({
-                ...textOps.styleProps(state.axis.labelStyle),
-                text: () => {
+        return asParts([
+            captionColumn({
+                count: state.markers.length,
+                axis: () => state.axis,
+                text: (i) => {
                     const value = sorted()[i];
                     return value === undefined ? "" : markerCaption(state, value);
                 },
-                y: () => {
-                    // Node2D space is y-up, so the fraction runs from the bottom.
-                    const height = box().height;
-                    const centred = (fracAt(sorted()[i]) - 0.5) * height;
-                    // Held inside the top edge for a theme whose markers are taller than the headroom; only the top, since the chart's own axis and legend lie below.
-                    const limit = height / 2 - marker.layoutBounds.height / 2;
-                    return Math.min(centred, limit);
-                },
-                opacity: () => arrivalOf(state.arrivals, i).opacity,
-                x: () => arrivalOf(state.arrivals, i).shift,
-            });
-            return marker;
-        });
-        const children = [];
-        if (state.label !== "") {
-            // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
-            children.push(new RotatedBox({
-                angle: -90,
-                width: "hug",
-                height: "hug",
-                children: new Text({
-                    ...textOps.styleProps(state.axis.titleStyle),
-                    text: state.label,
-                    opacity: () => arrivalOf(state.arrivals, "label").opacity,
-                    x: () => arrivalOf(state.arrivals, "label").shift,
-                }),
-            }));
-        }
-        children.push(new Rect({ height: "fill", width: "hug", padding: { right: tickPad }, children: markers }));
-        row.push(new Rect({ flow: "horizontal", gap: titlePad, children }));
-        return asParts(row);
+                place: (i, height) => (fracAt(sorted()[i]) - 0.5) * height,
+                arrivals: () => state.arrivals,
+                label: state.label,
+            }),
+        ]);
     },
     commands: {
         /**

package/dist/kit/vertical-axis.js.map

@@ -1 +1 @@
-{"version":3,"file":"vertical-axis.js","sourceRoot":"","sources":["../../src/kit/vertical-axis.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  Rect,\n  RotatedBox,\n  Text,\n  Types,\n  component2d,\n  insetsOps,\n  textOps,\n  type NodeOf,\n  // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.\n  type Node2D,\n  type Node2DProps as _Node2DProps,\n} from \"@motionscript/sdk\"\nimport { enterBudget } from \"@motionscript/sdk/component\"\n\nimport { asParts, fresh } from \"./entries\"\nimport { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from \"./motion\"\nimport {\n  DEFAULT_Y_AXIS,\n  formatMarker,\n  type AxisConfig,\n  type Range,\n} from \"./shared\"\n\nconst SLIDE = 24\n\n/** What a marker's caption reads: the one listed for its value, else its bare reading. */\nexport function markerCaption(s: { readonly markers: readonly number[]; readonly captions: readonly string[] }, value: number): string {\n  const index = s.markers.indexOf(value)\n  return (index >= 0 ? s.captions[index] : undefined) ?? formatMarker(value)\n}\n\n/**\n * The numeric vertical axis the cartesian charts share: a column of {@link Text}\n * markers, highest at the top, each centred on its value's fraction across\n * `range`. Caption and position are bound, so a rescale tweens live; only the\n * marker count is fixed at construction. The resting state is landed.\n */\nexport const VerticalAxis = component2d({\n  key: \"verticalAxis\",\n  state: {\n    range: fresh<Range>(() => [0, 1]),\n    /** Tick values in data units, each placed by its fraction across `range`; need not be even or include the ends. */\n    markers: fresh<number[]>(() => []),\n    /** One caption per marker in its order; a missing one reads as the bare numeric value. */\n    captions: fresh<string[]>(() => []),\n    axis: Types.custom<AxisConfig>(DEFAULT_Y_AXIS),\n    /** Rotated caption in the gutter left of the markers; empty builds no caption node and reserves no gutter. */\n    label: \"\",\n    arrivals: arrivalsEntry(),\n  },\n  // A node made of markers would otherwise hug them.\n  defaults: { width: \"fill\", height: \"fill\" },\n  children: (state) => {\n    const tickPad = insetsOps.resolve(state.axis.tickPadding).right\n    const titlePad = insetsOps.resolve(state.axis.titlePadding).right\n\n    const row: Node2D[] = []\n    // The row's parent is the axis, whose box the markers are placed in.\n    const box = () => (row[0]?.parent as Node2D | null | undefined)?.layoutBounds ?? { width: 0, height: 0 }\n    const sorted = () => [...state.markers].sort((a, b) => b - a)\n    const fracAt = (value: number | undefined) => {\n      if (value === undefined) return 0\n      const [min, max] = state.range\n      return max <= min ? 0 : (value - min) / (max - min)\n    }\n\n    // A slot with no value (the live list is shorter than the column built) renders empty, not its neighbour.\n    const markers = state.markers.map((_, i) => {\n      const marker: Node2D = new Text({\n        ...textOps.styleProps(state.axis.labelStyle),\n        text: () => {\n          const value = sorted()[i]\n          return value === undefined ? \"\" : markerCaption(state, value)\n        },\n        y: () => {\n          // Node2D space is y-up, so the fraction runs from the bottom.\n          const height = box().height\n          const centred = (fracAt(sorted()[i]) - 0.5) * height\n          // Held inside the top edge for a theme whose markers are taller than the headroom; only the top, since the chart's own axis and legend lie below.\n          const limit = height / 2 - marker.layoutBounds.height / 2\n          return Math.min(centred, limit)\n        },\n        opacity: () => arrivalOf(state.arrivals, i).opacity,\n        x: () => arrivalOf(state.arrivals, i).shift,\n      })\n      return marker\n    })\n\n    const children: Node2D[] = []\n    if (state.label !== \"\") {\n      // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.\n      children.push(\n        new RotatedBox({\n          angle: -90,\n          width: \"hug\",\n          height: \"hug\",\n          children: new Text({\n            ...textOps.styleProps(state.axis.titleStyle),\n            text: state.label,\n            opacity: () => arrivalOf(state.arrivals, \"label\").opacity,\n            x: () => arrivalOf(state.arrivals, \"label\").shift,\n          }),\n        })\n      )\n    }\n    children.push(new Rect({ height: \"fill\", width: \"hug\", padding: { right: tickPad }, children: markers }))\n    row.push(new Rect({ flow: \"horizontal\", gap: titlePad, children }))\n    return asParts(row)\n  },\n  commands: {\n    /**\n     * Stagger markers in bottom to top, then the caption. The duration is the\n     * whole entrance ({@link enterBudget}). `stagger` is seconds between markers\n     * (derived when omitted); `slide` is the starting rightward offset in px.\n     */\n    enter: {\n      args: {\n        stagger: Types.custom<number | undefined>(undefined),\n        slide: Types.number(SLIDE),\n      },\n      run: (timeline, state) => {\n        const { stagger, slide } = timeline.args\n        const count = state.markers.length\n        const captioned = state.label !== \"\"\n        const from: Arrival = { opacity: 0, shift: slide }\n        const keys = [...state.markers.keys(), ...(captioned ? [\"label\"] : [])]\n        const arm = timeline.animate(() => ({ arrivals: armed(keys, from) }))\n        if (count === 0) return arm\n        const { step, per, caption } = enterBudget(timeline.duration, count, captioned, stagger)\n        const ease = frameEase(timeline)\n        // The bottom marker leads, so walk the top-to-bottom column in reverse.\n        const markers = state.markers.map((_, i) => ({ at: (count - 1 - i) * step, duration: per, piece: arrival(timeline, i, from, ease) }))\n        const label = captioned ? [{ at: (count - 1) * step + per, duration: caption, piece: arrival(timeline, \"label\", from, ease) }] : []\n        return timeline.together([arm, beats(timeline, [...markers, ...label])])\n      },\n    },\n  },\n})\n\nexport type VerticalAxis = NodeOf<typeof VerticalAxis>\n"]}
+{"version":3,"file":"vertical-axis.js","sourceRoot":"","sources":["../../src/kit/vertical-axis.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  Rect,\n  RotatedBox,\n  Text,\n  Types,\n  component2d,\n  insetsOps,\n  type NodeOf,\n  // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.\n  type Node2D,\n  type Node2DProps as _Node2DProps,\n} from \"@motionscript/sdk\"\nimport { enterBudget } from \"@motionscript/sdk/component\"\n\nimport { boundText } from \"./cartesian\"\nimport { asParts, fresh } from \"./entries\"\nimport { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from \"./motion\"\nimport {\n  DEFAULT_Y_AXIS,\n  formatMarker,\n  type AxisConfig,\n  type Range,\n} from \"./shared\"\n\nconst SLIDE = 24\n\n/** What a marker's caption reads: the one listed for its value, else its bare reading. */\nexport function markerCaption(s: { readonly markers: readonly number[]; readonly captions: readonly string[] }, value: number): string {\n  const index = s.markers.indexOf(value)\n  return (index >= 0 ? s.captions[index] : undefined) ?? formatMarker(value)\n}\n\n/** The gap between an axis's markers and the plot, and between the markers and the caption, read off its config. */\nexport function axisPads(axis: AxisConfig, side: \"top\" | \"right\"): { tick: number; title: number } {\n  return { tick: insetsOps.resolve(axis.tickPadding)[side], title: insetsOps.resolve(axis.titlePadding)[side] }\n}\n\n/**\n * A column of right-aligned captions beside the plot: `place(i)` is caption\n * `i`'s centre height in the column (y-up), whose height it is handed. The\n * value axis and a horizontal bar chart's category axis are both this column.\n */\nexport function captionColumn(spec: {\n  readonly count: number\n  readonly axis: () => AxisConfig\n  readonly text: (i: number) => string\n  readonly place: (i: number, height: number) => number\n  readonly arrivals: () => Readonly<Record<string, Arrival>>\n  readonly opacity?: (i: number) => number\n  readonly label: string\n}): Node2D {\n  const pads = () => axisPads(spec.axis(), \"right\")\n  const markers = Array.from({ length: spec.count }, (_, i) => {\n    const column = () => (marker.parent as Node2D | null)?.layoutBounds ?? { width: 0, height: 0 }\n    const marker: Node2D = new Text({\n      ...boundText(() => spec.axis().labelStyle),\n      text: () => spec.text(i),\n      // Right-aligned against the tick padding: freeform children sit on the content box's centre.\n      x: () => (column().width - pads().tick) / 2 - marker.layoutBounds.width / 2 + arrivalOf(spec.arrivals(), i).shift,\n      y: () => spec.place(i, column().height),\n      opacity: () => arrivalOf(spec.arrivals(), i).opacity * (spec.opacity?.(i) ?? 1),\n    })\n    return marker\n  })\n  const children: Node2D[] = []\n  if (spec.label !== \"\") {\n    // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.\n    children.push(\n      new RotatedBox({\n        angle: -90,\n        width: \"hug\",\n        height: \"hug\",\n        children: new Text({\n          ...boundText(() => spec.axis().titleStyle),\n          text: spec.label,\n          opacity: () => arrivalOf(spec.arrivals(), \"label\").opacity,\n          x: () => arrivalOf(spec.arrivals(), \"label\").shift,\n        }),\n      }) as unknown as Node2D\n    )\n  }\n  children.push(new Rect({ height: \"fill\", width: \"hug\", padding: () => ({ right: pads().tick }), children: markers }) as unknown as Node2D)\n  return new Rect({ flow: \"horizontal\", gap: () => pads().title, height: \"fill\", children }) as unknown as Node2D\n}\n\n/**\n * The numeric vertical axis the cartesian charts share: a column of {@link Text}\n * markers, highest at the top, each centred on its value's fraction across\n * `range` and right-aligned against the plot. Caption and position are bound, so\n * a rescale tweens live; only the marker count is fixed at construction. The\n * resting state is landed.\n */\nexport const VerticalAxis = component2d({\n  key: \"verticalAxis\",\n  state: {\n    range: fresh<Range>(() => [0, 1]),\n    /** Tick values in data units, each placed by its fraction across `range`; need not be even or include the ends. */\n    markers: fresh<number[]>(() => []),\n    /** One caption per marker in its order; a missing one reads as the bare numeric value. */\n    captions: fresh<string[]>(() => []),\n    axis: Types.custom<AxisConfig>(DEFAULT_Y_AXIS),\n    /** Rotated caption in the gutter left of the markers; empty builds no caption node and reserves no gutter. */\n    label: \"\",\n    arrivals: arrivalsEntry(),\n  },\n  // A node made of markers would otherwise hug them.\n  defaults: { width: \"fill\", height: \"fill\" },\n  children: (state) => {\n    const sorted = () => [...state.markers].sort((a, b) => b - a)\n    const fracAt = (value: number | undefined) => {\n      if (value === undefined) return 0\n      const [min, max] = state.range\n      return max <= min ? 0 : (value - min) / (max - min)\n    }\n    // A slot with no value (the live list is shorter than the column built) renders empty, not its neighbour.\n    return asParts([\n      captionColumn({\n        count: state.markers.length,\n        axis: () => state.axis,\n        text: (i) => {\n          const value = sorted()[i]\n          return value === undefined ? \"\" : markerCaption(state, value)\n        },\n        place: (i, height) => (fracAt(sorted()[i]) - 0.5) * height,\n        arrivals: () => state.arrivals,\n        label: state.label,\n      }),\n    ])\n  },\n  commands: {\n    /**\n     * Stagger markers in bottom to top, then the caption. The duration is the\n     * whole entrance ({@link enterBudget}). `stagger` is seconds between markers\n     * (derived when omitted); `slide` is the starting rightward offset in px.\n     */\n    enter: {\n      args: {\n        stagger: Types.custom<number | undefined>(undefined),\n        slide: Types.number(SLIDE),\n      },\n      run: (timeline, state) => {\n        const { stagger, slide } = timeline.args\n        const count = state.markers.length\n        const captioned = state.label !== \"\"\n        const from: Arrival = { opacity: 0, shift: slide }\n        const keys = [...state.markers.keys(), ...(captioned ? [\"label\"] : [])]\n        const arm = timeline.animate(() => ({ arrivals: armed(keys, from) }))\n        if (count === 0) return arm\n        const { step, per, caption } = enterBudget(timeline.duration, count, captioned, stagger)\n        const ease = frameEase(timeline)\n        // The bottom marker leads, so walk the top-to-bottom column in reverse.\n        const markers = state.markers.map((_, i) => ({ at: (count - 1 - i) * step, duration: per, piece: arrival(timeline, i, from, ease) }))\n        const label = captioned ? [{ at: (count - 1) * step + per, duration: caption, piece: arrival(timeline, \"label\", from, ease) }] : []\n        return timeline.together([arm, beats(timeline, [...markers, ...label])])\n      },\n    },\n  },\n})\n\nexport type VerticalAxis = NodeOf<typeof VerticalAxis>\n"]}

package/dist/line-chart/chart-line.d.ts

@@ -1,10 +1,20 @@
-import { type NodeOf, type Node2D as _Node2D, type Node2DProps as _Node2DProps, type Stroke, type StrokeResolved, type Vector2 } from "@motionscript/sdk";
-import { type RegionBox } from "./shared.js";
-/** 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. */
+import { type Fill, type FillResolved, type NodeOf, type Node2D as _Node2D, type Node2DProps as _Node2DProps, type Stroke, type StrokeResolved, type Vector2 } from "@motionscript/sdk";
+import { type LineCurve, type RegionBox } from "./shared.js";
+/** The x a trace at `progress` has reached, across `points` ordered along x. */
+export declare function traceX(points: readonly Vector2[], progress: number): number;
+/**
+ * One series of a {@link LineChart}: its line through pre-mapped pixel `points`,
+ * shaped by `curve`, and a dot on each point. `progress` traces it in from the
+ * left; `enabled` shows or hides it wholesale.
+ */
 export declare const ChartLine: import("@motionscript/sdk").Component<"chartLine", import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
     /** In this node's pixel space (origin at centre, y-up), mapped by the parent and ordered along x. */
     readonly points: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    readonly curve: import("@motionscript/sdk").Type<LineCurve, LineCurve, false>;
     readonly stroke: import("@motionscript/sdk").Type<Stroke, StrokeResolved[], false>;
+    /** A dot of `dotSize` on each point, in `dotFill`; none at size 0. */
+    readonly dotSize: 0;
+    readonly dotFill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
     /** Trace from the left end, `[0, 1]`. Rests at 1 so a paused editor canvas paints the line; `enter` drives it from 0. */
     readonly progress: 1;
     /** Whether the line is drawn at all, flipped alongside its legend entry. */
@@ -17,10 +27,17 @@ export declare const ChartLine: import("@motionscript/sdk").Component<"chartLine
         readonly from: import("@motionscript/sdk").Type<number, number, false>;
         readonly to: import("@motionscript/sdk").Type<number, number, false>;
     };
+    readonly hold: {
+        readonly shown: import("@motionscript/sdk").Type<boolean, boolean, false>;
+    };
 }, null, _Node2D<_Node2DProps>, import("@motionscript/sdk").CallProps<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
     /** In this node's pixel space (origin at centre, y-up), mapped by the parent and ordered along x. */
     readonly points: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    readonly curve: import("@motionscript/sdk").Type<LineCurve, LineCurve, false>;
     readonly stroke: import("@motionscript/sdk").Type<Stroke, StrokeResolved[], false>;
+    /** A dot of `dotSize` on each point, in `dotFill`; none at size 0. */
+    readonly dotSize: 0;
+    readonly dotFill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
     /** Trace from the left end, `[0, 1]`. Rests at 1 so a paused editor canvas paints the line; `enter` drives it from 0. */
     readonly progress: 1;
     /** Whether the line is drawn at all, flipped alongside its legend entry. */
@@ -31,7 +48,11 @@ export declare const ChartLine: import("@motionscript/sdk").Component<"chartLine
 }>, null, import("@motionscript/sdk").BuiltNode<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
     /** In this node's pixel space (origin at centre, y-up), mapped by the parent and ordered along x. */
     readonly points: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    readonly curve: import("@motionscript/sdk").Type<LineCurve, LineCurve, false>;
     readonly stroke: import("@motionscript/sdk").Type<Stroke, StrokeResolved[], false>;
+    /** A dot of `dotSize` on each point, in `dotFill`; none at size 0. */
+    readonly dotSize: 0;
+    readonly dotFill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
     /** Trace from the left end, `[0, 1]`. Rests at 1 so a paused editor canvas paints the line; `enter` drives it from 0. */
     readonly progress: 1;
     /** Whether the line is drawn at all, flipped alongside its legend entry. */
@@ -44,6 +65,77 @@ export declare const ChartLine: import("@motionscript/sdk").Component<"chartLine
         readonly from: import("@motionscript/sdk").Type<number, number, false>;
         readonly to: import("@motionscript/sdk").Type<number, number, false>;
     };
+    readonly hold: {
+        readonly shown: import("@motionscript/sdk").Type<boolean, boolean, false>;
+    };
 }, _Node2D<_Node2DProps>>>>;
 export type ChartLine = NodeOf<typeof ChartLine>;
+/**
+ * The fill under one series of a {@link LineChart}: down to `base` (the series
+ * below it in a stack) or, without one, to the `baseline`. Drawn by its own node
+ * so every area sits under every line; the chart binds its trace, switch and
+ * opacity to its line's, so the two move as one.
+ */
+export declare const ChartArea: import("@motionscript/sdk").Component<"chartArea", import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    /** The series' points, as its line has them. */
+    readonly points: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    /** The line the area fills down to, at the same x positions; empty for the baseline. */
+    readonly base: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    /** Pixel y of the baseline. */
+    readonly baseline: 0;
+    readonly curve: import("@motionscript/sdk").Type<LineCurve, LineCurve, false>;
+    readonly area: import("@motionscript/sdk").Type<"none" | "solid" | "gradient", "none" | "solid" | "gradient", false>;
+    /** The series colour; the area paints it at `areaOpacity`, a gradient fading it out towards the bottom. */
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+    readonly areaOpacity: 0.4;
+    readonly progress: 1;
+    readonly enabled: true;
+    readonly spotlight: import("@motionscript/sdk").Type<RegionBox, RegionBox, false>;
+    readonly dimOpacity: 0.2;
+}>, {}, null, _Node2D<_Node2DProps>, import("@motionscript/sdk").CallProps<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    /** The series' points, as its line has them. */
+    readonly points: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    /** The line the area fills down to, at the same x positions; empty for the baseline. */
+    readonly base: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    /** Pixel y of the baseline. */
+    readonly baseline: 0;
+    readonly curve: import("@motionscript/sdk").Type<LineCurve, LineCurve, false>;
+    readonly area: import("@motionscript/sdk").Type<"none" | "solid" | "gradient", "none" | "solid" | "gradient", false>;
+    /** The series colour; the area paints it at `areaOpacity`, a gradient fading it out towards the bottom. */
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+    readonly areaOpacity: 0.4;
+    readonly progress: 1;
+    readonly enabled: true;
+    readonly spotlight: import("@motionscript/sdk").Type<RegionBox, RegionBox, false>;
+    readonly dimOpacity: 0.2;
+}>, null, import("@motionscript/sdk").BuiltNode<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    /** The series' points, as its line has them. */
+    readonly points: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    /** The line the area fills down to, at the same x positions; empty for the baseline. */
+    readonly base: import("@motionscript/sdk").Type<Vector2[], Vector2[], false>;
+    /** Pixel y of the baseline. */
+    readonly baseline: 0;
+    readonly curve: import("@motionscript/sdk").Type<LineCurve, LineCurve, false>;
+    readonly area: import("@motionscript/sdk").Type<"none" | "solid" | "gradient", "none" | "solid" | "gradient", false>;
+    /** The series colour; the area paints it at `areaOpacity`, a gradient fading it out towards the bottom. */
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+    readonly areaOpacity: 0.4;
+    readonly progress: 1;
+    readonly enabled: true;
+    readonly spotlight: import("@motionscript/sdk").Type<RegionBox, RegionBox, false>;
+    readonly dimOpacity: 0.2;
+}>, {}, _Node2D<_Node2DProps>>>>;
+interface Span {
+    readonly top: number;
+    readonly bottom: number;
+}
+/**
+ * The area's paint for an outline spanning `own`: the series colour at
+ * `opacity`, or for a gradient that colour fading to nearly nothing across
+ * `whole`. A gradient maps onto the bounds of the shape it fills, so its ends
+ * are placed in `own`'s unit box (y-up) at `whole`'s top and bottom.
+ */
+export declare function areaFill(colour: FillResolved[], area: "none" | "solid" | "gradient", opacity: number, whole: Span, own: Span): FillResolved[];
+export type ChartArea = NodeOf<typeof ChartArea>;
+export {};
 //# sourceMappingURL=chart-line.d.ts.map

package/dist/line-chart/chart-line.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chart-line.d.ts","sourceRoot":"","sources":["../../src/line-chart/chart-line.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,MAAM,EAEX,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,WAAW,IAAI,YAAY,EAChC,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,OAAO,EACb,MAAM,mBAAmB,CAAA;AAM1B,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,UAAU,CAAA;AAkCjB,oMAAoM;AACpM,eAAO,MAAM,SAAS;IAGlB,qGAAqG;;;IAGrG,yHAAyH;;IAEzH,4EAA4E;;IAE5E,6EAA6E;;;;;;;;;IAP7E,qGAAqG;;;IAGrG,yHAAyH;;IAEzH,4EAA4E;;IAE5E,6EAA6E;;;;IAP7E,qGAAqG;;;IAGrG,yHAAyH;;IAEzH,4EAA4E;;IAE5E,6EAA6E;;;;;;;;2BAyD/E,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,SAAS,CAAC,CAAA"}
+{"version":3,"file":"chart-line.d.ts","sourceRoot":"","sources":["../../src/line-chart/chart-line.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,IAAI,EACT,KAAK,YAAY,EACjB,KAAK,MAAM,EAEX,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,WAAW,IAAI,YAAY,EAGhC,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,OAAO,EACb,MAAM,mBAAmB,CAAA;AAO1B,OAAO,EAOL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,UAAU,CAAA;AAEjB,gFAAgF;AAChF,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK3E;AAuBD;;;;GAIG;AACH,eAAO,MAAM,SAAS;IAGlB,qGAAqG;;;;IAIrG,sEAAsE;;;IAGtE,yHAAyH;;IAEzH,4EAA4E;;IAE5E,6EAA6E;;;;;;;;;;;;IAX7E,qGAAqG;;;;IAIrG,sEAAsE;;;IAGtE,yHAAyH;;IAEzH,4EAA4E;;IAE5E,6EAA6E;;;;IAX7E,qGAAqG;;;;IAIrG,sEAAsE;;;IAGtE,yHAAyH;;IAEzH,4EAA4E;;IAE5E,6EAA6E;;;;;;;;;;;2BAyE/E,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,SAAS,CAAC,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;IAGlB,gDAAgD;;IAEhD,wFAAwF;;IAExF,+BAA+B;;;;IAI/B,2GAA2G;;;;;;;;IAR3G,gDAAgD;;IAEhD,wFAAwF;;IAExF,+BAA+B;;;;IAI/B,2GAA2G;;;;;;;;IAR3G,gDAAgD;;IAEhD,wFAAwF;;IAExF,+BAA+B;;;;IAI/B,2GAA2G;;;;;;;gCAkC7G,CAAA;AAEF,UAAU,IAAI;IACZ,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAYD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,YAAY,EAAE,CAY7I;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,SAAS,CAAC,CAAA"}

package/dist/line-chart/chart-line.js

@@ -1,49 +1,51 @@
-import { Graphics2D, Types, component2d, strokeOps, } from "@motionscript/sdk";
+import { Graphics2D, Types, clamp, component2d, fillOps, strokeOps, } from "@motionscript/sdk";
+import { fade } from "../kit/cartesian.js";
 import { fresh } from "../kit/entries.js";
 import { frameEase } from "../kit/motion.js";
 import { loadPaints } from "../kit/paints.js";
 import { SPOTLIGHT_DIM } from "../kit/shared.js";
-import { EMPTY_REGION_BOX, clipPolylineToBox, hasRegion, } from "./shared.js";
-/** 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, p) {
-    if (p >= 1 || pts.length < 2)
-        return pts;
-    if (p <= 0)
-        return [];
-    const segLen = [];
-    let total = 0;
-    for (let i = 1; i < pts.length; i++) {
-        const d = Math.hypot(pts[i].x - pts[i - 1].x, pts[i].y - pts[i - 1].y);
-        segLen.push(d);
-        total += d;
-    }
-    if (total === 0)
-        return pts;
-    let target = total * p;
-    const out = [pts[0]];
-    for (let i = 0; i < segLen.length; i++) {
-        if (target >= segLen[i]) {
-            out.push(pts[i + 1]);
-            target -= segLen[i];
-        }
-        else {
-            const t = segLen[i] === 0 ? 0 : target / segLen[i];
-            out.push({
-                x: pts[i].x + (pts[i + 1].x - pts[i].x) * t,
-                y: pts[i].y + (pts[i + 1].y - pts[i].y) * t,
-            });
-            break;
-        }
-    }
-    return out;
+import { EMPTY_REGION_BOX, clipPolygonToBox, clipPolylineToBox, cutAt, curvePoints, hasRegion, } from "./shared.js";
+/** The x a trace at `progress` has reached, across `points` ordered along x. */
+export function traceX(points, progress) {
+    if (points.length === 0)
+        return 0;
+    const first = points[0].x;
+    const last = points[points.length - 1].x;
+    return progress >= 1 ? Infinity : first + (last - first) * progress;
 }
-/** 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. */
+/** The drawn path at `progress`: the whole curve once traced, else the part left of the trace. */
+function traced(points, curve, progress) {
+    const path = curvePoints(points, curve);
+    return progress >= 1 ? path : cutAt(path, traceX(points, progress));
+}
+const curveEntry = () => Types.custom("smooth");
+/** A closed outline as path commands. */
+function outlineCommands(points) {
+    return [...points.map((p, i) => ({ type: i === 0 ? "M" : "L", x: p.x, y: p.y })), { type: "Z" }];
+}
+function fillOutline(ctx, outline, fill, opacity) {
+    if (outline.length < 3 || opacity <= 0)
+        return;
+    const { width, height } = ctx.size;
+    // A frame symmetric about the origin, so the outline draws where its points say rather than re-centred on itself.
+    const centerBounds = [-width / 2, -height / 2, width / 2, height / 2];
+    ctx.draw(new Graphics2D().path({ data: outlineCommands(outline), centerBounds }).fill(fill).opacity(opacity));
+}
+/**
+ * One series of a {@link LineChart}: its line through pre-mapped pixel `points`,
+ * shaped by `curve`, and a dot on each point. `progress` traces it in from the
+ * left; `enabled` shows or hides it wholesale.
+ */
 export const ChartLine = component2d({
     key: "chartLine",
     state: {
         /** In this node's pixel space (origin at centre, y-up), mapped by the parent and ordered along x. */
         points: fresh(() => []),
+        curve: curveEntry(),
         stroke: Types.custom([], { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
+        /** A dot of `dotSize` on each point, in `dotFill`; none at size 0. */
+        dotSize: 0,
+        dotFill: Types.custom([], { resolve: fillOps.resolve, lerp: fillOps.lerp }),
         /** 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 the line is drawn at all, flipped alongside its legend entry. */
@@ -52,7 +54,7 @@ export const ChartLine = component2d({
         spotlight: fresh(() => EMPTY_REGION_BOX),
         dimOpacity: SPOTLIGHT_DIM,
     },
-    load: (loader, state) => loadPaints(loader, { strokes: [state.stroke] }),
+    load: (loader, state) => loadPaints(loader, { fills: [state.dotFill], strokes: [state.stroke] }),
     commands: {
         /**
          * Trace the line from `from` to `to`; `showSeries`/`hideSeries` are this with
@@ -72,35 +74,145 @@ export const ChartLine = component2d({
                 });
             },
         },
+        /** Hold the line fully traced while its chart moves it, switched on throughout a show and off once a hide lands. */
+        hold: {
+            args: { shown: Types.boolean(true) },
+            run: (timeline) => {
+                const { shown } = timeline.args;
+                return timeline.animate((t) => ({ progress: 1, enabled: shown || t < 1 }), { eased: false });
+            },
+        },
     },
     render: (ctx, state) => {
         if (!state.enabled)
             return;
         const pts = state.points;
-        if (pts.length < 2)
+        const p = clamp(state.progress, 0, 1);
+        if (pts.length === 0 || p <= 0)
             return;
-        const p = Math.max(0, Math.min(1, state.progress));
-        if (p <= 0)
+        const box = state.spotlight;
+        const lit = hasRegion(box);
+        const dim = clamp(state.dimOpacity, 0, 1);
+        const stroke = state.stroke;
+        const weight = stroke[0]?.weight ?? 0;
+        const drawn = traced(pts, state.curve, p);
+        if (drawn.length >= 2 && weight > 0) {
+            // Rounded corners only where the line has corners to round.
+            const radius = state.curve === "linear" ? weight * 2 : 0;
+            ctx.draw(new Graphics2D().line({ points: drawn, radius }).stroke(stroke).opacity(lit ? dim : 1));
+            // One `draw` per run: shapes chained before `stroke()` combine into one surface, and stroking a union of disjoint open paths paints nothing.
+            if (lit)
+                for (const run of clipPolylineToBox(drawn, box))
+                    ctx.draw(new Graphics2D().line({ points: run, radius }).stroke(stroke));
+        }
+        const size = state.dotSize;
+        if (size <= 0)
             return;
-        const drawn = tracePoints(pts, p);
-        if (drawn.length < 2)
+        const reach = traceX(pts, p);
+        const bright = new Graphics2D();
+        const dimmed = new Graphics2D();
+        let brightAny = false;
+        let dimAny = false;
+        for (const pt of pts) {
+            // A dot grows in as the trace passes it.
+            const grown = reach === Infinity ? 1 : clamp((reach - pt.x) / (size * 2), 0, 1);
+            if (grown <= 0)
+                continue;
+            const inside = !lit || (pt.x >= box.left && pt.x <= box.right && pt.y >= box.bottom && pt.y <= box.top);
+            (inside ? bright : dimmed).ellipse({ x: pt.x, y: pt.y, width: size * grown, height: size * grown });
+            if (inside)
+                brightAny = true;
+            else
+                dimAny = true;
+        }
+        if (dimAny)
+            ctx.draw(dimmed.fill(state.dotFill).opacity(dim));
+        if (brightAny)
+            ctx.draw(bright.fill(state.dotFill));
+    },
+});
+/**
+ * The fill under one series of a {@link LineChart}: down to `base` (the series
+ * below it in a stack) or, without one, to the `baseline`. Drawn by its own node
+ * so every area sits under every line; the chart binds its trace, switch and
+ * opacity to its line's, so the two move as one.
+ */
+export const ChartArea = component2d({
+    key: "chartArea",
+    state: {
+        /** The series' points, as its line has them. */
+        points: fresh(() => []),
+        /** The line the area fills down to, at the same x positions; empty for the baseline. */
+        base: fresh(() => []),
+        /** Pixel y of the baseline. */
+        baseline: 0,
+        curve: curveEntry(),
+        area: Types.custom("solid"),
+        /** The series colour; the area paints it at `areaOpacity`, a gradient fading it out towards the bottom. */
+        fill: Types.custom([], { resolve: fillOps.resolve, lerp: fillOps.lerp }),
+        areaOpacity: 0.4,
+        progress: 1,
+        enabled: true,
+        spotlight: fresh(() => EMPTY_REGION_BOX),
+        dimOpacity: SPOTLIGHT_DIM,
+    },
+    load: (loader, state) => loadPaints(loader, { fills: [state.fill] }),
+    render: (ctx, state) => {
+        const pts = state.points;
+        const p = clamp(state.progress, 0, 1);
+        if (!state.enabled || state.area === "none" || pts.length < 2 || p <= 0 || state.fill.length === 0)
             return;
-        const stroke = state.stroke;
-        const radius = (stroke[0]?.weight ?? 0) * 2;
+        const outlineAt = (progress) => {
+            const top = traced(pts, state.curve, progress);
+            if (top.length < 2)
+                return [];
+            const base = state.base.length === pts.length
+                ? traced(state.base, state.curve, progress)
+                : [{ x: top[0].x, y: state.baseline }, { x: top[top.length - 1].x, y: state.baseline }];
+            return [...top, ...[...base].reverse()];
+        };
+        // The gradient spans the whole area's height, so it holds still while the area traces in and across a spotlight's cut.
+        const span = verticalSpan(outlineAt(1));
+        const paint = (outline, opacity) => fillOutline(ctx, outline, areaFill(state.fill, state.area, state.areaOpacity, span, verticalSpan(outline)), opacity);
+        const outline = outlineAt(p);
         const box = state.spotlight;
         if (!hasRegion(box)) {
-            ctx.draw(new Graphics2D().line({ points: drawn, radius }).stroke(stroke));
+            paint(outline, 1);
             return;
         }
-        // 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 })
-            .stroke(stroke)
-            .opacity(Math.max(0, Math.min(1, state.dimOpacity))));
-        // 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));
-        }
+        paint(outline, clamp(state.dimOpacity, 0, 1));
+        paint(clipPolygonToBox(outline, box), 1);
     },
 });
+function verticalSpan(points) {
+    let top = -Infinity;
+    let bottom = Infinity;
+    for (const p of points) {
+        if (p.y > top)
+            top = p.y;
+        if (p.y < bottom)
+            bottom = p.y;
+    }
+    return { top, bottom };
+}
+/**
+ * The area's paint for an outline spanning `own`: the series colour at
+ * `opacity`, or for a gradient that colour fading to nearly nothing across
+ * `whole`. A gradient maps onto the bounds of the shape it fills, so its ends
+ * are placed in `own`'s unit box (y-up) at `whole`'s top and bottom.
+ */
+export function areaFill(colour, area, opacity, whole, own) {
+    const top = colour[colour.length - 1];
+    if (area !== "gradient" || top?.type !== "solid" || !(own.top > own.bottom))
+        return fade(colour, opacity);
+    const [r, g, b, a] = top.color;
+    const middle = (own.top + own.bottom) / 2;
+    const half = (own.top - own.bottom) / 2;
+    return fillOps.resolve({
+        type: "linear-gradient",
+        colors: [[r, g, b, a * opacity], [r, g, b, a * opacity * 0.04]],
+        start: { x: 0, y: (whole.top - middle) / half },
+        end: { x: 0, y: (whole.bottom - middle) / half },
+    });
+}
 //# sourceMappingURL=chart-line.js.map