@svgrid/grid 3.0.2 → 3.0.4

package/dist/chart-stats.js

@@ -0,0 +1,419 @@
+// The two trend primitives live in their own leaf (see chart-trend.ts for
+// why) and are re-exported here so every importer of chart-stats keeps working.
+export { linearTrend, pearson } from './chart-trend.js';
+/**
+ * Five-number summary of a raw sample, with the 1.5 IQR whisker rule.
+ *
+ * Whiskers stop at the last observation INSIDE the fence rather than at the
+ * fence itself, which is what makes them read as real data; anything past them
+ * comes back in `outliers`. Quartiles use linear interpolation between the two
+ * neighbouring order statistics.
+ *
+ * Returns `null` for an empty sample, so a category with no observations is a
+ * gap rather than a box drawn at zero.
+ */
+export function boxStats(sample, whisker = 1.5) {
+    const v = sample.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b);
+    if (!v.length)
+        return null;
+    const q = (p) => {
+        const pos = (v.length - 1) * p;
+        const lo = Math.floor(pos);
+        const hi = Math.ceil(pos);
+        return lo === hi ? v[lo] : v[lo] + (v[hi] - v[lo]) * (pos - lo);
+    };
+    const q1 = q(0.25);
+    const median = q(0.5);
+    const q3 = q(0.75);
+    const fenceLo = q1 - whisker * (q3 - q1);
+    const fenceHi = q3 + whisker * (q3 - q1);
+    const inside = v.filter((n) => n >= fenceLo && n <= fenceHi);
+    const outliers = v.filter((n) => n < fenceLo || n > fenceHi);
+    return {
+        // `inside` can only be empty if every point is an outlier, which the fence
+        // rule makes impossible (q1 and q3 are always within it) - but a degenerate
+        // sample should still produce a box rather than `undefined` coordinates.
+        min: inside.length ? inside[0] : v[0],
+        q1,
+        median,
+        q3,
+        max: inside.length ? inside[inside.length - 1] : v[v.length - 1],
+        ...(outliers.length ? { outliers } : {}),
+    };
+}
+const NO_FIT = (values) => ({ fitted: values.map(() => NaN), r2: 0, equation: '', predict: () => NaN });
+/** The x of each value: the caller's, else the index. */
+const xsOf = (values, xs) => (xs ? values.map((_, i) => xs[i] ?? NaN) : values.map((_, i) => i));
+/** R-squared of a fit: 1 minus residual over total variance across the
+ *  indices where both the value and the fit are finite. 0 when there is no
+ *  variance to explain. */
+export function rSquared(values, fitted) {
+    let n = 0;
+    let mean = 0;
+    for (let i = 0; i < values.length; i += 1) {
+        if (Number.isFinite(values[i]) && Number.isFinite(fitted[i])) {
+            n += 1;
+            mean += values[i];
+        }
+    }
+    if (n < 2)
+        return 0;
+    mean /= n;
+    let ssRes = 0;
+    let ssTot = 0;
+    for (let i = 0; i < values.length; i += 1) {
+        if (!Number.isFinite(values[i]) || !Number.isFinite(fitted[i]))
+            continue;
+        ssRes += (values[i] - fitted[i]) ** 2;
+        ssTot += (values[i] - mean) ** 2;
+    }
+    if (ssTot === 0)
+        return ssRes === 0 ? 1 : 0;
+    return Math.max(0, Math.min(1, 1 - ssRes / ssTot));
+}
+const fmtCoef = (c) => (Math.abs(c) >= 1000 || (Math.abs(c) < 0.001 && c !== 0) ? c.toExponential(2) : String(Math.round(c * 1000) / 1000));
+/** Solve a small linear system by Gaussian elimination with partial pivoting;
+ *  null when singular. */
+function solve(a, b) {
+    const n = b.length;
+    const m = a.map((row, i) => [...row, b[i]]);
+    for (let c = 0; c < n; c += 1) {
+        let p = c;
+        for (let r = c + 1; r < n; r += 1)
+            if (Math.abs(m[r][c]) > Math.abs(m[p][c]))
+                p = r;
+        if (Math.abs(m[p][c]) < 1e-12)
+            return null;
+        [m[c], m[p]] = [m[p], m[c]];
+        for (let r = 0; r < n; r += 1) {
+            if (r === c)
+                continue;
+            const f = m[r][c] / m[c][c];
+            for (let k = c; k <= n; k += 1)
+                m[r][k] -= f * m[c][k];
+        }
+    }
+    return m.map((row, i) => row[n] / row[i]);
+}
+/**
+ * Least-squares polynomial of `degree` (clamped to 1..6) through
+ * (x, values[i]), x the index or the caller's `xs`. The x values are
+ * normalised to [-1, 1] before the normal equations are solved, so a
+ * degree-6 fit over a thousand points does not lose the low coefficients to
+ * rounding. Non-finite values are skipped and fitted as NaN.
+ */
+export function polynomialFit(values, degree, xs) {
+    const d = Math.max(1, Math.min(6, Math.round(degree)));
+    const n = values.length;
+    const nan = NO_FIT(values);
+    const X = xsOf(values, xs);
+    const idx = [];
+    for (let i = 0; i < n; i += 1)
+        if (Number.isFinite(values[i]) && Number.isFinite(X[i]))
+            idx.push(i);
+    if (idx.length <= d)
+        return nan;
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const i of idx) {
+        lo = Math.min(lo, X[i]);
+        hi = Math.max(hi, X[i]);
+    }
+    if (!xs) {
+        lo = 0;
+        hi = Math.max(1, n - 1);
+    }
+    const scale = Math.max(hi - lo, 1e-12);
+    const nx = (x) => (2 * (x - lo)) / scale - 1;
+    // Normal equations: sum x^(j+k) c_k = sum x^j y.
+    const a = Array.from({ length: d + 1 }, () => new Array(d + 1).fill(0));
+    const b = new Array(d + 1).fill(0);
+    for (const i of idx) {
+        const x = nx(X[i]);
+        const y = values[i];
+        const pow = [1];
+        for (let k = 1; k <= 2 * d; k += 1)
+            pow.push(pow[k - 1] * x);
+        for (let j = 0; j <= d; j += 1) {
+            b[j] += pow[j] * y;
+            for (let k = 0; k <= d; k += 1)
+                a[j][k] += pow[j + k];
+        }
+    }
+    const c = solve(a, b);
+    if (!c)
+        return nan;
+    const predict = (x) => {
+        const u = nx(x);
+        let y = 0;
+        let p = 1;
+        for (let k = 0; k <= d; k += 1) {
+            y += c[k] * p;
+            p *= u;
+        }
+        return y;
+    };
+    const fitted = values.map((v, i) => (Number.isFinite(v) && Number.isFinite(X[i]) ? predict(X[i]) : NaN));
+    const terms = c.map((ck, k) => (k === 0 ? fmtCoef(ck) : `${fmtCoef(ck)} u^${k}`)).reverse();
+    const u = xs ? `u = 2(x - ${fmtCoef(lo)})/${fmtCoef(scale)} - 1` : `u = 2x/${scale} - 1`;
+    return { fitted, r2: rSquared(values, fitted), equation: `y = ${terms.join(' + ')} (${u})`, predict };
+}
+/** Ordinary least squares of values on their index, or on `xs`, as a {@link RegressionFit}. */
+export function linearFit(values, xs) {
+    const X = xsOf(values, xs);
+    const { slope, intercept, ok } = lineThrough(X, values);
+    if (!ok)
+        return NO_FIT(values);
+    const predict = (x) => slope * x + intercept;
+    const fitted = values.map((v, i) => (Number.isFinite(v) && Number.isFinite(X[i]) ? predict(X[i]) : NaN));
+    return { fitted, r2: rSquared(values, fitted), equation: `y = ${fmtCoef(slope)} x + ${fmtCoef(intercept)}`, predict };
+}
+/** Fit y = a * e^(b x) by least squares on ln y, x the index or `xs`;
+ *  values at or below zero cannot be logged and are skipped (fitted as NaN). */
+export function exponentialFit(values, xs) {
+    const X = xsOf(values, xs);
+    const logs = values.map((v) => (Number.isFinite(v) && v > 0 ? Math.log(v) : NaN));
+    const { slope: b, intercept, ok } = lineThrough(X, logs);
+    if (!ok)
+        return NO_FIT(values);
+    const a = Math.exp(intercept);
+    const predict = (x) => a * Math.exp(b * x);
+    const fitted = values.map((v, i) => (Number.isFinite(v) && v > 0 && Number.isFinite(X[i]) ? predict(X[i]) : NaN));
+    return { fitted, r2: rSquared(values, fitted), equation: `y = ${fmtCoef(a)} e^(${fmtCoef(b)} x)`, predict };
+}
+/** Fit y = a + b ln(x + 1) by least squares (x the index, shifted by one so
+ *  the first point has a logarithm), or y = a + b ln(x) on `xs`, where
+ *  points with x at or below zero are skipped. */
+export function logarithmicFit(values, xs) {
+    const shift = xs ? 0 : 1;
+    const lx = xsOf(values, xs).map((x) => (x + shift > 0 ? Math.log(x + shift) : NaN));
+    const { slope, intercept, ok } = lineThrough(lx, values);
+    if (!ok)
+        return NO_FIT(values);
+    const predict = (x) => (x + shift > 0 ? intercept + slope * Math.log(x + shift) : NaN);
+    const fitted = values.map((v, i) => (Number.isFinite(v) && Number.isFinite(lx[i]) ? intercept + slope * lx[i] : NaN));
+    const arg = xs ? 'x' : 'x + 1';
+    return { fitted, r2: rSquared(values, fitted), equation: `y = ${fmtCoef(intercept)} + ${fmtCoef(slope)} ln(${arg})`, predict };
+}
+/** Fit y = a (x + 1)^b by least squares on ln y against ln(x + 1), or
+ *  y = a x^b on `xs`; values (and x on `xs`) at or below zero are skipped
+ *  (fitted as NaN). */
+export function powerFit(values, xs) {
+    const shift = xs ? 0 : 1;
+    const lx = xsOf(values, xs).map((x) => (x + shift > 0 ? Math.log(x + shift) : NaN));
+    const logs = values.map((v) => (Number.isFinite(v) && v > 0 ? Math.log(v) : NaN));
+    const { slope, intercept, ok } = lineThrough(lx, logs);
+    if (!ok)
+        return NO_FIT(values);
+    const a = Math.exp(intercept);
+    const predict = (x) => (x + shift > 0 ? a * Math.pow(x + shift, slope) : NaN);
+    const fitted = values.map((v, i) => (Number.isFinite(v) && v > 0 && Number.isFinite(lx[i]) ? a * Math.exp(slope * lx[i]) : NaN));
+    const arg = xs ? 'x' : '(x + 1)';
+    return { fitted, r2: rSquared(values, fitted), equation: `y = ${fmtCoef(a)} ${arg}^${fmtCoef(slope)}`, predict };
+}
+/** Least squares of y on arbitrary x, skipping non-finite pairs. */
+function lineThrough(xs, ys) {
+    let n = 0, sx = 0, sy = 0, sxx = 0, sxy = 0;
+    for (let i = 0; i < ys.length; i += 1) {
+        const x = xs[i];
+        const y = ys[i];
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            continue;
+        n += 1;
+        sx += x;
+        sy += y;
+        sxx += x * x;
+        sxy += x * y;
+    }
+    if (n < 2)
+        return { slope: 0, intercept: 0, ok: false };
+    const denom = n * sxx - sx * sx;
+    const slope = denom === 0 ? 0 : (n * sxy - sx * sy) / denom;
+    return { slope, intercept: (sy - slope * sx) / n, ok: true };
+}
+/** Simple moving average over a window of `period` values. Window centres
+ *  trail to the right (typical for time-series). NaN for points before the
+ *  window is full. */
+export function simpleMovingAverage(values, period) {
+    if (period < 1)
+        return values.slice();
+    const out = new Array(values.length).fill(NaN);
+    let sum = 0, count = 0;
+    for (let i = 0; i < values.length; i += 1) {
+        const v = values[i];
+        if (Number.isFinite(v)) {
+            sum += v;
+            count += 1;
+        }
+        if (i >= period) {
+            const drop = values[i - period];
+            if (Number.isFinite(drop)) {
+                sum -= drop;
+                count -= 1;
+            }
+        }
+        if (i >= period - 1 && count > 0)
+            out[i] = sum / count;
+    }
+    return out;
+}
+/** Exponential moving average. Smoothing factor alpha = 2 / (period + 1). */
+export function exponentialMovingAverage(values, period) {
+    const alpha = 2 / (Math.max(1, period) + 1);
+    const out = new Array(values.length).fill(NaN);
+    let prev = null;
+    for (let i = 0; i < values.length; i += 1) {
+        const v = values[i];
+        if (!Number.isFinite(v)) {
+            out[i] = prev ?? NaN;
+            continue;
+        }
+        prev = prev == null ? v : alpha * v + (1 - alpha) * prev;
+        out[i] = prev;
+    }
+    return out;
+}
+/** The reducers that need every observation, not a running sum and count. */
+export function reducerNeedsSamples(reducer) {
+    return !(reducer === 'sum' || reducer === 'avg' || reducer === 'count');
+}
+/**
+ * Collapse a group's observations to one number. `sum` / `avg` / `count` are
+ * what `rowsToChartSpec` always did; the rest are the ones a pivot table
+ * offers and a chart panel was missing: `min`, `max`, `median`, `first`,
+ * `last`, `countDistinct`, and `pN` for the Nth percentile (`'p90'`). An
+ * empty group reduces to 0 for `sum` / `count` and to NaN otherwise, so a
+ * missing bucket draws as a gap rather than as a fake zero.
+ */
+export function reduceValues(samples, reducer) {
+    const n = samples.length;
+    switch (reducer) {
+        case 'count':
+            return n;
+        case 'sum': {
+            let s = 0;
+            for (const v of samples)
+                s += v;
+            return s;
+        }
+        case 'avg': {
+            if (!n)
+                return 0;
+            let s = 0;
+            for (const v of samples)
+                s += v;
+            return s / n;
+        }
+        case 'min':
+            return n ? Math.min(...samples) : Number.NaN;
+        case 'max':
+            return n ? Math.max(...samples) : Number.NaN;
+        case 'first':
+            return n ? samples[0] : Number.NaN;
+        case 'last':
+            return n ? samples[n - 1] : Number.NaN;
+        case 'countDistinct':
+            return new Set(samples).size;
+        case 'median':
+            return percentile(samples, 50);
+        default: {
+            const m = /^p(\d+(?:\.\d+)?)$/.exec(reducer);
+            return m ? percentile(samples, Number(m[1])) : Number.NaN;
+        }
+    }
+}
+/** The p-th percentile (0..100) by linear interpolation between order statistics. */
+export function percentile(samples, p) {
+    const v = samples.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b);
+    if (!v.length)
+        return Number.NaN;
+    const pos = (v.length - 1) * Math.max(0, Math.min(100, p)) / 100;
+    const lo = Math.floor(pos);
+    const hi = Math.ceil(pos);
+    return lo === hi ? v[lo] : v[lo] + (v[hi] - v[lo]) * (pos - lo);
+}
+/**
+ * The ISO date (`YYYY-MM-DD`, UTC) that starts the bucket containing `date`:
+ * the day itself, the Monday of its week, the first of its month, quarter or
+ * year. Returns `''` for a value that is not a date, so the caller can drop
+ * the row rather than file it under 1970.
+ */
+export function bucketStart(date, bucket) {
+    const t = date instanceof Date ? date.getTime() : typeof date === 'number' ? date : Date.parse(date);
+    if (!Number.isFinite(t))
+        return '';
+    const d = new Date(t);
+    const y = d.getUTCFullYear();
+    const m = d.getUTCMonth();
+    let out;
+    switch (bucket) {
+        case 'day':
+            out = new Date(Date.UTC(y, m, d.getUTCDate()));
+            break;
+        case 'week': {
+            // Monday-based, which is what a business calendar reads.
+            const day = (d.getUTCDay() + 6) % 7;
+            out = new Date(Date.UTC(y, m, d.getUTCDate() - day));
+            break;
+        }
+        case 'month':
+            out = new Date(Date.UTC(y, m, 1));
+            break;
+        case 'quarter':
+            out = new Date(Date.UTC(y, m - (m % 3), 1));
+            break;
+        default:
+            out = new Date(Date.UTC(y, 0, 1));
+    }
+    return out.toISOString().slice(0, 10);
+}
+/**
+ * Bin a raw sample for a histogram. The bin count comes from `bins`, from a
+ * `binWidth`, or from a rule: `'sturges'` (default, log2 n + 1), `'fd'`
+ * (Freedman-Diaconis, 2 IQR / cbrt n) or `'sqrt'`. The range is the data's
+ * extent unless `min` / `max` pin it; the top edge is inclusive. Edges are
+ * rounded to a sensible precision for the width, so labels read as `10, 20,
+ * 30` rather than `10.000000001`.
+ */
+export function binValues(values, opts = {}) {
+    const v = values.filter((n) => Number.isFinite(n));
+    if (!v.length)
+        return { categories: [], counts: [], edges: [], width: 0 };
+    const lo = opts.min ?? Math.min(...v);
+    let hi = opts.max ?? Math.max(...v);
+    if (hi <= lo)
+        hi = lo + 1;
+    let count;
+    if (opts.bins && opts.bins > 0)
+        count = Math.round(opts.bins);
+    else if (opts.binWidth && opts.binWidth > 0)
+        count = Math.max(1, Math.ceil((hi - lo) / opts.binWidth));
+    else if (opts.method === 'sqrt')
+        count = Math.ceil(Math.sqrt(v.length));
+    else if (opts.method === 'fd') {
+        const iqr = percentile(v, 75) - percentile(v, 25);
+        const w = iqr > 0 ? (2 * iqr) / Math.cbrt(v.length) : 0;
+        count = w > 0 ? Math.ceil((hi - lo) / w) : Math.ceil(Math.log2(v.length) + 1);
+    }
+    else
+        count = Math.ceil(Math.log2(v.length) + 1);
+    count = Math.max(1, Math.min(1000, count));
+    const width = opts.binWidth && opts.binWidth > 0 ? opts.binWidth : (hi - lo) / count;
+    // Precision from the width: a 0.25 width keeps two decimals, a 10 width none.
+    const decimals = width >= 1 ? 0 : Math.min(6, Math.ceil(-Math.log10(width)) + 1);
+    const fix = (n) => Number(n.toFixed(decimals));
+    const edges = [];
+    for (let i = 0; i <= count; i += 1)
+        edges.push(fix(lo + i * width));
+    const counts = new Array(count).fill(0);
+    for (const n of v) {
+        let i = Math.floor((n - lo) / width);
+        if (i >= count)
+            i = count - 1;
+        if (i < 0)
+            i = 0;
+        counts[i] = (counts[i] ?? 0) + 1;
+    }
+    const categories = counts.map((_, i) => String(fix(lo + (i + 0.5) * width)));
+    return { categories, counts, edges, width };
+}

package/dist/chart-stream.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Live data. A feed hands a chart one new point every few hundred
+ * milliseconds; the spec is immutable state, so each tick wants a new spec
+ * with the point appended and the oldest dropped, with every per-category
+ * array kept in step. Demo 159 rebuilt the whole spec from a rows array on
+ * every tick; `appendPoints` does the append in one call and keeps the
+ * confidence bands, row ids, candles and volumes parallel by construction,
+ * because it walks the same key list the zoom window and decimation use.
+ */
+import type { ChartSpec, OhlcBar } from './chart-types.js';
+/** One new category with its values, for {@link appendPoints}. */
+export type ChartPoint = {
+    /** The category label (a date string on a time axis). */
+    category: string;
+    /** One value per series in spec order, or values keyed by series label;
+     *  a series not named gets a gap (NaN). */
+    values: ReadonlyArray<number> | Record<string, number>;
+    /** The bar for a candlestick series (the first series with `ohlc`). */
+    ohlc?: OhlcBar | null;
+    /** The volume for that series. */
+    volume?: number;
+    /** Row ids behind the point, one array per series in spec order. */
+    rowIds?: ReadonlyArray<ReadonlyArray<string | number>>;
+    /** Confidence band ends, one per series in spec order. */
+    upper?: ReadonlyArray<number>;
+    lower?: ReadonlyArray<number>;
+    /** Range low / bullet target, one per series in spec order. */
+    low?: ReadonlyArray<number>;
+    target?: ReadonlyArray<number>;
+};
+/** What {@link appendPoints} takes besides the points. */
+export type AppendPointsOptions = {
+    /** Keep only the last `window` categories after appending. */
+    window?: number;
+};
+/**
+ * Append one or more points to a spec and return the new spec, trimmed to
+ * the trailing `window` categories when one is given. Every array a series
+ * carries per category (values, row ids, bands, candles, volumes, colours,
+ * markers, errors, lows, targets) grows by the same count, with a gap where
+ * the point says nothing; so do the spec-level ones (waterfall totals). The
+ * input is never mutated: only the arrays that grow are copied, which keeps
+ * Svelte's state diffing cheap at 4 Hz.
+ */
+export declare function appendPoints(spec: ChartSpec, points: ChartPoint | ReadonlyArray<ChartPoint>, opts?: AppendPointsOptions): ChartSpec;

package/dist/chart-stream.js

@@ -0,0 +1,91 @@
+import { PER_CATEGORY_SERIES_KEYS, PER_CATEGORY_SPEC_KEYS, pickCategories } from './chart-decimate.js';
+/** The gap value each per-category array takes when a point does not set it. */
+function gapFor(key) {
+    switch (key) {
+        case 'rowIds': return [];
+        case 'ohlc':
+        case 'boxes':
+        case 'markers':
+        case 'colors':
+        case 'errors': return null;
+        default: return Number.NaN;
+    }
+}
+/**
+ * Append one or more points to a spec and return the new spec, trimmed to
+ * the trailing `window` categories when one is given. Every array a series
+ * carries per category (values, row ids, bands, candles, volumes, colours,
+ * markers, errors, lows, targets) grows by the same count, with a gap where
+ * the point says nothing; so do the spec-level ones (waterfall totals). The
+ * input is never mutated: only the arrays that grow are copied, which keeps
+ * Svelte's state diffing cheap at 4 Hz.
+ */
+export function appendPoints(spec, points, opts = {}) {
+    const list = Array.isArray(points) ? points : [points];
+    if (!list.length)
+        return opts.window ? trim(spec, opts.window) : spec;
+    const categories = [...spec.categories, ...list.map((p) => p.category)];
+    const ohlcOwner = spec.series.findIndex((s) => s.ohlc);
+    const series = spec.series.map((s, si) => {
+        const next = { ...s, values: [...s.values] };
+        for (const p of list) {
+            const v = Array.isArray(p.values) ? p.values[si] : p.values[s.label];
+            next.values.push(typeof v === 'number' ? v : Number.NaN);
+        }
+        for (const key of PER_CATEGORY_SERIES_KEYS) {
+            if (key === 'values')
+                continue;
+            const has = s[key] !== undefined;
+            // A key the series does not carry is only created when a point brings
+            // it (a candle, a volume), so a plain line stays a plain line.
+            const brings = list.some((p) => (key === 'ohlc' && p.ohlc !== undefined && si === (ohlcOwner < 0 ? 0 : ohlcOwner)) ||
+                (key === 'volumes' && p.volume !== undefined && si === (ohlcOwner < 0 ? 0 : ohlcOwner)) ||
+                (key === 'rowIds' && p.rowIds?.[si] !== undefined) ||
+                (key === 'upperValues' && p.upper?.[si] !== undefined) ||
+                (key === 'lowerValues' && p.lower?.[si] !== undefined) ||
+                (key === 'lowValues' && p.low?.[si] !== undefined) ||
+                (key === 'targets' && p.target?.[si] !== undefined));
+            if (!has && !brings)
+                continue;
+            const base = has ? [...s[key]] : new Array(s.values.length).fill(gapFor(key));
+            for (const p of list) {
+                let v = undefined;
+                if (key === 'ohlc' && si === (ohlcOwner < 0 ? 0 : ohlcOwner))
+                    v = p.ohlc;
+                else if (key === 'volumes' && si === (ohlcOwner < 0 ? 0 : ohlcOwner))
+                    v = p.volume;
+                else if (key === 'rowIds')
+                    v = p.rowIds?.[si];
+                else if (key === 'upperValues')
+                    v = p.upper?.[si];
+                else if (key === 'lowerValues')
+                    v = p.lower?.[si];
+                else if (key === 'lowValues')
+                    v = p.low?.[si];
+                else if (key === 'targets')
+                    v = p.target?.[si];
+                base.push(v === undefined ? gapFor(key) : v);
+            }
+            ;
+            next[key] = base;
+        }
+        return next;
+    });
+    let out = { ...spec, categories, series };
+    for (const key of PER_CATEGORY_SPEC_KEYS) {
+        const arr = spec[key];
+        if (arr)
+            out[key] = [...arr, ...list.map(() => false)];
+    }
+    if (opts.window)
+        out = trim(out, opts.window);
+    return out;
+}
+/** The last `window` categories of a spec (the spec itself when it fits). */
+function trim(spec, window) {
+    const n = spec.categories.length;
+    if (window <= 0 || n <= window)
+        return spec;
+    const indices = Array.from({ length: window }, (_, k) => n - window + k);
+    return pickCategories(spec, indices);
+}

package/dist/chart-summary.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A chart in a sentence or two. `chartSummary` reads a spec the way a
+ * colleague would read the picture: which way each series goes and by how
+ * much, where it peaks, what the biggest slices are, whether two measures
+ * move together, how the last session closed. `SvChart` puts the result in
+ * the SVG's `aria-description`, the context menu copies it, and the AI
+ * "explain this chart" prompt is grounded on it, so the words a screen
+ * reader hears and the words a model reasons from are the same words.
+ *
+ * Pure and dependency-light (two small leaves: the number formatter and the
+ * trend primitives, kept apart from the engine's modules so the chunk a
+ * bundler shares between this lazy module and the base stays tiny), so it
+ * runs on the server and in a test, and the renderer loads it lazily.
+ */
+import type { ChartSpec } from './chart-types.js';
+/** What {@link chartSummary} takes. */
+export type ChartSummaryOptions = {
+    /** How numbers are written. Default: the spec's `valueFormat` / `locale` / `currency`. */
+    formatValue?: (v: number) => string;
+    /** How many series a cartesian chart describes before it says "and N more". Default 4. */
+    maxSeries?: number;
+};
+/**
+ * Describe a spec in plain words. Never throws: an empty spec of any type
+ * comes back as "No data." so a live region always has something to say.
+ */
+export declare function chartSummary(spec: ChartSpec, opts?: ChartSummaryOptions): string;