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

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

@@ -0,0 +1,347 @@
+import { Node2D, type Command, type CommandArgs, type DataRecord, type NodeConfig, type Node2DProps } from "@motionscript/core";
+import { type AxisDomainConfig } from "../kit/shared.js";
+import { type ChartTheme, type LineSeries, type PlotRegion } from "./shared.js";
+import { type Seekable } from "@motionscript/core/component";
+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
+     * {@link LineChart.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;
+}
+/**
+ * The two signals the region call-out is made of, as a props type for the
+ * commands that move them.
+ *
+ * Written out rather than reusing `LineChartProps` because the pair is what
+ * those commands actually touch, and because `regionReveal` is a signal of the
+ * chart's own rather than part of its authored props.
+ */
+type RegionState = {
+    region: PlotRegion | null;
+    regionReveal: number;
+};
+/**
+ * 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.
+ *
+ * The parts are laid out from this node's `layoutBounds`: a left gutter for the
+ * vertical axis, a bottom gutter for the horizontal axis, the plot filling
+ * what's left, and the legend row beneath the whole chart. Every child's
+ * position/size is bound reactively, so the chart re-flows if its box changes,
+ * and the series lines read the same resolved scales as the axes, so points land
+ * exactly on their markers.
+ *
+ * **Resting state is the finished chart.** Unlike the standalone component this
+ * was ported from, nothing is built hidden: the studio paints a node's Initial
+ * state on a paused canvas, and a chart that only appeared once a command had
+ * run would be edited blind. {@link enter} arms every part back to its
+ * pre-entrance state before animating, so the entrance itself is unchanged.
+ *
+ * Past the entrance, three things move the chart around:
+ * {@link showSeries}/{@link hideSeries}/{@link spotlightSeries} pick out a
+ * *series*, {@link spotlightRegion} marks a *slice of the plot* without changing
+ * the scale, and {@link zoomTo} rescales the axes so a slice fills the plot. The
+ * last two take the same {@link PlotRegion} and compose — a spotlit region
+ * resolves against the live scales, so it travels with a zoom.
+ */
+export declare class LineChart extends Node2D<LineChartProps> {
+    data: DataRecord[];
+    xField: string;
+    series: LineSeries[];
+    /**
+     * X/Y-axis data domain (label/range/ticks), tweenable and mappable like
+     * `theme`: the mapper merges a partial input onto the previous resolved
+     * domain (leaving `range`/`ticks` `undefined` — the auto-derive signal — on
+     * first resolution), and the tween interpolates them numerically, so
+     * `chart.to({ yAxis: { range: [0, 10] } }, 1)` smoothly rescales the plotted
+     * lines. Like `theme`, the axis *label* text is captured once at construction.
+     */
+    xAxis: AxisDomainConfig;
+    yAxis: AxisDomainConfig;
+    /**
+     * The chart's visual theme, tweenable and mappable like a `stroke`/`fill`
+     * prop: the mapper merges the author's partial input onto the previous
+     * resolved theme (or {@link DEFAULT_CHART_THEME} the first time) and resolves
+     * every leaf; the tween interpolates two resolved themes leaf-by-leaf, so
+     * `chart.to({ theme: next }, 1)` animates smoothly.
+     */
+    theme: ChartTheme;
+    /**
+     * The spotlit slice of the plot in data units, or `null` for none. Held as a
+     * plain reactive value rather than a tweened one: the box itself snaps, and
+     * the *animation* is {@link regionReveal} drawing the rules on and the lines
+     * dimming outside it.
+     */
+    region: PlotRegion | null;
+    /**
+     * How far the {@link region} call-out is drawn in, `[0, 1]` — the single
+     * signal behind both halves of the effect: the rules grow out and the wash
+     * fades up as it climbs, while every line's out-of-region stretch fades from
+     * full down to the theme's `region.dimOpacity`. At 0 a chart with a `region`
+     * set looks exactly like one without.
+     */
+    regionReveal: number;
+    /**
+     * Read once, in the constructor, like `series`: the legend is a part the
+     * chart builds or doesn't, so a change reaches it by rebuilding the node.
+     */
+    showLegend: boolean;
+    private vAxis;
+    private hAxis;
+    /** The plot panel — the box the grid, the lines and the region all share. */
+    private plotRect;
+    private legend;
+    private lines;
+    /**
+     * `this.theme` read back through its *resolved* shape: the property's declared
+     * type is the loose author-facing {@link ChartTheme} (so a partial theme is
+     * accepted), but the mapper always stores the fully-resolved
+     * {@link ChartConfig} at runtime — the same loose-declared/resolved-stored
+     * idiom as a shape's `fill`/`stroke`.
+     */
+    private get resolvedTheme();
+    /** Fallback marker count when neither axis's ticks are given. */
+    private static readonly DEFAULT_MARKERS;
+    /**
+     * 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`.
+     */
+    private get xColumn();
+    private get xScale();
+    private get yScale();
+    /** The vertical axis ticks: the explicit ones, else five across the scale. */
+    private get resolvedYMarkers();
+    /**
+     * The horizontal axis ticks: the explicit ones, else five across the scale.
+     *
+     * Asked of the column rather than spaced evenly, because only a numeric column
+     * has round numbers between its samples. On a month column, five evenly spaced
+     * values land two-thirds of the way through four different months; the ticks
+     * a reader wants are Jan/Apr/Jul/Oct/Dec, which are rows.
+     */
+    private get resolvedXMarkers();
+    /**
+     * The plot panel's size, **as laid out**.
+     *
+     * This used to be computed: six constants estimating what the axis gutters and
+     * the legend row would take, subtracted from the node's box. The estimate was
+     * never the layout — the vertical axis is `width: "hug"`, so its real width is
+     * whatever its widest marker needs — and everything downstream inherited the
+     * gap. The grid is drawn by {@link ChartCanvas} across its *own* allocation,
+     * while the lines were mapped across the estimate, so a series sat a few
+     * percent off the grid line it was supposed to touch, silently and by an
+     * amount that changed with the theme.
+     *
+     * Asking the panel is exact by construction and cannot drift: the lines, the
+     * region rules and the grid all resolve against one box, and it is the box
+     * they are drawn in. Zero until the first layout pass, like any other
+     * `layoutBounds` read — the bindings that call this re-run on the next frame.
+     */
+    private plotSize;
+    /**
+     * Map one series' data points into the plot's **centred** pixel space (origin
+     * at the plot centre, y-up) — the local frame of the clip/line box that fills
+     * the plot. x runs `[-w/2, +w/2]`, y runs `[-h/2, +h/2]`.
+     */
+    private seriesPixels;
+    /**
+     * {@link region} mapped into the plot's **centred** pixel space — the same
+     * frame {@link seriesPixels} returns, so the region's rules and each line's
+     * clip resolve against one box from one place. Reads the live scales, so it
+     * re-maps when `xAxis`/`yAxis` tween.
+     */
+    /**
+     * Whether a call-out is authored at all — the question {@link enter} and
+     * {@link spotlightRegion} branch on.
+     *
+     * Deliberately **not** `hasRegion(this.regionBox())`, which they used to ask.
+     * That resolves the region into pixels, so it answers "and has the chart been
+     * laid out yet" as well, and comes back false for a perfectly real region on a
+     * chart that has not been measured. A generator never noticed, because it only
+     * ever ran mid-playback; a command is *built* before the first layout pass, and
+     * would have quietly dropped the region beat every time.
+     *
+     * What is left once the pixels are taken out is the same test
+     * {@link resolveRegionBox} applies before it maps anything: a region bounding
+     * *neither* axis is not a call-out, so `{}` counts as none exactly as `null`
+     * does.
+     */
+    private hasCallout;
+    private regionBox;
+    constructor(props?: NodeConfig<LineChart, LineChartProps>);
+    /**
+     * Prime every part at its pre-entrance state — axis markers shifted and
+     * transparent, lines untraced, legend dropped and transparent.
+     *
+     * Called by {@link enter} before its first frame so nothing flashes ahead of
+     * its beat. Idempotent, and public so a scene can hide a chart ahead of time
+     * without starting the entrance.
+     */
+    arm(): void;
+    /**
+     * Animate the whole chart in: the two axes stagger their markers in (vertical
+     * bottom-to-top, horizontal left-to-right), the series lines trace
+     * left-to-right, and the legend fades up last.
+     *
+     * `duration` is the **whole** entrance. The phases below are shares of it, not
+     * multiples — a command that declares 1.4 seconds has to take 1.4 seconds,
+     * because that is the slot the timeline lays out for it, the length its
+     * parallel siblings are timed against, and its contribution to the scene's own
+     * duration. (The component this was ported from scaled every phase *off* the
+     * line trace and let the total fall where it may, which came out around 3×.)
+     *
+     * A chart authored with a `region` lands its call-out last, over lines that
+     * have already traced — the same order a scene would get by calling
+     * {@link spotlightRegion} right after this — and that beat comes out of the
+     * same budget.
+     */
+    enter(args: CommandArgs<Record<string, never>> & {
+        duration: number;
+    }): Seekable;
+    /**
+     * Spotlight a rectangular slice of the plot given in **data units**: dashed
+     * rules draw themselves onto each bounded edge while every series fades
+     * outside the box and stays full inside it.
+     *
+     * Either axis alone is a band — `{ x: [80, 100] }` picks out the last fifth
+     * across all series, `{ y: [8, 10] }` a value band across the whole width —
+     * and both together a box. The unbounded axis spans the plot and draws no
+     * rule, since there's no data bound there to mark.
+     *
+     * Calling it while another region is already up cross-fades: the old call-out
+     * retracts, then the new one draws in, each over half `duration`.
+     *
+     * Both the call-out's shape and its draw-on are plain signals — `region` and
+     * {@link regionReveal} — so the whole thing is a function of `t`, including
+     * the swap: which region is up is a step at the halfway point rather than an
+     * effect that has to have happened.
+     */
+    spotlightRegion(args: CommandArgs<{
+        region: PlotRegion;
+    }> & {
+        duration?: number;
+    }): Command<RegionState>;
+    /**
+     * Drop the region call-out — the rules retract, the wash fades, and every
+     * series comes back to full across its whole length. A no-op when nothing is
+     * spotlit.
+     */
+    clearRegion(args?: CommandArgs<Record<string, never>> & {
+        duration?: number;
+    }): Command<RegionState>;
+    /**
+     * The domain to come back to, captured the first time {@link zoomTo} runs so a
+     * later {@link resetZoom} restores the chart as authored — including ticks
+     * that were auto-derived rather than given, which the props alone don't
+     * record. Cleared by {@link resetZoom}, so a second zoom captures wherever the
+     * chart genuinely rests then.
+     */
+    private home;
+    /**
+     * The `region` a document handed a command, or `{}`. A command is added
+     * before its arguments are filled in, so an unstated region is ordinary input
+     * rather than a malformed one.
+     */
+    private static regionArg;
+    /** A range read as a span, whichever way round the author wrote it. */
+    private static span;
+    /**
+     * Rescale an axis to `range`, keeping the tick *count* it already has — the
+     * axis tween interpolates ticks pairwise by index, so a constant count lets
+     * each marker slide from its old value to its new one instead of the row
+     * popping.
+     */
+    private static rescale;
+    /**
+     * Zoom the plot to a slice of itself, given in **data units**: the named axes
+     * rescale so that slice fills the plot, the grid and both marker rows
+     * following the new scale, and every series re-tracing itself into the new
+     * frame. All of it tweens, so the move reads as a camera push rather than a
+     * cut.
+     *
+     * An **omitted axis is left as it is** rather than being fitted to what's
+     * visible — so a zoom is exactly what was asked for, and two calls compose
+     * predictably. A spotlit region, if one is up, follows the zoom: it resolves
+     * against the same live scales, so its rules stay on their data bounds.
+     */
+    zoomTo(args: CommandArgs<{
+        region: PlotRegion;
+    }> & {
+        duration?: number;
+    }): Seekable;
+    /**
+     * Pull back out to the domain the chart was authored with — the mirror of
+     * {@link zoomTo}, and a no-op if it was never zoomed.
+     */
+    resetZoom(args?: CommandArgs<Record<string, never>> & {
+        duration?: number;
+    }): Seekable;
+    /**
+     * Show series `index`: **trace** its line in left-to-right — the same draw as
+     * {@link enter}, not an opacity fade — in lockstep with its legend entry
+     * growing in.
+     *
+     * `enabled` is set as part of the command's own value rather than before it,
+     * so the line is drawable for every `t` the trace covers and undrawn outside
+     * it — which is what makes arriving here backwards show the same thing as
+     * arriving forwards.
+     */
+    showSeries(args: CommandArgs<{
+        seriesIndex: number;
+    }> & {
+        duration?: number;
+    }): Seekable;
+    /**
+     * Hide series `index`: **retrace** its line back out (`progress` 1 → 0) as its
+     * legend entry shrinks away — the mirror of {@link showSeries}.
+     */
+    hideSeries(args: CommandArgs<{
+        seriesIndex: number;
+    }> & {
+        duration?: number;
+    }): Seekable;
+    /**
+     * Fade out all other series — each line **and its legend entry** — to focus
+     * attention on `index`, which comes back to full. The legend dims in place
+     * (opacity only), so no entry moves and the row doesn't reflow.
+     */
+    spotlightSeries(args: CommandArgs<{
+        seriesIndex: number;
+    }> & {
+        duration?: number;
+    }): Seekable;
+}
+export {};
+//# sourceMappingURL=line-chart.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"line-chart.d.ts","sourceRoot":"","sources":["../../src/line-chart/line-chart.ts"],"names":[],"mappings":"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"}