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

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

@@ -0,0 +1,171 @@
+/**
+ * Types and pure helpers specific to the {@link LineChart} family: the traced
+ * polylines, the spotlit region they dim outside of, and the theme those two
+ * add to the shared chart vocabulary.
+ *
+ * Everything a bar or a pie chart would want too — what a series is, how an axis
+ * is scaled and formatted, the theme leaf resolvers, the legend and plot-panel
+ * branches — lives in `../kit/shared.ts` and is imported here. What's
+ * left below is what only a line chart has: points sorted along an x column,
+ * a region clipped out of a polyline, and the `region` branch of the theme.
+ *
+ * Kept renderer-agnostic (no `Node` imports) so every part shares one
+ * scale/format/palette/theme vocabulary, and so a host's own inspector
+ * mapping can build a partial {@link ChartTheme} without
+ * pulling the components in.
+ */
+import { type DataRecord, type Fill, type Stroke } from "@motionscript/sdk";
+import { type AxisConfig, type ChartSeries, type LegendConfig, type LegendTheme, type PlotAreaConfig, type Range } from "../kit/shared.js";
+import type { XScale } from "./x-scale.js";
+/**
+ * One series in a {@link LineChart}: a polyline traced through the values in one
+ * column of the chart's `data`, drawn in `fill` (or the theme's `seriesStyles`
+ * palette when omitted) and captioned by `label` in the legend.
+ *
+ * The family-wide {@link ChartSeries} under a name that says what it draws here;
+ * the chart's own `xField` prop names the column carrying the shared x values,
+ * so every series is read off the same rows — one row per sample, one column per
+ * series.
+ */
+export type LineSeries = ChartSeries;
+/**
+ * A rectangular slice of the plot, in **data units** — the author-facing input
+ * to {@link LineChart.spotlightRegion} / {@link LineChart.zoomTo}.
+ *
+ * Either axis may be omitted, and that's the point: `{ x: [60, 100] }` is a
+ * vertical band spanning the full height, `{ y: [8, 10] }` a horizontal band
+ * spanning the full width, and both together a box. A reversed range is read
+ * the same as the forward one — a region is a span, not a direction.
+ */
+export interface PlotRegion {
+    /** Horizontal span in x-axis data units. Omit to span the full plot width. */
+    x?: Range;
+    /** Vertical span in y-axis data units. Omit to span the full plot height. */
+    y?: Range;
+}
+/**
+ * A {@link PlotRegion} resolved into the plot's **centred pixel space** (origin
+ * at the plot centre, y-up) — the same local frame the series points live in,
+ * so a line can be clipped against it directly.
+ *
+ * `xBounded`/`yBounded` carry which axes the author actually constrained: an
+ * unbounded axis has its edges pinned to the plot's own and draws no rule.
+ */
+export interface RegionBox {
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+    /** The author gave an x range — the left/right edges are real data bounds. */
+    xBounded: boolean;
+    /** The author gave a y range — the bottom/top edges are real data bounds. */
+    yBounded: boolean;
+}
+/** The empty box, used as the "no region" resting value. */
+export declare const EMPTY_REGION_BOX: RegionBox;
+/** Is `box` a real, non-degenerate region — i.e. is there anything to spotlight? */
+export declare function hasRegion(box: RegionBox): boolean;
+/**
+ * Resolve a {@link PlotRegion} against the plot's pixel box and the chart's
+ * scales. `plot` is the plot rectangle in centred pixel space, and
+ * `xScale`/`yScale` the data ranges those edges span.
+ *
+ * An omitted axis takes the plot's own edges, so the region spans it. A given
+ * axis is clamped to the plot, so a range running off the scale still produces
+ * a box inside the panel.
+ */
+export declare function resolveRegionBox(region: PlotRegion | null | undefined, plot: {
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+}, xScale: Range, yScale: Range): RegionBox;
+/** A bare `{x, y}` — declared locally so this module stays free of node imports. */
+interface Vector2Like {
+    x: number;
+    y: number;
+}
+/**
+ * The parts of `points` that fall **inside** `box`, as a list of contiguous
+ * sub-polylines — the geometry behind the region spotlight: a series is drawn
+ * dimmed in full, then these runs are re-drawn over it at full strength.
+ *
+ * Segments are clipped against the box rather than filtered by endpoint, so a
+ * line entering the region mid-segment is cut exactly on the boundary.
+ */
+export declare function clipPolylineToBox(points: Vector2Like[], box: RegionBox): Vector2Like[][];
+/**
+ * How a spotlit {@link PlotRegion} is drawn — the dashed rules on its bounded
+ * edges, the wash filling it, and how far the series fade outside it.
+ */
+export interface RegionConfig {
+    /** The dashed rule marking each bounded edge. */
+    stroke: Stroke;
+    /** Wash filling the region, drawn under the series lines. */
+    fill: Fill;
+    /** Opacity the stretch of every series *outside* the region fades to. */
+    dimOpacity: number;
+}
+/** A {@link LineChart}'s full, resolved visual theme. */
+export interface ChartConfig {
+    /**
+     * Default per-series line stroke, cycled by series index (`i % length`). A
+     * series' own `fill`, when set, overrides just the colour.
+     */
+    seriesStyles: Stroke[];
+    xAxis: AxisConfig;
+    yAxis: AxisConfig;
+    /** The plot panel: border, fill, and drop shadow. */
+    plotArea: PlotAreaConfig;
+    legend: LegendConfig;
+    /** The spotlit-region annotation — see {@link RegionConfig}. */
+    region: RegionConfig;
+}
+/**
+ * Author-facing partial theme, passed as {@link LineChart}'s `theme` prop —
+ * every branch optional and deep-merged onto {@link DEFAULT_CHART_THEME}.
+ */
+export type ChartTheme = {
+    seriesStyles?: Stroke[];
+    xAxis?: Partial<AxisConfig>;
+    yAxis?: Partial<AxisConfig>;
+    plotArea?: Partial<PlotAreaConfig>;
+    legend?: LegendTheme;
+    region?: Partial<RegionConfig>;
+};
+/** The chart's out-of-the-box look. */
+export declare const DEFAULT_CHART_THEME: ChartConfig;
+/**
+ * {@link LineChart}'s `theme` entry's resolve: merges the author's partial
+ * {@link ChartTheme} onto `previous` (falling back to
+ * {@link DEFAULT_CHART_THEME} on first resolution), fully resolving every leaf.
+ */
+export declare function resolveChartTheme(theme: ChartTheme | undefined, previous?: ChartConfig): ChartConfig;
+/** {@link LineChart}'s `theme` entry's lerp — leaf by leaf. */
+export declare function lerpChartTheme(from: ChartConfig, to: ChartConfig, t: number): ChartConfig;
+/**
+ * Resolve one series' `[x, y]` points out of the chart's rows: each row's
+ * position on the {@link XScale} paired with its own `field` column, sorted
+ * along x so the polyline traces left-to-right whatever order the rows arrived
+ * in.
+ *
+ * A row missing its y column contributes a 0 rather than a gap — these charts
+ * draw continuous lines, so dropping the point would silently bridge the hole.
+ *
+ * Takes the resolved scale rather than the column *name*, because what a row's x
+ * is depends on what kind of column it came out of: a number, an instant, or a
+ * place in the file. See `x-scale.ts`.
+ */
+export declare function seriesPoints(data: DataRecord[], x: XScale, series: LineSeries): [x: number, y: number][];
+/** Min/max across every series' column, the fallback when unset. */
+export declare function yExtent(data: DataRecord[], series: LineSeries[]): Range;
+/**
+ * Effective vertical scale: the explicit `range`, else the data's y extent
+ * nudged out to tidy step bounds so markers read as round numbers.
+ *
+ * `divisions` is how many segments the auto-range is stepped into (one fewer
+ * than a marker count) — it only shapes the tidy step when `range` is omitted.
+ */
+export declare function resolveYScale(data: DataRecord[], series: LineSeries[], range: Range | undefined, divisions: number): Range;
+export {};
+//# sourceMappingURL=shared.d.ts.map

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

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

package/dist/line-chart/shared.js

@@ -0,0 +1,285 @@
+/**
+ * Types and pure helpers specific to the {@link LineChart} family: the traced
+ * polylines, the spotlit region they dim outside of, and the theme those two
+ * add to the shared chart vocabulary.
+ *
+ * Everything a bar or a pie chart would want too — what a series is, how an axis
+ * is scaled and formatted, the theme leaf resolvers, the legend and plot-panel
+ * branches — lives in `../kit/shared.ts` and is imported here. What's
+ * left below is what only a line chart has: points sorted along an x column,
+ * a region clipped out of a polyline, and the `region` branch of the theme.
+ *
+ * Kept renderer-agnostic (no `Node` imports) so every part shares one
+ * scale/format/palette/theme vocabulary, and so a host's own inspector
+ * mapping can build a partial {@link ChartTheme} without
+ * pulling the components in.
+ */
+import { Fills, fillOps, lerpNumber, strokeOps, } from "@motionscript/sdk";
+import { CHART_PALETTE, DEFAULT_LEGEND, DEFAULT_PLOT_AREA, DEFAULT_SERIES_STROKES, DEFAULT_X_AXIS, DEFAULT_Y_AXIS, SPOTLIGHT_DIM, lerpAxisConfig, lerpLegendConfig, lerpPlotArea, lerpSeriesStrokes, niceStep, num, resolveAxisConfig, resolveLegendConfig, resolvePlotArea, resolveSeriesStrokes, } from "../kit/shared.js";
+/** The empty box, used as the "no region" resting value. */
+export const EMPTY_REGION_BOX = {
+    left: 0,
+    right: 0,
+    bottom: 0,
+    top: 0,
+    xBounded: false,
+    yBounded: false,
+};
+/** Is `box` a real, non-degenerate region — i.e. is there anything to spotlight? */
+export function hasRegion(box) {
+    return box.right > box.left && box.top > box.bottom;
+}
+/**
+ * Resolve a {@link PlotRegion} against the plot's pixel box and the chart's
+ * scales. `plot` is the plot rectangle in centred pixel space, and
+ * `xScale`/`yScale` the data ranges those edges span.
+ *
+ * An omitted axis takes the plot's own edges, so the region spans it. A given
+ * axis is clamped to the plot, so a range running off the scale still produces
+ * a box inside the panel.
+ */
+export function resolveRegionBox(region, plot, xScale, yScale) {
+    if (!region || (region.x === undefined && region.y === undefined)) {
+        return EMPTY_REGION_BOX;
+    }
+    const span = (range, [min, max], lo, hi) => {
+        if (range === undefined || max <= min)
+            return [lo, hi, false];
+        const a = Math.min(range[0], range[1]);
+        const b = Math.max(range[0], range[1]);
+        const toPx = (v) => lo + ((v - min) / (max - min)) * (hi - lo);
+        return [
+            Math.max(lo, Math.min(hi, toPx(a))),
+            Math.max(lo, Math.min(hi, toPx(b))),
+            true,
+        ];
+    };
+    const [left, right, xBounded] = span(region.x, xScale, plot.left, plot.right);
+    const [bottom, top, yBounded] = span(region.y, yScale, plot.bottom, plot.top);
+    return { left, right, bottom, top, xBounded, yBounded };
+}
+/**
+ * The parts of `points` that fall **inside** `box`, as a list of contiguous
+ * sub-polylines — the geometry behind the region spotlight: a series is drawn
+ * dimmed in full, then these runs are re-drawn over it at full strength.
+ *
+ * Segments are clipped against the box rather than filtered by endpoint, so a
+ * line entering the region mid-segment is cut exactly on the boundary.
+ */
+export function clipPolylineToBox(points, box) {
+    if (points.length < 2 || !hasRegion(box))
+        return [];
+    const runs = [];
+    let run = [];
+    for (let i = 1; i < points.length; i++) {
+        const seg = clipSegment(points[i - 1], points[i], box);
+        if (!seg) {
+            // Segment misses the box entirely — close whatever run was open.
+            if (run.length >= 2)
+                runs.push(run);
+            run = [];
+            continue;
+        }
+        const [a, b] = seg;
+        // Continue the open run when this clipped segment starts where the last one
+        // ended; otherwise the line left the box and came back, which is a new run.
+        if (run.length > 0 && samePoint(run[run.length - 1], a))
+            run.push(b);
+        else {
+            if (run.length >= 2)
+                runs.push(run);
+            run = [a, b];
+        }
+    }
+    if (run.length >= 2)
+        runs.push(run);
+    return runs;
+}
+/** Points within half a pixel are the same point, for run-joining purposes. */
+function samePoint(a, b) {
+    return Math.abs(a.x - b.x) < 0.5 && Math.abs(a.y - b.y) < 0.5;
+}
+/**
+ * Liang–Barsky clip of one segment against the axis-aligned `box`. Returns the
+ * surviving `[start, end]`, or `null` when the segment lies wholly outside.
+ */
+function clipSegment(a, b, box) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    let t0 = 0;
+    let t1 = 1;
+    // Each edge as (p, q): the segment survives where p·t <= q.
+    const edges = [
+        [-dx, a.x - box.left],
+        [dx, box.right - a.x],
+        [-dy, a.y - box.bottom],
+        [dy, box.top - a.y],
+    ];
+    for (const [p, q] of edges) {
+        if (p === 0) {
+            // Parallel to this edge: outside it means the whole segment is out.
+            if (q < 0)
+                return null;
+            continue;
+        }
+        const r = q / p;
+        if (p < 0) {
+            if (r > t1)
+                return null;
+            if (r > t0)
+                t0 = r;
+        }
+        else {
+            if (r < t0)
+                return null;
+            if (r < t1)
+                t1 = r;
+        }
+    }
+    return [
+        { x: a.x + t0 * dx, y: a.y + t0 * dy },
+        { x: a.x + t1 * dx, y: a.y + t1 * dy },
+    ];
+}
+/**
+ * The legend of a line chart: the shared one, with a small rounded-square
+ * swatch in place of the wide chip. A bar's or a wedge's swatch stands in for
+ * an area of paint and is drawn like one; a line's stands in for a colour, and
+ * a square reads as the sample it is.
+ */
+const LINE_CHART_LEGEND = {
+    ...DEFAULT_LEGEND,
+    markerStyle: {
+        ...DEFAULT_LEGEND.markerStyle,
+        width: 20,
+        height: 20,
+        borderRadius: 6,
+    },
+};
+/** The chart's out-of-the-box look. */
+export const DEFAULT_CHART_THEME = {
+    seriesStyles: DEFAULT_SERIES_STROKES,
+    xAxis: DEFAULT_X_AXIS,
+    yAxis: DEFAULT_Y_AXIS,
+    plotArea: DEFAULT_PLOT_AREA,
+    legend: LINE_CHART_LEGEND,
+    region: {
+        // Brighter than the grid and dashed, so the boundary reads as a call-out
+        // rather than another axis line; `butt` caps keep the dash lengths exact.
+        stroke: {
+            weight: 3,
+            fill: CHART_PALETTE.regionColor,
+            dash: [14, 12],
+            cap: "butt",
+        },
+        // A wash barely above the panel — enough to tint the band, not enough to
+        // mute the series drawn over it.
+        fill: Fills.color(CHART_PALETTE.regionColor, { opacity: 0.08 }),
+        dimOpacity: SPOTLIGHT_DIM,
+    },
+};
+function resolveRegionConfig(region, previous) {
+    return {
+        stroke: strokeOps.resolve(region?.stroke ?? previous.stroke),
+        fill: fillOps.resolve(region?.fill ?? previous.fill),
+        dimOpacity: region?.dimOpacity ?? previous.dimOpacity,
+    };
+}
+function lerpRegionConfig(from, to, t) {
+    return {
+        stroke: strokeOps.lerp(from.stroke, to.stroke, t),
+        fill: fillOps.lerp(from.fill, to.fill, t),
+        dimOpacity: lerpNumber(from.dimOpacity, to.dimOpacity, t),
+    };
+}
+/**
+ * {@link LineChart}'s `theme` entry's resolve: merges the author's partial
+ * {@link ChartTheme} onto `previous` (falling back to
+ * {@link DEFAULT_CHART_THEME} on first resolution), fully resolving every leaf.
+ */
+export function resolveChartTheme(theme, previous) {
+    const base = previous ?? DEFAULT_CHART_THEME;
+    return {
+        seriesStyles: resolveSeriesStrokes(theme?.seriesStyles, base.seriesStyles),
+        xAxis: resolveAxisConfig(theme?.xAxis, base.xAxis),
+        yAxis: resolveAxisConfig(theme?.yAxis, base.yAxis),
+        plotArea: resolvePlotArea(theme?.plotArea, base.plotArea),
+        legend: resolveLegendConfig(theme?.legend, base.legend),
+        region: resolveRegionConfig(theme?.region, base.region),
+    };
+}
+/** {@link LineChart}'s `theme` entry's lerp — leaf by leaf. */
+export function lerpChartTheme(from, to, t) {
+    return {
+        seriesStyles: lerpSeriesStrokes(from.seriesStyles, to.seriesStyles, t),
+        xAxis: lerpAxisConfig(from.xAxis, to.xAxis, t),
+        yAxis: lerpAxisConfig(from.yAxis, to.yAxis, t),
+        plotArea: lerpPlotArea(from.plotArea, to.plotArea, t),
+        legend: lerpLegendConfig(from.legend, to.legend, t),
+        region: lerpRegionConfig(from.region, to.region, t),
+    };
+}
+// ---- Scales --------------------------------------------------------------
+/**
+ * Resolve one series' `[x, y]` points out of the chart's rows: each row's
+ * position on the {@link XScale} paired with its own `field` column, sorted
+ * along x so the polyline traces left-to-right whatever order the rows arrived
+ * in.
+ *
+ * A row missing its y column contributes a 0 rather than a gap — these charts
+ * draw continuous lines, so dropping the point would silently bridge the hole.
+ *
+ * Takes the resolved scale rather than the column *name*, because what a row's x
+ * is depends on what kind of column it came out of: a number, an instant, or a
+ * place in the file. See `x-scale.ts`.
+ */
+export function seriesPoints(data, x, series) {
+    return data
+        .map((row, i) => [x.at(i), num(row, series.field)])
+        .sort((a, b) => a[0] - b[0]);
+}
+/** Min/max across every series' column, the fallback when unset. */
+export function yExtent(data, series) {
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const row of data)
+        for (const s of series) {
+            const v = num(row, s.field);
+            if (v < lo)
+                lo = v;
+            if (v > hi)
+                hi = v;
+        }
+    return lo <= hi ? [lo, hi] : [0, 1];
+}
+/**
+ * Effective vertical scale: the explicit `range`, else the data's y extent
+ * nudged out to tidy step bounds so markers read as round numbers.
+ *
+ * `divisions` is how many segments the auto-range is stepped into (one fewer
+ * than a marker count) — it only shapes the tidy step when `range` is omitted.
+ */
+export function resolveYScale(data, series, range, divisions) {
+    if (range)
+        return range;
+    const [lo, hi] = yExtent(data, series);
+    const segments = Math.max(1, Math.round(divisions));
+    if (hi === lo)
+        return constantScale(lo, segments);
+    const step = niceStep((hi - lo) / segments);
+    return [Math.floor(lo / step) * step, Math.ceil(hi / step) * step];
+}
+/**
+ * The scale for data that never moves. A zero-width scale puts every tick on the
+ * same value and the line on the plot's floor, so it is widened to a few steps
+ * either side of the value (the step sized to its magnitude, so `5` gets
+ * `[3, 7]` and `5000` gets `[3000, 7000]`), or to `[0, 1]` for all zeros, as for
+ * no data at all.
+ */
+function constantScale(value, segments) {
+    if (value === 0)
+        return [0, 1];
+    const step = niceStep(Math.abs(value) / segments);
+    return [value - step, value + step];
+}
+//# sourceMappingURL=shared.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/line-chart/shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Types and pure helpers specific to the {@link LineChart} family: the traced\n * polylines, the spotlit region they dim outside of, and the theme those two\n * add to the shared chart vocabulary.\n *\n * Everything a bar or a pie chart would want too — what a series is, how an axis\n * is scaled and formatted, the theme leaf resolvers, the legend and plot-panel\n * branches — lives in `../kit/shared.ts` and is imported here. What's\n * left below is what only a line chart has: points sorted along an x column,\n * a region clipped out of a polyline, and the `region` branch of the theme.\n *\n * Kept renderer-agnostic (no `Node` imports) so every part shares one\n * scale/format/palette/theme vocabulary, and so a host's own inspector\n * mapping can build a partial {@link ChartTheme} without\n * pulling the components in.\n */\n\nimport {\n  Fills,\n  fillOps,\n  lerpNumber,\n  strokeOps,\n  type DataRecord,\n  type Fill,\n  type FillResolved,\n  type Stroke,\n  type StrokeResolved,\n} from \"@motionscript/sdk\"\n\nimport {\n  CHART_PALETTE,\n  DEFAULT_LEGEND,\n  DEFAULT_PLOT_AREA,\n  DEFAULT_SERIES_STROKES,\n  DEFAULT_X_AXIS,\n  DEFAULT_Y_AXIS,\n  SPOTLIGHT_DIM,\n  lerpAxisConfig,\n  lerpLegendConfig,\n  lerpPlotArea,\n  lerpSeriesStrokes,\n  niceStep,\n  num,\n  resolveAxisConfig,\n  resolveLegendConfig,\n  resolvePlotArea,\n  resolveSeriesStrokes,\n  type AxisConfig,\n  type ChartSeries,\n  type LegendConfig,\n  type LegendTheme,\n  type PlotAreaConfig,\n  type Range,\n} from \"../kit/shared\"\nimport type { XScale } from \"./x-scale\"\n\n/**\n * One series in a {@link LineChart}: a polyline traced through the values in one\n * column of the chart's `data`, drawn in `fill` (or the theme's `seriesStyles`\n * palette when omitted) and captioned by `label` in the legend.\n *\n * The family-wide {@link ChartSeries} under a name that says what it draws here;\n * the chart's own `xField` prop names the column carrying the shared x values,\n * so every series is read off the same rows — one row per sample, one column per\n * series.\n */\nexport type LineSeries = ChartSeries\n\n// ---- Plot regions -------------------------------------------------------\n\n/**\n * A rectangular slice of the plot, in **data units** — the author-facing input\n * to {@link LineChart.spotlightRegion} / {@link LineChart.zoomTo}.\n *\n * Either axis may be omitted, and that's the point: `{ x: [60, 100] }` is a\n * vertical band spanning the full height, `{ y: [8, 10] }` a horizontal band\n * spanning the full width, and both together a box. A reversed range is read\n * the same as the forward one — a region is a span, not a direction.\n */\nexport interface PlotRegion {\n  /** Horizontal span in x-axis data units. Omit to span the full plot width. */\n  x?: Range\n  /** Vertical span in y-axis data units. Omit to span the full plot height. */\n  y?: Range\n}\n\n/**\n * A {@link PlotRegion} resolved into the plot's **centred pixel space** (origin\n * at the plot centre, y-up) — the same local frame the series points live in,\n * so a line can be clipped against it directly.\n *\n * `xBounded`/`yBounded` carry which axes the author actually constrained: an\n * unbounded axis has its edges pinned to the plot's own and draws no rule.\n */\nexport interface RegionBox {\n  left: number\n  right: number\n  bottom: number\n  top: number\n  /** The author gave an x range — the left/right edges are real data bounds. */\n  xBounded: boolean\n  /** The author gave a y range — the bottom/top edges are real data bounds. */\n  yBounded: boolean\n}\n\n/** The empty box, used as the \"no region\" resting value. */\nexport const EMPTY_REGION_BOX: RegionBox = {\n  left: 0,\n  right: 0,\n  bottom: 0,\n  top: 0,\n  xBounded: false,\n  yBounded: false,\n}\n\n/** Is `box` a real, non-degenerate region — i.e. is there anything to spotlight? */\nexport function hasRegion(box: RegionBox): boolean {\n  return box.right > box.left && box.top > box.bottom\n}\n\n/**\n * Resolve a {@link PlotRegion} against the plot's pixel box and the chart's\n * scales. `plot` is the plot rectangle in centred pixel space, and\n * `xScale`/`yScale` the data ranges those edges span.\n *\n * An omitted axis takes the plot's own edges, so the region spans it. A given\n * axis is clamped to the plot, so a range running off the scale still produces\n * a box inside the panel.\n */\nexport function resolveRegionBox(\n  region: PlotRegion | null | undefined,\n  plot: { left: number; right: number; bottom: number; top: number },\n  xScale: Range,\n  yScale: Range\n): RegionBox {\n  if (!region || (region.x === undefined && region.y === undefined)) {\n    return EMPTY_REGION_BOX\n  }\n\n  const span = (\n    range: Range | undefined,\n    [min, max]: Range,\n    lo: number,\n    hi: number\n  ): [number, number, boolean] => {\n    if (range === undefined || max <= min) return [lo, hi, false]\n    const a = Math.min(range[0], range[1])\n    const b = Math.max(range[0], range[1])\n    const toPx = (v: number) => lo + ((v - min) / (max - min)) * (hi - lo)\n    return [\n      Math.max(lo, Math.min(hi, toPx(a))),\n      Math.max(lo, Math.min(hi, toPx(b))),\n      true,\n    ]\n  }\n\n  const [left, right, xBounded] = span(region.x, xScale, plot.left, plot.right)\n  const [bottom, top, yBounded] = span(region.y, yScale, plot.bottom, plot.top)\n  return { left, right, bottom, top, xBounded, yBounded }\n}\n\n/** A bare `{x, y}` — declared locally so this module stays free of node imports. */\ninterface Vector2Like {\n  x: number\n  y: number\n}\n\n/**\n * The parts of `points` that fall **inside** `box`, as a list of contiguous\n * sub-polylines — the geometry behind the region spotlight: a series is drawn\n * dimmed in full, then these runs are re-drawn over it at full strength.\n *\n * Segments are clipped against the box rather than filtered by endpoint, so a\n * line entering the region mid-segment is cut exactly on the boundary.\n */\nexport function clipPolylineToBox(\n  points: Vector2Like[],\n  box: RegionBox\n): Vector2Like[][] {\n  if (points.length < 2 || !hasRegion(box)) return []\n\n  const runs: Vector2Like[][] = []\n  let run: Vector2Like[] = []\n\n  for (let i = 1; i < points.length; i++) {\n    const seg = clipSegment(points[i - 1], points[i], box)\n    if (!seg) {\n      // Segment misses the box entirely — close whatever run was open.\n      if (run.length >= 2) runs.push(run)\n      run = []\n      continue\n    }\n    const [a, b] = seg\n    // Continue the open run when this clipped segment starts where the last one\n    // ended; otherwise the line left the box and came back, which is a new run.\n    if (run.length > 0 && samePoint(run[run.length - 1], a)) run.push(b)\n    else {\n      if (run.length >= 2) runs.push(run)\n      run = [a, b]\n    }\n  }\n  if (run.length >= 2) runs.push(run)\n  return runs\n}\n\n/** Points within half a pixel are the same point, for run-joining purposes. */\nfunction samePoint(a: Vector2Like, b: Vector2Like): boolean {\n  return Math.abs(a.x - b.x) < 0.5 && Math.abs(a.y - b.y) < 0.5\n}\n\n/**\n * Liang–Barsky clip of one segment against the axis-aligned `box`. Returns the\n * surviving `[start, end]`, or `null` when the segment lies wholly outside.\n */\nfunction clipSegment(\n  a: Vector2Like,\n  b: Vector2Like,\n  box: RegionBox\n): [Vector2Like, Vector2Like] | null {\n  const dx = b.x - a.x\n  const dy = b.y - a.y\n  let t0 = 0\n  let t1 = 1\n\n  // Each edge as (p, q): the segment survives where p·t <= q.\n  const edges: [number, number][] = [\n    [-dx, a.x - box.left],\n    [dx, box.right - a.x],\n    [-dy, a.y - box.bottom],\n    [dy, box.top - a.y],\n  ]\n  for (const [p, q] of edges) {\n    if (p === 0) {\n      // Parallel to this edge: outside it means the whole segment is out.\n      if (q < 0) return null\n      continue\n    }\n    const r = q / p\n    if (p < 0) {\n      if (r > t1) return null\n      if (r > t0) t0 = r\n    } else {\n      if (r < t0) return null\n      if (r < t1) t1 = r\n    }\n  }\n  return [\n    { x: a.x + t0 * dx, y: a.y + t0 * dy },\n    { x: a.x + t1 * dx, y: a.y + t1 * dy },\n  ]\n}\n\n// ---- Theme ---------------------------------------------------------------\n\n/**\n * How a spotlit {@link PlotRegion} is drawn — the dashed rules on its bounded\n * edges, the wash filling it, and how far the series fade outside it.\n */\nexport interface RegionConfig {\n  /** The dashed rule marking each bounded edge. */\n  stroke: Stroke\n  /** Wash filling the region, drawn under the series lines. */\n  fill: Fill\n  /** Opacity the stretch of every series *outside* the region fades to. */\n  dimOpacity: number\n}\n\n/** A {@link LineChart}'s full, resolved visual theme. */\nexport interface ChartConfig {\n  /**\n   * Default per-series line stroke, cycled by series index (`i % length`). A\n   * series' own `fill`, when set, overrides just the colour.\n   */\n  seriesStyles: Stroke[]\n  xAxis: AxisConfig\n  yAxis: AxisConfig\n  /** The plot panel: border, fill, and drop shadow. */\n  plotArea: PlotAreaConfig\n  legend: LegendConfig\n  /** The spotlit-region annotation — see {@link RegionConfig}. */\n  region: RegionConfig\n}\n\n/**\n * Author-facing partial theme, passed as {@link LineChart}'s `theme` prop —\n * every branch optional and deep-merged onto {@link DEFAULT_CHART_THEME}.\n */\nexport type ChartTheme = {\n  seriesStyles?: Stroke[]\n  xAxis?: Partial<AxisConfig>\n  yAxis?: Partial<AxisConfig>\n  plotArea?: Partial<PlotAreaConfig>\n  legend?: LegendTheme\n  region?: Partial<RegionConfig>\n}\n\n/**\n * The legend of a line chart: the shared one, with a small rounded-square\n * swatch in place of the wide chip. A bar's or a wedge's swatch stands in for\n * an area of paint and is drawn like one; a line's stands in for a colour, and\n * a square reads as the sample it is.\n */\nconst LINE_CHART_LEGEND: LegendConfig = {\n  ...DEFAULT_LEGEND,\n  markerStyle: {\n    ...DEFAULT_LEGEND.markerStyle,\n    width: 20,\n    height: 20,\n    borderRadius: 6,\n  },\n}\n\n/** The chart's out-of-the-box look. */\nexport const DEFAULT_CHART_THEME: ChartConfig = {\n  seriesStyles: DEFAULT_SERIES_STROKES,\n  xAxis: DEFAULT_X_AXIS,\n  yAxis: DEFAULT_Y_AXIS,\n  plotArea: DEFAULT_PLOT_AREA,\n  legend: LINE_CHART_LEGEND,\n  region: {\n    // Brighter than the grid and dashed, so the boundary reads as a call-out\n    // rather than another axis line; `butt` caps keep the dash lengths exact.\n    stroke: {\n      weight: 3,\n      fill: CHART_PALETTE.regionColor,\n      dash: [14, 12],\n      cap: \"butt\",\n    },\n    // A wash barely above the panel — enough to tint the band, not enough to\n    // mute the series drawn over it.\n    fill: Fills.color(CHART_PALETTE.regionColor, { opacity: 0.08 }),\n    dimOpacity: SPOTLIGHT_DIM,\n  },\n}\n\nfunction resolveRegionConfig(\n  region: Partial<RegionConfig> | undefined,\n  previous: RegionConfig\n): RegionConfig {\n  return {\n    stroke: strokeOps.resolve(region?.stroke ?? previous.stroke),\n    fill: fillOps.resolve(region?.fill ?? previous.fill),\n    dimOpacity: region?.dimOpacity ?? previous.dimOpacity,\n  }\n}\n\nfunction lerpRegionConfig(\n  from: RegionConfig,\n  to: RegionConfig,\n  t: number\n): RegionConfig {\n  return {\n    stroke: strokeOps.lerp(\n      from.stroke as StrokeResolved[],\n      to.stroke as StrokeResolved[],\n      t\n    ),\n    fill: fillOps.lerp(\n      from.fill as FillResolved[],\n      to.fill as FillResolved[],\n      t\n    ),\n    dimOpacity: lerpNumber(from.dimOpacity, to.dimOpacity, t),\n  }\n}\n\n/**\n * {@link LineChart}'s `theme` entry's resolve: merges the author's partial\n * {@link ChartTheme} onto `previous` (falling back to\n * {@link DEFAULT_CHART_THEME} on first resolution), fully resolving every leaf.\n */\nexport function resolveChartTheme(\n  theme: ChartTheme | undefined,\n  previous?: ChartConfig\n): ChartConfig {\n  const base = previous ?? DEFAULT_CHART_THEME\n  return {\n    seriesStyles: resolveSeriesStrokes(theme?.seriesStyles, base.seriesStyles),\n    xAxis: resolveAxisConfig(theme?.xAxis, base.xAxis),\n    yAxis: resolveAxisConfig(theme?.yAxis, base.yAxis),\n    plotArea: resolvePlotArea(theme?.plotArea, base.plotArea),\n    legend: resolveLegendConfig(theme?.legend, base.legend),\n    region: resolveRegionConfig(theme?.region, base.region),\n  }\n}\n\n/** {@link LineChart}'s `theme` entry's lerp — leaf by leaf. */\nexport function lerpChartTheme(\n  from: ChartConfig,\n  to: ChartConfig,\n  t: number\n): ChartConfig {\n  return {\n    seriesStyles: lerpSeriesStrokes(from.seriesStyles, to.seriesStyles, t),\n    xAxis: lerpAxisConfig(from.xAxis, to.xAxis, t),\n    yAxis: lerpAxisConfig(from.yAxis, to.yAxis, t),\n    plotArea: lerpPlotArea(from.plotArea, to.plotArea, t),\n    legend: lerpLegendConfig(from.legend, to.legend, t),\n    region: lerpRegionConfig(from.region, to.region, t),\n  }\n}\n\n// ---- Scales --------------------------------------------------------------\n\n/**\n * Resolve one series' `[x, y]` points out of the chart's rows: each row's\n * position on the {@link XScale} paired with its own `field` column, sorted\n * along x so the polyline traces left-to-right whatever order the rows arrived\n * in.\n *\n * A row missing its y column contributes a 0 rather than a gap — these charts\n * draw continuous lines, so dropping the point would silently bridge the hole.\n *\n * Takes the resolved scale rather than the column *name*, because what a row's x\n * is depends on what kind of column it came out of: a number, an instant, or a\n * place in the file. See `x-scale.ts`.\n */\nexport function seriesPoints(\n  data: DataRecord[],\n  x: XScale,\n  series: LineSeries\n): [x: number, y: number][] {\n  return data\n    .map((row, i): [number, number] => [x.at(i), num(row, series.field)])\n    .sort((a, b) => a[0] - b[0])\n}\n\n/** Min/max across every series' column, the fallback when unset. */\nexport function yExtent(data: DataRecord[], series: LineSeries[]): Range {\n  let lo = Infinity\n  let hi = -Infinity\n  for (const row of data)\n    for (const s of series) {\n      const v = num(row, s.field)\n      if (v < lo) lo = v\n      if (v > hi) hi = v\n    }\n  return lo <= hi ? [lo, hi] : [0, 1]\n}\n\n/**\n * Effective vertical scale: the explicit `range`, else the data's y extent\n * nudged out to tidy step bounds so markers read as round numbers.\n *\n * `divisions` is how many segments the auto-range is stepped into (one fewer\n * than a marker count) — it only shapes the tidy step when `range` is omitted.\n */\nexport function resolveYScale(\n  data: DataRecord[],\n  series: LineSeries[],\n  range: Range | undefined,\n  divisions: number\n): Range {\n  if (range) return range\n  const [lo, hi] = yExtent(data, series)\n  const segments = Math.max(1, Math.round(divisions))\n  if (hi === lo) return constantScale(lo, segments)\n  const step = niceStep((hi - lo) / segments)\n  return [Math.floor(lo / step) * step, Math.ceil(hi / step) * step]\n}\n\n/**\n * The scale for data that never moves. A zero-width scale puts every tick on the\n * same value and the line on the plot's floor, so it is widened to a few steps\n * either side of the value (the step sized to its magnitude, so `5` gets\n * `[3, 7]` and `5000` gets `[3000, 7000]`), or to `[0, 1]` for all zeros, as for\n * no data at all.\n */\nfunction constantScale(value: number, segments: number): Range {\n  if (value === 0) return [0, 1]\n  const step = niceStep(Math.abs(value) / segments)\n  return [value - step, value + step]\n}\n"]}

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

@@ -0,0 +1,77 @@
+/**
+ * What a line chart's x column *means* — the one question that has to be
+ * answered before a row can be given a position along the bottom of the plot.
+ *
+ * A y column is always a magnitude. An x column is one of three things, and
+ * which one is a property of the data rather than something the author states:
+ *
+ * - **numeric** — `0, 5, 10` — plot the number.
+ * - **time** — `Jan`, `2026-03`, `2026-W12`, `2026-03-14` — plot the instant,
+ *   so samples a month apart sit a month apart and a gap in the data reads as a
+ *   gap.
+ * - **ordinal** — anything else — plot the row's position, evenly spaced.
+ *
+ * Before this, every x column went through `num()`, which reads a non-numeric
+ * cell as `0`. A `Month` column of `Jan…Dec` therefore stacked all twelve
+ * points on one x and drew a vertical line — no error, no empty chart, just a
+ * wrong picture. That is the failure this module exists to remove: every column
+ * now plots as *something*, and the something is the reading a person would
+ * give it.
+ *
+ * The captions come back off the rows rather than out of a formatter. A tick on
+ * a time or ordinal scale is chosen *from the data* (see {@link XScale.ticks}),
+ * so the label it wants is the cell the author wrote — `Jan`, not `1970-01-01`,
+ * and `2026-W12`, not the Monday it resolves to. Only a tick that is not a
+ * sample — an author-set range, or a `zoomTo` mid-flight — needs formatting,
+ * and that is the one case {@link formatInstant} covers.
+ */
+import type { DataRecord } from "@motionscript/sdk";
+import { type Range } from "../kit/shared.js";
+/** How an x column's cells become positions along the axis. */
+export type XScaleKind = "numeric" | "time" | "ordinal";
+/**
+ * An x column resolved into positions, captions and ticks.
+ *
+ * The three kinds differ in all three answers, so they are three closures built
+ * once per (data, column) rather than a kind tag every caller switches on.
+ */
+export interface XScale {
+    kind: XScaleKind;
+    /** Position of row `index` along the axis, in this scale's own units. */
+    at(index: number): number;
+    /** `[min, max]` across the rows — the scale when no range is set. */
+    extent: Range;
+    /** The caption for a tick at `value`. */
+    label(value: number): string;
+    /** `divisions + 1` tick values spanning `range`, ends included. */
+    ticks(range: Range, divisions: number): number[];
+}
+/**
+ * One cell read as an instant, or `null` when it isn't one.
+ *
+ * Deliberately **not** `Date.parse`. That accepts `"5"`, `"Q3"` and a good deal
+ * else besides, differs between engines on anything non-ISO, and reads a bare
+ * `2026-03-14` as UTC but `2026/03/14` as local — three ways for a column to be
+ * silently misread as time. Every form below is matched explicitly, and an
+ * ambiguous all-numeric date (`03/04/2026` — March or April, depending on where
+ * the author lives) is deliberately not one of them.
+ */
+export declare function parseInstant(raw: unknown): number | null;
+/**
+ * An instant captioned at the coarsest granularity the axis's own span can tell
+ * apart — a decade of samples reads as years, a year of them as months.
+ *
+ * Only reached for a tick that is *not* one of the rows (an author-set range, a
+ * `zoomTo` part-way through). A tick that is a sample is captioned with the
+ * cell the author wrote; see the note at the top of this file.
+ */
+export declare function formatInstant(value: number, span: number): string;
+/**
+ * How `field` positions the rows: the number it holds, the instant it names, or
+ * failing both, the row's own place in the file.
+ *
+ * Kept per `data` array: a chart's bound props ask a dozen times a frame, and
+ * parsing every row's instant each time was most of a frame.
+ */
+export declare function resolveXScale(data: DataRecord[], field: string, pattern?: string): XScale;
+//# sourceMappingURL=x-scale.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"x-scale.d.ts","sourceRoot":"","sources":["../../src/line-chart/x-scale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD,OAAO,EAKL,KAAK,KAAK,EACX,MAAM,eAAe,CAAA;AAGtB,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,UAAU,CAAA;IAChB,yEAAyE;IACzE,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,qEAAqE;IACrE,MAAM,EAAE,KAAK,CAAA;IACb,yCAAyC;IACzC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IAC5B,mEAAmE;IACnE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CACjD;AAmDD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkDxD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQjE;AA0HD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAOR"}