@svgrid/grid 3.0.2 → 3.0.4

package/dist/chart-summary.js

@@ -0,0 +1,205 @@
+import { formatChartValue } from './chart-format.js';
+import { linearTrend, pearson } from './chart-trend.js';
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+/** First and last finite value of a series with their indices, or null. */
+function ends(values) {
+    let i0 = -1;
+    let i1 = -1;
+    for (let i = 0; i < values.length; i += 1)
+        if (finite(values[i])) {
+            if (i0 < 0)
+                i0 = i;
+            i1 = i;
+        }
+    if (i0 < 0)
+        return null;
+    return { i0, v0: values[i0], i1, v1: values[i1] };
+}
+function extremes(values) {
+    let max = -Infinity, min = Infinity, iMax = -1, iMin = -1;
+    values.forEach((v, i) => {
+        if (!finite(v))
+            return;
+        if (v > max) {
+            max = v;
+            iMax = i;
+        }
+        if (v < min) {
+            min = v;
+            iMin = i;
+        }
+    });
+    return iMax < 0 ? null : { max, iMax, min, iMin };
+}
+const pct = (from, to) => {
+    if (from === 0)
+        return '';
+    const p = Math.abs(((to - from) / Math.abs(from)) * 100);
+    return `${p >= 10 ? Math.round(p) : Math.round(p * 10) / 10}%`;
+};
+function describeSeries(s, categories, fmt) {
+    const values = s.ohlc ? s.ohlc.map((b) => (b ? b.c : Number.NaN)) : s.values;
+    const e = ends(values);
+    if (!e)
+        return `${s.label} has no values.`;
+    const at = (i) => categories[i] ?? `#${i + 1}`;
+    if (e.i0 === e.i1)
+        return `${s.label} is ${fmt(e.v0)} at ${at(e.i0)}.`;
+    const slope = linearTrend(values);
+    const rise = slope[slope.length - 1] - slope[0];
+    const span = Math.abs(e.v1 - e.v0);
+    const scale = Math.max(Math.abs(e.v0), Math.abs(e.v1), 1e-9);
+    const flat = span / scale < 0.02 && Math.abs(rise) / scale < 0.05;
+    const dir = flat ? 'holds at about' : e.v1 > e.v0 ? 'rises' : 'falls';
+    const change = pct(e.v0, e.v1);
+    let out = flat
+        ? `${s.label} holds at about ${fmt(e.v1)} from ${at(e.i0)} to ${at(e.i1)}`
+        : `${s.label} ${dir}${change ? ` ${change}` : ''} from ${fmt(e.v0)} at ${at(e.i0)} to ${fmt(e.v1)} at ${at(e.i1)}`;
+    const x = extremes(values);
+    if (x && !flat) {
+        const peakInside = x.iMax !== e.i0 && x.iMax !== e.i1;
+        const troughInside = x.iMin !== e.i0 && x.iMin !== e.i1;
+        if (peakInside)
+            out += `, peaking at ${fmt(x.max)} at ${at(x.iMax)}`;
+        if (troughInside)
+            out += `, lowest at ${fmt(x.min)} at ${at(x.iMin)}`;
+    }
+    return out + '.';
+}
+function shares(labels, values, fmt, noun) {
+    const total = values.reduce((a, v) => a + (finite(v) ? Math.abs(v) : 0), 0);
+    if (!total)
+        return `No ${noun} has a value.`;
+    const ranked = labels.map((l, i) => ({ l, v: finite(values[i]) ? Math.abs(values[i]) : 0 })).sort((a, b) => b.v - a.v);
+    const top = ranked.slice(0, 3).map((r) => `${r.l} ${Math.round((r.v / total) * 100)}%`);
+    const rest = ranked.length > 3 ? `, ${ranked.length - 3} more share the rest` : '';
+    return `${labels.length} ${noun}s totalling ${fmt(total)}: ${top.join(', ')}${rest}.`;
+}
+/**
+ * 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 function chartSummary(spec, opts = {}) {
+    const fmt = opts.formatValue ?? ((v) => formatChartValue(v, spec.valueFormat, spec));
+    const max = opts.maxSeries ?? 4;
+    const cats = spec.categories ?? [];
+    const series = (spec.series ?? []).filter((s) => s.visible !== false);
+    const type = spec.type;
+    try {
+        if (type === 'pie' || type === 'radial-bar' || type === 'nightingale') {
+            const s = series[0];
+            if (!s || !s.values.some(finite))
+                return 'No data.';
+            return shares(cats, s.values, fmt, 'slice');
+        }
+        if (type === 'treemap' || type === 'sunburst') {
+            const root = spec.treemap ?? spec.tree;
+            const kids = root?.children ?? [];
+            if (!kids.length)
+                return 'No data.';
+            const total = (n) => n.value ?? (n.children ?? []).reduce((a, c) => a + total(c), 0);
+            return shares(kids.map((k) => k.name), kids.map((k) => total(k)), fmt, 'node');
+        }
+        if (type === 'gauge') {
+            if (!finite(spec.gaugeValue))
+                return 'No data.';
+            const lo = spec.gaugeMin ?? 0;
+            const hi = spec.gaugeMax ?? 100;
+            const share = hi > lo ? Math.round(((spec.gaugeValue - lo) / (hi - lo)) * 100) : 0;
+            const target = finite(spec.gaugeTarget) ? `, ${spec.gaugeValue >= spec.gaugeTarget ? 'above' : 'below'} the target of ${fmt(spec.gaugeTarget)}` : '';
+            return `${fmt(spec.gaugeValue)}${spec.gaugeUnit ? ' ' + spec.gaugeUnit : ''}, ${share}% of the way from ${fmt(lo)} to ${fmt(hi)}${target}.`;
+        }
+        if (type === 'scatter') {
+            const pts = series.flatMap((s) => s.points ?? []).filter((p) => finite(p.x) && finite(p.y));
+            if (!pts.length)
+                return 'No data.';
+            const r = pearson(pts.map((p) => p.x), pts.map((p) => p.y));
+            const strength = Math.abs(r) >= 0.7 ? 'strong' : Math.abs(r) >= 0.4 ? 'moderate' : Math.abs(r) >= 0.2 ? 'weak' : 'no';
+            const sign = r > 0 ? 'positive' : 'negative';
+            const rel = strength === 'no' ? 'no clear correlation' : `a ${strength} ${sign} correlation (r ${r.toFixed(2)})`;
+            return `${pts.length} points in ${series.length} series with ${rel} between x and y.`;
+        }
+        if (type === 'candlestick' || type === 'ohlc') {
+            const s = series.find((x) => x.ohlc) ?? series[0];
+            const bars = (s?.ohlc ?? []).filter((b) => !!b);
+            if (!s || !bars.length)
+                return 'No data.';
+            const last = bars[bars.length - 1];
+            const prev = bars.length > 1 ? bars[bars.length - 2] : null;
+            const hi = Math.max(...bars.map((b) => b.h));
+            const lo = Math.min(...bars.map((b) => b.l));
+            const move = prev ? `, ${last.c >= prev.c ? 'up' : 'down'} ${pct(prev.c, last.c)} on the session` : '';
+            return `${s.label}: last close ${fmt(last.c)}${move}, ranging ${fmt(lo)} to ${fmt(hi)} over ${bars.length} bars.`;
+        }
+        if (type === 'heatmap') {
+            let best = null;
+            for (const s of series)
+                s.values.forEach((v, i) => { if (finite(v) && (!best || v > best.v))
+                    best = { v, row: s.label, col: cats[i] ?? String(i) }; });
+            if (!best)
+                return 'No data.';
+            const b = best;
+            return `${series.length} rows by ${cats.length} columns; the highest cell is ${fmt(b.v)} at ${b.row} and ${b.col}.`;
+        }
+        if (type === 'calendar') {
+            const days = (spec.calendarValues ?? []).filter((d) => finite(d.value));
+            if (!days.length)
+                return 'No data.';
+            const top = days.reduce((a, d) => (d.value > a.value ? d : a), days[0]);
+            const total = days.reduce((a, d) => a + d.value, 0);
+            return `${days.length} days totalling ${fmt(total)}; the busiest is ${top.date} at ${fmt(top.value)}.`;
+        }
+        if (type === 'funnel') {
+            const s = series[0];
+            const vals = (s?.values ?? []).filter(finite);
+            if (!s || vals.length < 2)
+                return s && vals.length === 1 ? `${cats[0] ?? s.label}: ${fmt(vals[0])}.` : 'No data.';
+            const first = vals[0];
+            const last = vals[vals.length - 1];
+            const conv = first ? Math.round((last / first) * 100) : 0;
+            let worstDrop = 0;
+            let worstAt = '';
+            for (let i = 1; i < vals.length; i += 1) {
+                const drop = vals[i - 1] ? 1 - vals[i] / vals[i - 1] : 0;
+                if (drop > worstDrop) {
+                    worstDrop = drop;
+                    worstAt = cats[i] ?? `step ${i + 1}`;
+                }
+            }
+            return `${conv}% of ${fmt(first)} at ${cats[0] ?? 'the top'} reach ${cats[vals.length - 1] ?? 'the bottom'}${worstAt ? `; the biggest drop is into ${worstAt} (${Math.round(worstDrop * 100)}% lost)` : ''}.`;
+        }
+        if (type === 'boxplot') {
+            let widest = null;
+            for (const s of series)
+                for (const b of s.boxes ?? []) {
+                    if (!b)
+                        continue;
+                    const spread = b.q3 - b.q1;
+                    if (!widest || spread > widest.spread)
+                        widest = { label: s.label, spread };
+                }
+            if (!widest)
+                return 'No data.';
+            return `${series.length} distributions over ${cats.length} categories; ${widest.label} has the widest interquartile range at ${fmt(widest.spread)}.`;
+        }
+        if (type === 'sankey' || type === 'chord') {
+            const links = spec.sankeyLinks ?? [];
+            if (!links.length)
+                return 'No data.';
+            const total = links.reduce((a, l) => a + (finite(l.value) ? l.value : 0), 0);
+            const top = [...links].sort((a, b) => b.value - a.value)[0];
+            return `${links.length} flows totalling ${fmt(total)}; the largest is ${top.source} to ${top.target} at ${fmt(top.value)}.`;
+        }
+        // Cartesian families: one sentence per series, up to the cap.
+        const usable = series.filter((s) => s.values.some(finite) || s.ohlc);
+        if (!usable.length)
+            return 'No data.';
+        const shown = usable.slice(0, max);
+        const parts = shown.map((s) => describeSeries(s, cats, fmt));
+        const more = usable.length > shown.length ? ` And ${usable.length - shown.length} more series.` : '';
+        return `${parts.join(' ')}${more}`;
+    }
+    catch {
+        return 'No data.';
+    }
+}

package/dist/chart-sync.svelte.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared hover and zoom between charts in the same `syncGroup`.
+ *
+ * A registry of groups whose entries are `$state`, so every chart that reads
+ * its group's entry re-renders when another chart in the group writes to it. Each write
+ * carries the writer's token so a chart can ignore its own echoes.
+ */
+import type { ChartZoomWindow } from './chart-types.js';
+/** What one chart publishes for the others: the hovered category (its label,
+ *  index and, when the category parses as a date, its time) and the window. */
+export type ChartSyncState = {
+    hover: {
+        label: string;
+        index: number;
+        time: number | null;
+        from: symbol;
+    } | null;
+    zoom: {
+        window: ChartZoomWindow | null;
+        count: number;
+        from: symbol;
+        labels: [string, string] | null;
+    } | null;
+};
+/** The live entry for a group, created on first use. */
+export declare function syncGroupState(name: string): ChartSyncState;
+/** Publish a hover (or clear it with null). */
+export declare function publishSyncHover(name: string, hover: ChartSyncState['hover']): void;
+/** Publish a zoom window (null = the whole axis) with the axis length it
+ *  was made against and the category labels at its two ends, so a chart with
+ *  a different axis can map it by date. */
+export declare function publishSyncZoom(name: string, window: ChartZoomWindow | null, count: number, from: symbol, labels?: [string, string] | null): void;

package/dist/chart-sync.svelte.js

@@ -0,0 +1,23 @@
+// A plain map of reactive entries: looking a group up (which a chart does
+// inside a $derived) must not itself be a state mutation, so the map is not
+// reactive and each entry is.
+const groups = new Map();
+/** The live entry for a group, created on first use. */
+export function syncGroupState(name) {
+    const existing = groups.get(name);
+    if (existing)
+        return existing;
+    const fresh = $state({ hover: null, zoom: null });
+    groups.set(name, fresh);
+    return fresh;
+}
+/** Publish a hover (or clear it with null). */
+export function publishSyncHover(name, hover) {
+    syncGroupState(name).hover = hover;
+}
+/** Publish a zoom window (null = the whole axis) with the axis length it
+ *  was made against and the category labels at its two ends, so a chart with
+ *  a different axis can map it by date. */
+export function publishSyncZoom(name, window, count, from, labels = null) {
+    syncGroupState(name).zoom = { window, count, from, labels };
+}

package/dist/chart-table.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Chart spec -> grid table.
+ *
+ * The rows and columns a `ChartSpec` amounts to, in the shape `SvGrid` takes:
+ * one row per category with a column per series for the category types, one
+ * row per point for a scatter, per link for a sankey or chord, per leaf for
+ * a tree map or sunburst, per day for a calendar, and one row for a gauge.
+ * Number columns carry `cellDataType: 'number'` and the chart's value format,
+ * so a grid of the chart reads its numbers the way the chart does.
+ *
+ * This is the grid-shaped sibling of `chartSpecToCsv`: the CSV keeps its
+ * header contract byte for byte, this one adds types and formats and covers
+ * the shapes the CSV leaves out. A "Chart | Grid" switch on a chart is this
+ * function behind an `SvGrid`.
+ */
+import type { CellFormatConfig } from './core.js';
+import type { ChartSpec } from './chart-types.js';
+/** One column of a chart's table: what `SvGrid` needs to draw it. */
+export type ChartTableColumn = {
+    field: string;
+    header: string;
+    cellDataType?: 'number' | 'text' | 'date';
+    format?: CellFormatConfig;
+    width?: number;
+};
+/** A chart's data as a table: grid columns and plain row objects. */
+export type ChartTable = {
+    columns: ChartTableColumn[];
+    rows: Array<Record<string, unknown>>;
+};
+/**
+ * The rows and columns a chart spec amounts to. Never throws: a spec with
+ * nothing to tabulate comes back with no rows and no columns.
+ */
+export declare function chartSpecToTable(spec: ChartSpec): ChartTable;

package/dist/chart-table.js

@@ -0,0 +1,165 @@
+/** A finite number as itself, anything else as an empty cell. */
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+/** The cell format a chart value format maps to, for the number columns. */
+function formatOf(format, spec) {
+    const locales = typeof spec.locale === 'string' ? spec.locale : spec.locale ? [...spec.locale] : undefined;
+    if (format === 'currency')
+        return { type: 'currency', currency: spec.currency ?? 'USD', ...(locales ? { locales } : {}) };
+    if (format === 'percent')
+        return { type: 'percent', ...(locales ? { locales } : {}) };
+    if (format === 'number' || format === 'compact')
+        return { type: 'number', ...(locales ? { locales } : {}) };
+    return undefined;
+}
+/**
+ * The rows and columns a chart spec amounts to. Never throws: a spec with
+ * nothing to tabulate comes back with no rows and no columns.
+ */
+export function chartSpecToTable(spec) {
+    const fmt = formatOf(spec.valueFormat, spec);
+    // A series on the right axis reads in that axis's format: a margin of 0.29
+    // beside a revenue in dollars is "29%", not "$0.29".
+    const fmt2 = formatOf(spec.y2Axis?.format, spec);
+    const numCol = (field, header, right = false) => {
+        const f = right ? fmt2 : fmt;
+        return { field, header, cellDataType: 'number', ...(f ? { format: f } : {}) };
+    };
+    const textCol = (field, header) => ({ field, header });
+    const series = spec.series ?? [];
+    // Scatter and bubble: one row per point.
+    if (series.some((s) => s.points?.length)) {
+        const rows = [];
+        for (const s of series)
+            for (const p of s.points ?? [])
+                rows.push({ series: s.label, x: num(p.x), y: num(p.y), size: num(p.r), label: p.label ?? '' });
+        return { columns: [textCol('series', 'Series'), numCol('x', 'X'), numCol('y', 'Y'), numCol('size', 'Size'), textCol('label', 'Label')], rows };
+    }
+    // Sankey and chord: one row per link.
+    if (spec.sankeyLinks?.length) {
+        const names = new Map((spec.sankeyNodes ?? []).map((n) => [n.id, n.label ?? n.id]));
+        const rows = spec.sankeyLinks.map((l) => ({ source: names.get(l.source) ?? l.source, target: names.get(l.target) ?? l.target, value: num(l.value) }));
+        return { columns: [textCol('source', 'Source'), textCol('target', 'Target'), numCol('value', 'Value')], rows };
+    }
+    // Tree map and sunburst: one row per leaf, a column per level.
+    const tree = spec.tree ?? spec.treemap;
+    if (tree && (spec.type === 'treemap' || spec.type === 'sunburst' || !spec.categories?.length)) {
+        const rows = [];
+        let depth = 0;
+        const walk = (n, path) => {
+            if (n.children?.length) {
+                for (const c of n.children)
+                    walk(c, [...path, c.name]);
+                return;
+            }
+            depth = Math.max(depth, path.length);
+            const row = { value: num(n.value) };
+            path.forEach((seg, i) => (row[`level${i + 1}`] = seg));
+            rows.push(row);
+        };
+        walk(tree, []);
+        const columns = [];
+        for (let i = 1; i <= depth; i += 1)
+            columns.push(textCol(`level${i}`, depth === 1 ? 'Name' : `Level ${i}`));
+        columns.push(numCol('value', 'Value'));
+        return { columns, rows };
+    }
+    // Calendar: one row per day.
+    if (spec.calendarValues?.length) {
+        return {
+            columns: [{ field: 'date', header: 'Date', cellDataType: 'date' }, numCol('value', 'Value')],
+            rows: spec.calendarValues.map((d) => ({ date: d.date, value: num(d.value) })),
+        };
+    }
+    // Gauge: the one reading and its scale.
+    if (spec.type === 'gauge') {
+        return {
+            columns: [textCol('metric', 'Metric'), numCol('value', spec.gaugeUnit ? `Value (${spec.gaugeUnit})` : 'Value'), numCol('min', 'Min'), numCol('max', 'Max'), numCol('target', 'Target')],
+            rows: [{ metric: spec.title ?? spec.series[0]?.label ?? 'Value', value: num(spec.gaugeValue), min: num(spec.gaugeMin ?? 0), max: num(spec.gaugeMax ?? 100), target: num(spec.gaugeTarget) }],
+        };
+    }
+    // Everything else reads categories x series: one row per category, one
+    // column per number a series carries.
+    const cats = spec.categories ?? [];
+    if (!cats.length || !series.length)
+        return { columns: [], rows: [] };
+    const columns = [];
+    const groups = spec.categoryGroups;
+    if (groups?.length)
+        columns.push(textCol('group', 'Group'));
+    const edges = spec.binEdges;
+    const xType = spec.xAxis?.type ?? spec.xType;
+    const dated = xType === 'time' || xType === 'ordinal-time';
+    const catHeader = spec.xAxis?.title ?? spec.xAxisTitle ?? (dated ? 'Date' : 'Category');
+    if (edges && edges.length === cats.length + 1)
+        columns.push(numCol('from', 'From'), numCol('to', 'To'));
+    else
+        columns.push(dated ? { field: 'category', header: catHeader, cellDataType: 'date' } : textCol('category', catHeader));
+    const fields = [];
+    series.forEach((s, si) => {
+        const key = (suffix) => `s${si}${suffix}`;
+        const add = (suffix, header, pick) => {
+            columns.push(numCol(key(suffix), header, s.axis === 'right'));
+            fields.push({ field: key(suffix), pick });
+        };
+        if (s.ohlc) {
+            add('o', `${s.label} Open`, (i) => num(s.ohlc[i]?.o));
+            add('h', `${s.label} High`, (i) => num(s.ohlc[i]?.h));
+            add('l', `${s.label} Low`, (i) => num(s.ohlc[i]?.l));
+            add('c', `${s.label} Close`, (i) => num(s.ohlc[i]?.c));
+            if (s.volumes)
+                add('v', `${s.label} Volume`, (i) => num(s.volumes[i]));
+        }
+        else if (s.boxes) {
+            add('min', `${s.label} Min`, (i) => num(s.boxes[i]?.min));
+            add('q1', `${s.label} Q1`, (i) => num(s.boxes[i]?.q1));
+            add('med', `${s.label} Median`, (i) => num(s.boxes[i]?.median));
+            add('q3', `${s.label} Q3`, (i) => num(s.boxes[i]?.q3));
+            add('max', `${s.label} Max`, (i) => num(s.boxes[i]?.max));
+            columns.push(textCol(key('out'), `${s.label} Outliers`));
+            fields.push({ field: key('out'), pick: (i) => s.boxes[i]?.outliers?.join(' ') ?? '' });
+        }
+        else if (s.errors) {
+            add('', s.label, (i) => num(s.values[i]));
+            add('lo', `${s.label} Low`, (i) => {
+                const v = s.values[i], e = s.errors[i];
+                return e == null || !Number.isFinite(v) ? null : typeof e === 'number' ? v - Math.abs(e) : Math.min(e.lo, e.hi);
+            });
+            add('hi', `${s.label} High`, (i) => {
+                const v = s.values[i], e = s.errors[i];
+                return e == null || !Number.isFinite(v) ? null : typeof e === 'number' ? v + Math.abs(e) : Math.max(e.lo, e.hi);
+            });
+        }
+        else if (s.lowValues) {
+            add('lo', `${s.label} Low`, (i) => num(s.lowValues[i]));
+            add('hi', `${s.label} High`, (i) => num(s.values[i]));
+        }
+        else if (s.targets) {
+            add('', s.label, (i) => num(s.values[i]));
+            add('t', `${s.label} Target`, (i) => num(s.targets[i]));
+        }
+        else {
+            add('', s.label, (i) => num(s.values[i]));
+        }
+    });
+    // A category's group, from the spans.
+    const groupOf = [];
+    if (groups?.length)
+        for (const g of groups)
+            for (let k = 0; k < g.span; k += 1)
+                groupOf.push(g.label);
+    const rows = cats.map((cat, i) => {
+        const row = {};
+        if (groups?.length)
+            row.group = groupOf[i] ?? '';
+        if (edges && edges.length === cats.length + 1) {
+            row.from = num(edges[i]);
+            row.to = num(edges[i + 1]);
+        }
+        else
+            row.category = cat;
+        for (const f of fields)
+            row[f.field] = f.pick(i);
+        return row;
+    });
+    return { columns, rows };
+}

package/dist/chart-trend.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The two trend primitives a chart is read with: the least-squares line
+ * through a series and Pearson's correlation of two samples.
+ *
+ * A leaf of its own, and deliberately small, for the same reason as
+ * chart-format.ts: the engine and the lazily loaded summary
+ * (chart-summary.ts) share these two functions, a bundler hoists what the
+ * base chunk and a lazy chunk share into a third chunk, and hoisting all of
+ * chart-stats.ts for two functions cost the base bundle gzip locality for no
+ * new code. chart-stats.ts re-exports both.
+ */
+/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
+ *  Returns the fitted value at each x index, or NaN where the source value
+ *  was non-finite. */
+export declare function linearTrend(values: number[]): number[];
+/** Pearson's correlation coefficient of two equal-length samples, skipping
+ *  pairs where either side is non-finite; 0 when fewer than two pairs remain
+ *  or either side has no variance. */
+export declare function pearson(xs: ReadonlyArray<number>, ys: ReadonlyArray<number>): number;

package/dist/chart-trend.js

@@ -0,0 +1,61 @@
+/**
+ * The two trend primitives a chart is read with: the least-squares line
+ * through a series and Pearson's correlation of two samples.
+ *
+ * A leaf of its own, and deliberately small, for the same reason as
+ * chart-format.ts: the engine and the lazily loaded summary
+ * (chart-summary.ts) share these two functions, a bundler hoists what the
+ * base chunk and a lazy chunk share into a third chunk, and hoisting all of
+ * chart-stats.ts for two functions cost the base bundle gzip locality for no
+ * new code. chart-stats.ts re-exports both.
+ */
+/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
+ *  Returns the fitted value at each x index, or NaN where the source value
+ *  was non-finite. */
+export function linearTrend(values) {
+    let n = 0, sumX = 0, sumY = 0, sumXX = 0, sumXY = 0;
+    for (let i = 0; i < values.length; i += 1) {
+        const y = values[i];
+        if (!Number.isFinite(y))
+            continue;
+        n += 1;
+        sumX += i;
+        sumY += y;
+        sumXX += i * i;
+        sumXY += i * y;
+    }
+    if (n < 2)
+        return values.map(() => NaN);
+    const denom = n * sumXX - sumX * sumX;
+    if (denom === 0)
+        return values.map(() => sumY / n);
+    const slope = (n * sumXY - sumX * sumY) / denom;
+    const intercept = (sumY - slope * sumX) / n;
+    return values.map((_, i) => slope * i + intercept);
+}
+/** Pearson's correlation coefficient of two equal-length samples, skipping
+ *  pairs where either side is non-finite; 0 when fewer than two pairs remain
+ *  or either side has no variance. */
+export function pearson(xs, ys) {
+    let n = 0, sx = 0, sy = 0;
+    const len = Math.min(xs.length, ys.length);
+    for (let i = 0; i < len; i += 1)
+        if (Number.isFinite(xs[i]) && Number.isFinite(ys[i])) {
+            n += 1;
+            sx += xs[i];
+            sy += ys[i];
+        }
+    if (n < 2)
+        return 0;
+    const mx = sx / n, my = sy / n;
+    let sxy = 0, sxx = 0, syy = 0;
+    for (let i = 0; i < len; i += 1) {
+        if (!Number.isFinite(xs[i]) || !Number.isFinite(ys[i]))
+            continue;
+        const dx = xs[i] - mx, dy = ys[i] - my;
+        sxy += dx * dy;
+        sxx += dx * dx;
+        syy += dy * dy;
+    }
+    return sxx === 0 || syy === 0 ? 0 : sxy / Math.sqrt(sxx * syy);
+}