@pond-ts/charts 0.31.0

package/dist/data.d.ts

@@ -0,0 +1,154 @@
+import type { SeriesSchema, TimeSeries, ValueSeries, ValueSeriesSchema } from 'pond-ts';
+/**
+ * A chart-ready columnar view of a series: parallel typed arrays for the time
+ * (x) and value (y) axes, plus the logical row count.
+ *
+ * Missing / non-finite values are `NaN` in `y` — the gap signal the draw layers
+ * break the line on (`Number.isFinite`, never `!= null`; see
+ * `docs/rfcs/charts.md` trap #2).
+ *
+ * Both arrays are length `length`. `x` is a zero-copy view of the key column's
+ * `begin` buffer (immutable by contract — do not mutate); `y` is the value
+ * column materialized to a `Float64Array`.
+ */
+export interface ChartSeries {
+    readonly x: Float64Array;
+    readonly y: Float64Array;
+    readonly length: number;
+}
+/**
+ * A chart-ready view of a band (variance envelope): the time axis plus a paired
+ * `lower`/`upper` edge per sample. A sample is part of the filled band only
+ * where **both** edges are finite; either edge `NaN` is a gap (the fill breaks,
+ * it does not bridge — same contract as {@link ChartSeries}).
+ */
+export interface BandSeries {
+    readonly x: Float64Array;
+    readonly lower: Float64Array;
+    readonly upper: Float64Array;
+    readonly length: number;
+}
+/**
+ * A chart-ready view of a box-and-whisker series ({@link BoxPlot}): the
+ * interval-keyed time axis (`x` = key `begin`, `xEnd` = key `end`, the box's
+ * horizontal span) plus the five quantile edges per key —
+ * `lower`/`q1`/`median`/`q3`/`upper`. The quantiles are pre-computed columns
+ * (a `rolling`/`aggregate` percentile pass upstream); the chart only reads them.
+ *
+ * A key is drawn only where **all five** quantiles are finite; any one `NaN` is
+ * a gap (the box draws nothing — same gap contract as {@link BandSeries}).
+ *
+ * `x` and `xEnd` are zero-copy views of the key column's `begin`/`end` buffers
+ * (immutable by contract — do not mutate). For a point-in-time key the column's
+ * `end` coincides with `begin`, so `xEnd === x` and the box collapses to a
+ * minimum-width mark via `barSpanPx`; an interval key gives the box real width.
+ */
+export interface BoxSeries {
+    readonly x: Float64Array;
+    readonly xEnd: Float64Array;
+    readonly lower: Float64Array;
+    readonly q1: Float64Array;
+    readonly median: Float64Array;
+    readonly q3: Float64Array;
+    readonly upper: Float64Array;
+    readonly length: number;
+}
+/**
+ * A chart-ready view of an interval-keyed series for bars: each mark spans
+ * `[begin[i], end[i]]` (the key's range) with height `y[i]`. Unlike
+ * {@link ChartSeries} (a single `x` point per row), a bar needs **both** key
+ * endpoints to know its x-span, so the time axis is split into `begin`/`end`.
+ *
+ * Missing / non-finite values are `NaN` in `y` — the gap signal {@link drawBars}
+ * skips (no bar), same `Number.isFinite` contract as {@link ChartSeries}. For a
+ * **point-keyed** series (`begin === end`), `barsFromTimeSeries` derives a span
+ * from neighbour spacing so the bars still have width (see there).
+ */
+export interface BarSeries {
+    readonly begin: Float64Array;
+    readonly end: Float64Array;
+    readonly y: Float64Array;
+    readonly length: number;
+}
+/** The five quantile column names a {@link boxFromTimeSeries} reads, in order. */
+export interface BoxColumns {
+    /** Lower whisker end (e.g. `p5` / `min`). */
+    readonly lower: string;
+    /** Box bottom — first quartile (e.g. `p25`). */
+    readonly q1: string;
+    /** Median line inside the box (e.g. `p50`). */
+    readonly median: string;
+    /** Box top — third quartile (e.g. `p75`). */
+    readonly q3: string;
+    /** Upper whisker end (e.g. `p95` / `max`). */
+    readonly upper: string;
+}
+/**
+ * Build a {@link ChartSeries} from a pond `TimeSeries` by reading its columnar
+ * buffers directly — no per-event materialization. `column` names a numeric
+ * value column; the key column supplies the time axis (`begin`, in ms).
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export declare function fromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, column: string): ChartSeries;
+/**
+ * Build a {@link ChartSeries} from a pond `ValueSeries` — the value-axis sibling
+ * of {@link fromTimeSeries}. The x axis is the series' monotonic value axis
+ * (`axisValues()`, e.g. cumulative distance) instead of time; `column` names a
+ * numeric value channel (HR, pace, …). The resulting `ChartSeries` is identical
+ * in shape — the chart draws it exactly as it draws a time series, only the x
+ * scale differs (a value scale rather than `scaleTime`).
+ *
+ * `x` is the axis key buffer zero-copy (immutable by contract — do not mutate);
+ * `y` is the channel materialized to a `Float64Array`, missing cells as `NaN`
+ * (the gap signal, same `Number.isFinite` contract as {@link fromTimeSeries}).
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export declare function fromValueSeries<VS extends ValueSeriesSchema>(series: ValueSeries<VS>, column: string): ChartSeries;
+/**
+ * Build a {@link BandSeries} from a pond `TimeSeries` — two numeric columns for
+ * the `lower`/`upper` edges sharing the series' time axis. The edge columns are
+ * typically `rollingByColumn` percentiles (e.g. p25/p75); a sample with either
+ * edge missing reads as a gap in the fill.
+ *
+ * @throws RangeError if `lower` or `upper` does not exist.
+ * @throws TypeError if `lower` or `upper` is not a numeric column.
+ */
+export declare function bandFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, lower: string, upper: string): BandSeries;
+/**
+ * Build a {@link BoxSeries} from a pond `TimeSeries` — five numeric quantile
+ * columns (`lower`/`q1`/`median`/`q3`/`upper`) sharing the series' interval time
+ * axis (`begin`/`end`, the box's horizontal span). The quantile columns are
+ * typically `rolling`/`aggregate` percentiles (e.g. p5/p25/p50/p75/p95); a key
+ * with any quantile missing reads as a gap (the box draws nothing).
+ *
+ * @throws RangeError if any quantile column does not exist.
+ * @throws TypeError if any quantile column is not a numeric column.
+ */
+export declare function boxFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, columns: BoxColumns): BoxSeries;
+/**
+ * Build a {@link BarSeries} from a pond `TimeSeries` — one bar per event, the
+ * key's `[begin, end]` as the x-span and `column` as the height.
+ *
+ * **Key-shape fallback (point-keyed series).** The primary form is
+ * interval / timeRange-keyed, where each key already carries a `[begin, end]`
+ * span. A **point-keyed** (`time`) series has `begin === end` (zero width), so
+ * this derives a span from neighbour spacing: each bar is centred on its
+ * timestamp and reaches **halfway to each neighbour** (a Voronoi cell on the
+ * time axis). The first/last bars mirror their single adjacent gap so the row's
+ * end bars match their interior width. A lone point (length 1) has no
+ * neighbour, so it keeps zero width and falls back to the renderer's `minWidth`.
+ *
+ * This makes a uniformly-sampled point series render as contiguous bars (the
+ * histogram look) without the caller pre-keying to intervals, while an
+ * interval-keyed series (e.g. an `aggregate`/`window` rollup) draws its true
+ * bucket spans. Detected by `keyColumn().kind === 'time'`.
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export declare function barsFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, column: string): BarSeries;
+//# sourceMappingURL=data.d.ts.map

package/dist/data.js

@@ -0,0 +1,197 @@
+/**
+ * Read a numeric column into a `Float64Array`, missing cells as `NaN`.
+ *
+ * Uses `read(i)` — a method on the column *class* — rather than the bulk
+ * `toFloat64Array()`. The bulk reader is mounted on the prototype by a
+ * side-effect import in pond-ts, which Vite/Rollup production builds tree-shake
+ * away (despite the package's `sideEffects` field), so it throws "not a
+ * function" in a bundled browser app. See `docs/notes/charts-m1-friction.md`.
+ *
+ * TODO(charts-perf): restore the bulk typed-array fast-path once the column-API
+ * augmentation is bundle-safe in core — that's the columnar throughput win.
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+function readNumericColumn(series, column) {
+    // Runtime-necessary even though it reads as dead code: `column()` returns
+    // `undefined` for an unknown name at runtime, but core's public overload
+    // currently types the result as non-`undefined` (see F-3 in the M1 friction
+    // note). Keep the guard — the "throws on unknown column" test exercises it.
+    const col = series.column(column);
+    if (col === undefined) {
+        throw new RangeError(`unknown column '${column}'`);
+    }
+    if (col.kind !== 'number') {
+        throw new TypeError(`column '${column}' must be numeric (got '${col.kind}')`);
+    }
+    const length = series.length;
+    const out = new Float64Array(length);
+    for (let i = 0; i < length; i += 1) {
+        const v = col.read(i);
+        out[i] = v === undefined ? NaN : v;
+    }
+    return out;
+}
+/** The key column's `begin` buffer aligned to the logical length (zero-copy). */
+function timeAxis(series) {
+    // `begin` may carry trailing capacity beyond the logical length; subarray so
+    // it lines up with the value arrays.
+    return series.keyColumn().begin.subarray(0, series.length);
+}
+/**
+ * The key column's `end` buffer aligned to the logical length (zero-copy). For a
+ * point-in-time key the column sets `end === begin`, so this returns the same
+ * timestamps as {@link timeAxis} — an interval key gives a distinct span.
+ */
+function timeEndAxis(series) {
+    return series.keyColumn().end.subarray(0, series.length);
+}
+/**
+ * Build a {@link ChartSeries} from a pond `TimeSeries` by reading its columnar
+ * buffers directly — no per-event materialization. `column` names a numeric
+ * value column; the key column supplies the time axis (`begin`, in ms).
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export function fromTimeSeries(series, column) {
+    return {
+        x: timeAxis(series),
+        y: readNumericColumn(series, column),
+        length: series.length,
+    };
+}
+/**
+ * Build a {@link ChartSeries} from a pond `ValueSeries` — the value-axis sibling
+ * of {@link fromTimeSeries}. The x axis is the series' monotonic value axis
+ * (`axisValues()`, e.g. cumulative distance) instead of time; `column` names a
+ * numeric value channel (HR, pace, …). The resulting `ChartSeries` is identical
+ * in shape — the chart draws it exactly as it draws a time series, only the x
+ * scale differs (a value scale rather than `scaleTime`).
+ *
+ * `x` is the axis key buffer zero-copy (immutable by contract — do not mutate);
+ * `y` is the channel materialized to a `Float64Array`, missing cells as `NaN`
+ * (the gap signal, same `Number.isFinite` contract as {@link fromTimeSeries}).
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export function fromValueSeries(series, column) {
+    const col = series.column(column);
+    if (col === undefined) {
+        throw new RangeError(`unknown column '${column}'`);
+    }
+    if (col.kind !== 'number') {
+        throw new TypeError(`column '${column}' must be numeric (got '${col.kind}')`);
+    }
+    const length = series.length;
+    const y = new Float64Array(length);
+    for (let i = 0; i < length; i += 1) {
+        const v = col.read(i);
+        y[i] = v === undefined ? NaN : v;
+    }
+    // axisValues() is the key buffer already trimmed to length (zero-copy).
+    return { x: series.axisValues(), y, length };
+}
+/**
+ * Build a {@link BandSeries} from a pond `TimeSeries` — two numeric columns for
+ * the `lower`/`upper` edges sharing the series' time axis. The edge columns are
+ * typically `rollingByColumn` percentiles (e.g. p25/p75); a sample with either
+ * edge missing reads as a gap in the fill.
+ *
+ * @throws RangeError if `lower` or `upper` does not exist.
+ * @throws TypeError if `lower` or `upper` is not a numeric column.
+ */
+export function bandFromTimeSeries(series, lower, upper) {
+    return {
+        x: timeAxis(series),
+        lower: readNumericColumn(series, lower),
+        upper: readNumericColumn(series, upper),
+        length: series.length,
+    };
+}
+/**
+ * Build a {@link BoxSeries} from a pond `TimeSeries` — five numeric quantile
+ * columns (`lower`/`q1`/`median`/`q3`/`upper`) sharing the series' interval time
+ * axis (`begin`/`end`, the box's horizontal span). The quantile columns are
+ * typically `rolling`/`aggregate` percentiles (e.g. p5/p25/p50/p75/p95); a key
+ * with any quantile missing reads as a gap (the box draws nothing).
+ *
+ * @throws RangeError if any quantile column does not exist.
+ * @throws TypeError if any quantile column is not a numeric column.
+ */
+export function boxFromTimeSeries(series, columns) {
+    return {
+        x: timeAxis(series),
+        xEnd: timeEndAxis(series),
+        lower: readNumericColumn(series, columns.lower),
+        q1: readNumericColumn(series, columns.q1),
+        median: readNumericColumn(series, columns.median),
+        q3: readNumericColumn(series, columns.q3),
+        upper: readNumericColumn(series, columns.upper),
+        length: series.length,
+    };
+}
+/**
+ * Per-row begin/end buffers for the key column, each aligned to the logical
+ * length (zero-copy views). For an interval / timeRange key these are the key's
+ * own endpoints; for a point (`time`) key `end === begin`, which
+ * {@link barsFromTimeSeries} then widens into a span.
+ */
+function keyBeginEnd(series) {
+    const key = series.keyColumn();
+    const n = series.length;
+    // `begin`/`end` may carry trailing capacity beyond the logical length; subarray
+    // so they line up with the value array. A `time` key's `end` aliases `begin`
+    // (point-in-time), which the caller's point-key fallback replaces.
+    return { begin: key.begin.subarray(0, n), end: key.end.subarray(0, n) };
+}
+/**
+ * Build a {@link BarSeries} from a pond `TimeSeries` — one bar per event, the
+ * key's `[begin, end]` as the x-span and `column` as the height.
+ *
+ * **Key-shape fallback (point-keyed series).** The primary form is
+ * interval / timeRange-keyed, where each key already carries a `[begin, end]`
+ * span. A **point-keyed** (`time`) series has `begin === end` (zero width), so
+ * this derives a span from neighbour spacing: each bar is centred on its
+ * timestamp and reaches **halfway to each neighbour** (a Voronoi cell on the
+ * time axis). The first/last bars mirror their single adjacent gap so the row's
+ * end bars match their interior width. A lone point (length 1) has no
+ * neighbour, so it keeps zero width and falls back to the renderer's `minWidth`.
+ *
+ * This makes a uniformly-sampled point series render as contiguous bars (the
+ * histogram look) without the caller pre-keying to intervals, while an
+ * interval-keyed series (e.g. an `aggregate`/`window` rollup) draws its true
+ * bucket spans. Detected by `keyColumn().kind === 'time'`.
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export function barsFromTimeSeries(series, column) {
+    const y = readNumericColumn(series, column);
+    const n = series.length;
+    const kind = series.keyColumn().kind;
+    if (kind !== 'time') {
+        // Interval / timeRange: the key's own endpoints are the bar span.
+        const { begin, end } = keyBeginEnd(series);
+        return { begin, end, y, length: n };
+    }
+    // Point key (begin === end): synthesize a span from neighbour spacing so the
+    // bars have width. Copy into fresh buffers — the key's begin buffer is shared
+    // (zero-copy) and must not be mutated.
+    const src = series.keyColumn().begin;
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const t = src[i];
+        // Half-gap to the previous point (mirror the next gap at the left edge).
+        const prevGap = i > 0 ? t - src[i - 1] : i + 1 < n ? src[i + 1] - t : 0;
+        // Half-gap to the next point (mirror the previous gap at the right edge).
+        const nextGap = i + 1 < n ? src[i + 1] - t : i > 0 ? t - src[i - 1] : 0;
+        begin[i] = t - prevGap / 2;
+        end[i] = t + nextGap / 2;
+    }
+    return { begin, end, y, length: n };
+}
+//# sourceMappingURL=data.js.map

package/dist/domain.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve a y-axis `[lo, hi]` domain from its explicit bounds and the extents of
+ * the layers linked to it. An `undefined` bound auto-fits the data: with no
+ * finite data the domain is `[0, 1]`, a flat extent gets ±1 of headroom (so a
+ * constant line sits mid-row, not on an edge).
+ *
+ * A **fully auto-fit** domain (both bounds `undefined`) is rounded out to nice
+ * boundaries (d3 `.nice()`) — headroom so peaks / whisker caps don't sit on the
+ * plot edge, plus rounder tick values. An explicit bound (full or partial) is
+ * left **exact**: the caller's number is never nice'd or moved.
+ *
+ * Guarantees an **ascending, non-degenerate** domain whenever a bound was
+ * auto-fit — a partial explicit bound with no (or flat) data on the other side
+ * can otherwise invert it (e.g. `min=5` with no data would naively give
+ * `[5, 1]`). Two explicit bounds are returned as-is (an inverted explicit domain
+ * is a deliberate axis flip; we don't second-guess it).
+ */
+export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>): [number, number];
+//# sourceMappingURL=domain.d.ts.map

package/dist/domain.js

@@ -0,0 +1,61 @@
+import { scaleLinear } from 'd3-scale';
+/**
+ * Resolve a y-axis `[lo, hi]` domain from its explicit bounds and the extents of
+ * the layers linked to it. An `undefined` bound auto-fits the data: with no
+ * finite data the domain is `[0, 1]`, a flat extent gets ±1 of headroom (so a
+ * constant line sits mid-row, not on an edge).
+ *
+ * A **fully auto-fit** domain (both bounds `undefined`) is rounded out to nice
+ * boundaries (d3 `.nice()`) — headroom so peaks / whisker caps don't sit on the
+ * plot edge, plus rounder tick values. An explicit bound (full or partial) is
+ * left **exact**: the caller's number is never nice'd or moved.
+ *
+ * Guarantees an **ascending, non-degenerate** domain whenever a bound was
+ * auto-fit — a partial explicit bound with no (or flat) data on the other side
+ * can otherwise invert it (e.g. `min=5` with no data would naively give
+ * `[5, 1]`). Two explicit bounds are returned as-is (an inverted explicit domain
+ * is a deliberate axis flip; we don't second-guess it).
+ */
+export function resolveYDomain(min, max, extents) {
+    // Both bounds explicit: trust them verbatim (allows an intentional flip).
+    if (min !== undefined && max !== undefined)
+        return [min, max];
+    let dataMin = Infinity;
+    let dataMax = -Infinity;
+    for (const e of extents) {
+        if (e) {
+            if (e[0] < dataMin)
+                dataMin = e[0];
+            if (e[1] > dataMax)
+                dataMax = e[1];
+        }
+    }
+    if (dataMin === Infinity) {
+        dataMin = 0; // no finite data yet
+        dataMax = 1;
+    }
+    else if (dataMin === dataMax) {
+        dataMin -= 1; // flat — give it room
+        dataMax += 1;
+    }
+    let lo = min ?? dataMin;
+    let hi = max ?? dataMax;
+    // A partial explicit bound can sit at/above the auto-fit other side (explicit
+    // min above empty-data's max, or explicit max below the data). Keep the axis
+    // ascending by moving the *auto-fit* side — never discard the caller's
+    // explicit bound. Exactly one side is explicit here: both-explicit returned
+    // early, and a both-auto domain can't invert after the empty/flat guards.
+    if (lo >= hi) {
+        if (min === undefined)
+            lo = hi - 1; // max is explicit → preserve it
+        else
+            hi = lo + 1; // min is explicit → preserve it
+    }
+    // Fully auto-fit → round the domain out for headroom + nicer ticks. A
+    // partial/full explicit bound is left exact (returned as-is below).
+    if (min === undefined && max === undefined) {
+        return scaleLinear().domain([lo, hi]).nice().domain();
+    }
+    return [lo, hi];
+}
+//# sourceMappingURL=domain.js.map

package/dist/encoding.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Data-driven point encoding for {@link ScatterChart} — the **deliberate,
+ * signed-off exception** to the package's single-styling-channel rule.
+ *
+ * Every other layer takes one styling input: a semantic `as` token the theme
+ * maps to a style. That discipline exists because react-timeseries-charts' free
+ * per-component style accessor (a function from a datum to a style object) bred
+ * a class of styling bugs. Scatter keeps the base mark on that same channel
+ * (`theme.scatter[as]` → the default radius + colour) but **adds** size and
+ * colour driven *from the data*: a column value run through a scale. The
+ * difference that keeps this safe is that the input is a **column name + a
+ * range**, not an arbitrary callback — there is no place to hide a styling bug
+ * in `{ column: 'velocity', range: [2, 12] }`.
+ *
+ * Both encodings build a *linear* scale over the **finite extent** of the named
+ * column (NaN / missing cells ignored, so a gap doesn't drag the domain) and map
+ * it into the requested output range. The scale is precomputed once per resolve;
+ * the returned `radiusAt` / `colorAt` are O(1) per point.
+ *
+ * Pure + unit-tested (`test/encoding.test.ts`); scatter is the sole consumer.
+ */
+import type { ChartSeries } from './data.js';
+/**
+ * Per-point **radius** encoding. Either:
+ * - a fixed radius in CSS px (every point the same size — the common case), or
+ * - `{ column, range }`: map the column's finite extent linearly onto
+ *   `[minR, maxR]` px. A point whose radius column is non-finite falls back to
+ *   the base radius (it still draws, at the default size).
+ *
+ * **Omitted ⇒ the base radius** from the style (`theme.scatter[as].radius`).
+ */
+export type RadiusEncoding = number | {
+    /** Numeric column whose value drives each point's radius. */
+    readonly column: string;
+    /** Output radius range in px, `[atColumnMin, atColumnMax]`. */
+    readonly range: readonly [number, number];
+};
+/**
+ * Per-point **colour** encoding — `{ column, range }`: map the column's finite
+ * extent linearly onto a two-stop colour ramp `[atMin, atMax]` (interpolated in
+ * sRGB). A point whose colour column is non-finite falls back to the base colour
+ * (the single styling channel — `theme.scatter[as].color`).
+ *
+ * **Omitted ⇒ the base colour** for every point. The `range` stops must be CSS
+ * hex (`#rgb` / `#rrggbb`); a non-hex stop disables interpolation for that point
+ * (falls back to the base colour) rather than guessing.
+ */
+export interface ColorEncoding {
+    /** Numeric column whose value drives each point's colour. */
+    readonly column: string;
+    /** Two-stop colour ramp, `[atColumnMin, atColumnMax]` — CSS hex. */
+    readonly range: readonly [string, string];
+}
+/**
+ * A resolved encoding: O(1) per-point accessors over a {@link ChartSeries}'
+ * index. `radiusAt`/`colorAt` are indexed by the *same* row position as the
+ * scatter's `x`/`y` arrays — a point with a non-finite encoding value (or no
+ * encoding configured) gets the base radius / colour.
+ */
+export interface ResolvedEncoding {
+    /** This point's radius in px (base radius if unencoded / non-finite). */
+    radiusAt(i: number): number;
+    /** This point's fill colour (base colour if unencoded / non-finite). */
+    colorAt(i: number): string;
+}
+/** A numeric column read into a `Float64Array` (gaps as NaN), by name. */
+export type ColumnReader = (column: string) => Float64Array;
+/**
+ * The `[min, max]` of the **finite** values in `col`, or `null` if none are
+ * finite. (Same gap-aware contract as `yExtent`; duplicated here so encoding
+ * stays a leaf module with no draw-layer dependency.)
+ */
+export declare function finiteExtent(col: Float64Array): [number, number] | null;
+/**
+ * Resolve a scatter's data-driven encoding into O(1) per-point accessors.
+ *
+ * @param cs        the scatter's columnar view (its `length` bounds the indices)
+ * @param baseRadius the style's base radius (the fixed-size fallback)
+ * @param baseColor  the style's base colour (the single-styling-channel colour)
+ * @param radius     the {@link RadiusEncoding} (a number, a `{column,range}`, or omitted)
+ * @param color      the {@link ColorEncoding} (a `{column,range}`, or omitted)
+ * @param readColumn reads a named numeric column to a `Float64Array` (gaps NaN)
+ *
+ * A `{column}` encoding whose column is entirely non-finite degrades to the base
+ * value (no scale to build); an individual non-finite cell likewise falls back,
+ * so every point always resolves to a finite radius and a concrete colour.
+ */
+export declare function resolveEncoding(cs: ChartSeries, baseRadius: number, baseColor: string, radius: RadiusEncoding | undefined, color: ColorEncoding | undefined, readColumn: ColumnReader): ResolvedEncoding;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/encoding.js

@@ -0,0 +1,144 @@
+/**
+ * Data-driven point encoding for {@link ScatterChart} — the **deliberate,
+ * signed-off exception** to the package's single-styling-channel rule.
+ *
+ * Every other layer takes one styling input: a semantic `as` token the theme
+ * maps to a style. That discipline exists because react-timeseries-charts' free
+ * per-component style accessor (a function from a datum to a style object) bred
+ * a class of styling bugs. Scatter keeps the base mark on that same channel
+ * (`theme.scatter[as]` → the default radius + colour) but **adds** size and
+ * colour driven *from the data*: a column value run through a scale. The
+ * difference that keeps this safe is that the input is a **column name + a
+ * range**, not an arbitrary callback — there is no place to hide a styling bug
+ * in `{ column: 'velocity', range: [2, 12] }`.
+ *
+ * Both encodings build a *linear* scale over the **finite extent** of the named
+ * column (NaN / missing cells ignored, so a gap doesn't drag the domain) and map
+ * it into the requested output range. The scale is precomputed once per resolve;
+ * the returned `radiusAt` / `colorAt` are O(1) per point.
+ *
+ * Pure + unit-tested (`test/encoding.test.ts`); scatter is the sole consumer.
+ */
+/**
+ * The `[min, max]` of the **finite** values in `col`, or `null` if none are
+ * finite. (Same gap-aware contract as `yExtent`; duplicated here so encoding
+ * stays a leaf module with no draw-layer dependency.)
+ */
+export function finiteExtent(col) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < col.length; i += 1) {
+        const v = col[i];
+        if (Number.isFinite(v)) {
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+    }
+    return min === Infinity ? null : [min, max];
+}
+/** Linear interpolate `t` (0..1) across `[a, b]`. */
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/** Parse a CSS hex colour to `[r, g, b]` (0–255), or `null` if not hex. */
+function parseHex(color) {
+    const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+    if (m === null)
+        return null;
+    const h = m[1];
+    if (h.length === 3) {
+        return [
+            parseInt(h[0] + h[0], 16),
+            parseInt(h[1] + h[1], 16),
+            parseInt(h[2] + h[2], 16),
+        ];
+    }
+    return [
+        parseInt(h.slice(0, 2), 16),
+        parseInt(h.slice(2, 4), 16),
+        parseInt(h.slice(4, 6), 16),
+    ];
+}
+/** Interpolate two hex colours in sRGB at `t` (0..1) → `rgb(r, g, b)`. */
+function mixHex(from, to, t) {
+    const a = parseHex(from);
+    const b = parseHex(to);
+    if (a === null || b === null)
+        return from; // non-hex stop: leave it to caller
+    const r = Math.round(lerp(a[0], b[0], t));
+    const g = Math.round(lerp(a[1], b[1], t));
+    const bl = Math.round(lerp(a[2], b[2], t));
+    return `rgb(${r}, ${g}, ${bl})`;
+}
+/** Position of `v` within `[min, max]` as a clamped 0..1 fraction (0 if flat). */
+function normalize(v, min, max) {
+    if (max - min < 1e-12)
+        return 0; // degenerate extent → everything at the low stop
+    const t = (v - min) / (max - min);
+    return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+/**
+ * Resolve a scatter's data-driven encoding into O(1) per-point accessors.
+ *
+ * @param cs        the scatter's columnar view (its `length` bounds the indices)
+ * @param baseRadius the style's base radius (the fixed-size fallback)
+ * @param baseColor  the style's base colour (the single-styling-channel colour)
+ * @param radius     the {@link RadiusEncoding} (a number, a `{column,range}`, or omitted)
+ * @param color      the {@link ColorEncoding} (a `{column,range}`, or omitted)
+ * @param readColumn reads a named numeric column to a `Float64Array` (gaps NaN)
+ *
+ * A `{column}` encoding whose column is entirely non-finite degrades to the base
+ * value (no scale to build); an individual non-finite cell likewise falls back,
+ * so every point always resolves to a finite radius and a concrete colour.
+ */
+export function resolveEncoding(cs, baseRadius, baseColor, radius, color, readColumn) {
+    // --- radius ---
+    let radiusAt;
+    if (radius === undefined || typeof radius === 'number') {
+        const r = radius === undefined ? baseRadius : radius;
+        radiusAt = () => r;
+    }
+    else {
+        const col = readColumn(radius.column);
+        const extent = finiteExtent(col);
+        const [minR, maxR] = radius.range;
+        if (extent === null) {
+            radiusAt = () => baseRadius; // column has no finite values
+        }
+        else {
+            const [lo, hi] = extent;
+            radiusAt = (i) => {
+                const v = col[i];
+                if (!Number.isFinite(v))
+                    return baseRadius;
+                return lerp(minR, maxR, normalize(v, lo, hi));
+            };
+        }
+    }
+    // --- colour ---
+    let colorAt;
+    if (color === undefined) {
+        colorAt = () => baseColor;
+    }
+    else {
+        const col = readColumn(color.column);
+        const extent = finiteExtent(col);
+        const [from, to] = color.range;
+        if (extent === null) {
+            colorAt = () => baseColor;
+        }
+        else {
+            const [lo, hi] = extent;
+            colorAt = (i) => {
+                const v = col[i];
+                if (!Number.isFinite(v))
+                    return baseColor;
+                return mixHex(from, to, normalize(v, lo, hi));
+            };
+        }
+    }
+    return { radiusAt, colorAt };
+}
+//# sourceMappingURL=encoding.js.map