@rowsncolumns/charts 27.0.30

package/dist/esm/utils/stock.js

@@ -0,0 +1,123 @@
+/**
+ * Stock-chart shaping shared by chart renderers.
+ *
+ * Excel stock charts come in four variants distinguished by the ordered
+ * set of value series they carry:
+ *   - HLC   : High, Low, Close
+ *   - OHLC  : Open, High, Low, Close
+ *   - VHLC  : Volume, High, Low, Close
+ *   - VOHLC : Volume, Open, High, Low, Close
+ *
+ * We render stock as a "line-derived" chart: each price role becomes its
+ * own line series (volume is kept out of the price plot — it lives on a
+ * different scale and would flatten the price lines — and is instead
+ * surfaced via `toVolumeSeries` for renderers to draw as a column
+ * sub-pane on its own value axis). The candlestick transform is also
+ * provided for renderers that prefer a true OHLC body (echarts
+ * CandlestickChart / plotly candlestick).
+ */
+/**
+ * The ordered roles for each variant. Series are matched to roles by
+ * position — series[0] takes role[0], etc.
+ */
+export const STOCK_ROLES = {
+    HLC: ["high", "low", "close"],
+    OHLC: ["open", "high", "low", "close"],
+    VHLC: ["volume", "high", "low", "close"],
+    VOHLC: ["volume", "open", "high", "low", "close"],
+};
+const isFiniteNum = (v) => typeof v === "number" && Number.isFinite(v);
+const toNumber = (v) => isFiniteNum(v) ? v : null;
+/**
+ * Map positional series to their stock roles for a given variant.
+ * Series beyond the variant's role count are ignored.
+ */
+export const assignStockRoles = (seriesValues, variant = "HLC") => {
+    const roles = STOCK_ROLES[variant] ?? STOCK_ROLES.HLC;
+    const result = {};
+    for (let i = 0; i < roles.length; i++) {
+        const role = roles[i];
+        const values = seriesValues[i];
+        if (values)
+            result[role] = values.map(toNumber);
+    }
+    return result;
+};
+/**
+ * Line-derived view: emit one line series per PRICE role (open/high/low/
+ * close), preserving variant order and dropping volume. Each returned
+ * series carries a role-derived display name and its value vector.
+ */
+export const toLineSeries = (seriesValues, variant = "HLC") => {
+    const byRole = assignStockRoles(seriesValues, variant);
+    const order = ["open", "high", "low", "close"];
+    const labels = {
+        volume: "Volume",
+        open: "Open",
+        high: "High",
+        low: "Low",
+        close: "Close",
+    };
+    const out = [];
+    for (const role of order) {
+        const values = byRole[role];
+        if (values)
+            out.push({ role, name: labels[role], values });
+    }
+    return out;
+};
+/**
+ * Volume view: extract the volume series for the V-variants and flag
+ * each point as an up/down day so renderers can color the columns to
+ * match the price plot. Up/down follows convention: close vs open where
+ * the point carries an open, otherwise close vs the previous close. A
+ * point with nothing to compare against (e.g. the first) counts as up.
+ * Returns null for variants without a volume role (HLC / OHLC) or when
+ * the volume series is absent.
+ */
+export const toVolumeSeries = (seriesValues, variant = "HLC") => {
+    const byRole = assignStockRoles(seriesValues, variant);
+    const volume = byRole.volume;
+    if (!volume)
+        return null;
+    const open = byRole.open ?? [];
+    const close = byRole.close ?? [];
+    let prevClose = null;
+    const out = [];
+    for (let i = 0; i < volume.length; i++) {
+        const c = close[i] ?? null;
+        const o = open[i] ?? null;
+        let up = true;
+        if (o !== null && c !== null)
+            up = c >= o;
+        else if (prevClose !== null && c !== null)
+            up = c >= prevClose;
+        out.push({ value: volume[i] ?? null, up });
+        if (c !== null)
+            prevClose = c;
+    }
+    return out;
+};
+/**
+ * Candlestick view: produce [open, close, low, high] tuples (echarts'
+ * candlestick data order) per category index. When the variant has no
+ * `open` (HLC / VHLC) the close value is used as the open so the body
+ * collapses to a tick — matching how Excel renders HLC stock bars.
+ */
+export const toCandlestick = (seriesValues, variant = "HLC") => {
+    const byRole = assignStockRoles(seriesValues, variant);
+    const high = byRole.high ?? [];
+    const low = byRole.low ?? [];
+    const close = byRole.close ?? [];
+    const open = byRole.open ?? [];
+    const len = Math.max(high.length, low.length, close.length, open.length);
+    const result = [];
+    for (let i = 0; i < len; i++) {
+        const c = close[i] ?? 0;
+        const o = open[i] ?? c;
+        const l = low[i] ?? 0;
+        const h = high[i] ?? 0;
+        result.push([o, c, l, h]);
+    }
+    return result;
+};

package/dist/esm/utils/three-d.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 3-D / surface chart helpers.
+ *
+ * Excel's 3-D chart classes (Bar3D / Line3D / Pie3D / Area3D / Surface /
+ * Surface3D) degrade to a 2-D fallback `chartType` when imported, with the
+ * authored type preserved verbatim on the spec as `sourceChartType`. These
+ * helpers gate the renderer's 3-D pipeline off that token and shape the
+ * category/series value matrix into the data layouts the echarts-gl
+ * `bar3D` / `line3D` / `surface` series expect.
+ *
+ * Everything in this module is pure and independent of echarts-gl so it can
+ * be unit-tested without loading (or even installing a working) WebGL stack.
+ *
+ * Mapping decisions (see also basic-chart.tsx):
+ * - BAR_3D    -> `bar3D`   (x = category, y = series index, z = value)
+ * - LINE_3D   -> `line3D`  (one polyline per series at its series-index depth)
+ * - AREA_3D   -> `line3D`  (echarts-gl has no area3D; the polyline keeps the
+ *                          authored depth layout)
+ * - SURFACE / SURFACE_3D -> `surface` (values grid as z-heights over the
+ *                          categories × series plane)
+ * - PIE_3D    -> null      (echarts-gl has no pie3D; the renderer keeps the
+ *                          existing 2-D pie fallback rather than faking it)
+ */
+declare const THREE_D_TOKENS: readonly ["BAR_3D", "LINE_3D", "PIE_3D", "AREA_3D", "SURFACE", "SURFACE_3D"];
+export type ThreeDSourceType = (typeof THREE_D_TOKENS)[number];
+/** The echarts-gl series type a 3-D spec renders as. */
+export type ThreeDRenderKind = "bar3D" | "line3D" | "surface";
+/**
+ * Normalize a raw `sourceChartType` value to one of the known 3-D tokens.
+ * Matching is case-insensitive and whitespace-tolerant; anything else
+ * (including null/undefined) returns null.
+ */
+export declare const normalize3DSourceType: (sourceChartType?: string | null) => ThreeDSourceType | null;
+/**
+ * True when the spec was authored as one of the six 3-D / surface chart
+ * classes (its `sourceChartType` is one of the degraded-payload tokens).
+ * Note PIE_3D is included here even though it renders as the 2-D pie —
+ * use `resolve3DRenderKind` to decide whether the 3-D pipeline runs.
+ */
+export declare const is3DSpec: (spec: {
+    sourceChartType?: string | null;
+} | null | undefined) => boolean;
+/**
+ * Map a `sourceChartType` token to the echarts-gl series kind it renders
+ * as, or null when the 3-D pipeline should not run:
+ * - PIE_3D — echarts-gl has no pie3D, so the 2-D pie fallback stays.
+ * - AREA_3D — echarts-gl has no area3D; rendered as line3D.
+ * - non-3-D / unknown tokens.
+ */
+export declare const resolve3DRenderKind: (sourceChartType?: string | null) => ThreeDRenderKind | null;
+export type ThreeDSeriesInput = {
+    /** Resolved series display name (legend / y-axis label). */
+    name: string;
+    /** Sanitized numeric values, one per category (gaps allowed). */
+    values: (number | null | undefined)[];
+};
+/** [x = category index, y = series index, z = value] */
+export type ThreeDPoint = [number, number, number];
+/** Number of categories = the longest series' value count. */
+export declare const getCategoryCount: (series: ThreeDSeriesInput[]) => number;
+/**
+ * Shape series values into a single bar3D data array: one point per
+ * (category, series) cell — x is the category index, y the series index
+ * (depth row), z the value. Non-finite values are skipped (no bar).
+ */
+export declare const buildBar3DData: (series: ThreeDSeriesInput[]) => ThreeDPoint[];
+/**
+ * Shape series values into one line3D polyline per series, laid out at the
+ * series' index on the depth (y) axis. Non-finite values are skipped, so
+ * the polyline simply bridges gaps.
+ */
+export declare const buildLine3DSeries: (series: ThreeDSeriesInput[]) => {
+    name: string;
+    data: ThreeDPoint[];
+}[];
+/**
+ * Shape series values into a complete surface grid over the categories (x)
+ * × series (y) plane with the values as z-heights. Surfaces require a
+ * complete grid, so ragged series are padded and non-finite values are
+ * flattened to 0. Points are emitted row-major (per series row, categories
+ * in order), the layout echarts-gl's surface parser expects.
+ */
+export declare const buildSurfaceData: (series: ThreeDSeriesInput[]) => ThreeDPoint[];
+/**
+ * [min, max] of the z values, for the surface visualMap range. Returns
+ * [0, 1] for an empty grid and pads a flat grid (min === max) by 1 so the
+ * visualMap never has a zero-width range.
+ */
+export declare const getValueExtent: (points: ThreeDPoint[]) => [number, number];
+/**
+ * Default z-height color ramp for surface plots (the classic echarts-gl
+ * blue → yellow → red diverging ramp). Used via visualMap.inRange.
+ */
+export declare const SURFACE_COLOR_RAMP: readonly string[];
+export {};
+//# sourceMappingURL=three-d.d.ts.map

package/dist/esm/utils/three-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"three-d.d.ts","sourceRoot":"","sources":["../../../utils/three-d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,QAAA,MAAM,cAAc,8EAOV,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAI9D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,kBAAkB,MAAM,GAAG,IAAI,KAC9B,gBAAgB,GAAG,IAIrB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GACnB,MAAM;IAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,KAC3D,OAAgE,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,kBAAkB,MAAM,GAAG,IAAI,KAC9B,gBAAgB,GAAG,IAcrB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;CACvC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAKnD,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,GAAI,QAAQ,iBAAiB,EAAE,KAAG,MACO,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,iBAAiB,EAAE,KAAG,WAAW,EAUvE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,iBAAiB,EAAE,KAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,EASpC,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,iBAAiB,EAAE,KAC1B,WAAW,EAcb,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,WAAW,EAAE,KAAG,CAAC,MAAM,EAAE,MAAM,CASrE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAY/C,CAAC"}

package/dist/esm/utils/three-d.js

@@ -0,0 +1,162 @@
+/**
+ * 3-D / surface chart helpers.
+ *
+ * Excel's 3-D chart classes (Bar3D / Line3D / Pie3D / Area3D / Surface /
+ * Surface3D) degrade to a 2-D fallback `chartType` when imported, with the
+ * authored type preserved verbatim on the spec as `sourceChartType`. These
+ * helpers gate the renderer's 3-D pipeline off that token and shape the
+ * category/series value matrix into the data layouts the echarts-gl
+ * `bar3D` / `line3D` / `surface` series expect.
+ *
+ * Everything in this module is pure and independent of echarts-gl so it can
+ * be unit-tested without loading (or even installing a working) WebGL stack.
+ *
+ * Mapping decisions (see also basic-chart.tsx):
+ * - BAR_3D    -> `bar3D`   (x = category, y = series index, z = value)
+ * - LINE_3D   -> `line3D`  (one polyline per series at its series-index depth)
+ * - AREA_3D   -> `line3D`  (echarts-gl has no area3D; the polyline keeps the
+ *                          authored depth layout)
+ * - SURFACE / SURFACE_3D -> `surface` (values grid as z-heights over the
+ *                          categories × series plane)
+ * - PIE_3D    -> null      (echarts-gl has no pie3D; the renderer keeps the
+ *                          existing 2-D pie fallback rather than faking it)
+ */
+const THREE_D_TOKENS = [
+    "BAR_3D",
+    "LINE_3D",
+    "PIE_3D",
+    "AREA_3D",
+    "SURFACE",
+    "SURFACE_3D",
+];
+const THREE_D_TOKEN_SET = new Set(THREE_D_TOKENS);
+/**
+ * Normalize a raw `sourceChartType` value to one of the known 3-D tokens.
+ * Matching is case-insensitive and whitespace-tolerant; anything else
+ * (including null/undefined) returns null.
+ */
+export const normalize3DSourceType = (sourceChartType) => {
+    if (typeof sourceChartType !== "string")
+        return null;
+    const token = sourceChartType.trim().toUpperCase();
+    return THREE_D_TOKEN_SET.has(token) ? token : null;
+};
+/**
+ * True when the spec was authored as one of the six 3-D / surface chart
+ * classes (its `sourceChartType` is one of the degraded-payload tokens).
+ * Note PIE_3D is included here even though it renders as the 2-D pie —
+ * use `resolve3DRenderKind` to decide whether the 3-D pipeline runs.
+ */
+export const is3DSpec = (spec) => normalize3DSourceType(spec?.sourceChartType) !== null;
+/**
+ * Map a `sourceChartType` token to the echarts-gl series kind it renders
+ * as, or null when the 3-D pipeline should not run:
+ * - PIE_3D — echarts-gl has no pie3D, so the 2-D pie fallback stays.
+ * - AREA_3D — echarts-gl has no area3D; rendered as line3D.
+ * - non-3-D / unknown tokens.
+ */
+export const resolve3DRenderKind = (sourceChartType) => {
+    switch (normalize3DSourceType(sourceChartType)) {
+        case "BAR_3D":
+            return "bar3D";
+        case "LINE_3D":
+        case "AREA_3D":
+            return "line3D";
+        case "SURFACE":
+        case "SURFACE_3D":
+            return "surface";
+        default:
+            // PIE_3D and non-3-D tokens: keep the 2-D fallback rendering.
+            return null;
+    }
+};
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** Number of categories = the longest series' value count. */
+export const getCategoryCount = (series) => series.reduce((max, entry) => Math.max(max, entry.values.length), 0);
+/**
+ * Shape series values into a single bar3D data array: one point per
+ * (category, series) cell — x is the category index, y the series index
+ * (depth row), z the value. Non-finite values are skipped (no bar).
+ */
+export const buildBar3DData = (series) => {
+    const points = [];
+    series.forEach((entry, seriesIndex) => {
+        entry.values.forEach((value, categoryIndex) => {
+            if (isFiniteNumber(value)) {
+                points.push([categoryIndex, seriesIndex, value]);
+            }
+        });
+    });
+    return points;
+};
+/**
+ * Shape series values into one line3D polyline per series, laid out at the
+ * series' index on the depth (y) axis. Non-finite values are skipped, so
+ * the polyline simply bridges gaps.
+ */
+export const buildLine3DSeries = (series) => series.map((entry, seriesIndex) => {
+    const data = [];
+    entry.values.forEach((value, categoryIndex) => {
+        if (isFiniteNumber(value)) {
+            data.push([categoryIndex, seriesIndex, value]);
+        }
+    });
+    return { name: entry.name, data };
+});
+/**
+ * Shape series values into a complete surface grid over the categories (x)
+ * × series (y) plane with the values as z-heights. Surfaces require a
+ * complete grid, so ragged series are padded and non-finite values are
+ * flattened to 0. Points are emitted row-major (per series row, categories
+ * in order), the layout echarts-gl's surface parser expects.
+ */
+export const buildSurfaceData = (series) => {
+    const categoryCount = getCategoryCount(series);
+    const points = [];
+    series.forEach((entry, seriesIndex) => {
+        for (let categoryIndex = 0; categoryIndex < categoryCount; categoryIndex++) {
+            const value = entry.values[categoryIndex];
+            points.push([
+                categoryIndex,
+                seriesIndex,
+                isFiniteNumber(value) ? value : 0,
+            ]);
+        }
+    });
+    return points;
+};
+/**
+ * [min, max] of the z values, for the surface visualMap range. Returns
+ * [0, 1] for an empty grid and pads a flat grid (min === max) by 1 so the
+ * visualMap never has a zero-width range.
+ */
+export const getValueExtent = (points) => {
+    if (points.length === 0)
+        return [0, 1];
+    let min = points[0][2];
+    let max = points[0][2];
+    for (const [, , z] of points) {
+        if (z < min)
+            min = z;
+        if (z > max)
+            max = z;
+    }
+    return [min, max === min ? min + 1 : max];
+};
+/**
+ * Default z-height color ramp for surface plots (the classic echarts-gl
+ * blue → yellow → red diverging ramp). Used via visualMap.inRange.
+ */
+export const SURFACE_COLOR_RAMP = [
+    "#313695",
+    "#4575b4",
+    "#74add1",
+    "#abd9e9",
+    "#e0f3f8",
+    "#ffffbf",
+    "#fee090",
+    "#fdae61",
+    "#f46d43",
+    "#d73027",
+    "#a50026",
+];

package/dist/esm/utils/trendline.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Trendline regression shared by chart renderers.
+ *
+ * Excel/OOXML `<c:trendline>` supports linear / polynomial / exponential /
+ * logarithmic / power / moving-average fits. Neither echarts nor plotly
+ * compute these for us (echarts-stat is intentionally NOT a dependency),
+ * so the regressions are hand-rolled here as pure least-squares math and
+ * the renderers draw the returned points as an overlay line series.
+ *
+ * All fits operate on the index domain x = 0, 1, 2, … (one step per
+ * category) which matches how a category-axis chart positions points.
+ * The caller passes the raw y-values; gaps (null/NaN) are skipped during
+ * fitting but the fitted curve is still emitted for every x in range.
+ */
+export type TrendlineType = "linear" | "exp" | "log" | "poly" | "power" | "movingAvg";
+export type TrendlinePoint = {
+    x: number;
+    y: number;
+};
+export type TrendlineResult = {
+    /** Fitted points across the (optionally forecast-extended) domain. */
+    points: TrendlinePoint[];
+    /** Coefficient of determination (R²) of the fit, 0..1. null if N/A. */
+    rSquared: number | null;
+    /** Human-readable equation string, e.g. "y = 1.5x + 2". */
+    equation: string | null;
+};
+/**
+ * Compute a trendline for a series of y-values.
+ *
+ * @param values  Raw y-values; the category index is used as x.
+ * @param spec    Trendline parameters (type/order/period/forecast).
+ */
+export declare const computeTrendline: (values: (number | null | undefined)[], spec?: {
+    type?: TrendlineType | null;
+    order?: number | null;
+    period?: number | null;
+    forecastForward?: number | null;
+    forecastBackward?: number | null;
+}) => TrendlineResult | null;
+//# sourceMappingURL=trendline.d.ts.map

package/dist/esm/utils/trendline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trendline.d.ts","sourceRoot":"","sources":["../../../utils/trendline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,KAAK,GACL,KAAK,GACL,MAAM,GACN,OAAO,GACP,WAAW,CAAC;AAEhB,MAAM,MAAM,cAAc,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,MAAM,MAAM,eAAe,GAAG;IAC5B,sEAAsE;IACtE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AA+IF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACrC,OAAM;IACJ,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,KACL,eAAe,GAAG,IA6FpB,CAAC"}

package/dist/esm/utils/trendline.js

@@ -0,0 +1,257 @@
+/**
+ * Trendline regression shared by chart renderers.
+ *
+ * Excel/OOXML `<c:trendline>` supports linear / polynomial / exponential /
+ * logarithmic / power / moving-average fits. Neither echarts nor plotly
+ * compute these for us (echarts-stat is intentionally NOT a dependency),
+ * so the regressions are hand-rolled here as pure least-squares math and
+ * the renderers draw the returned points as an overlay line series.
+ *
+ * All fits operate on the index domain x = 0, 1, 2, … (one step per
+ * category) which matches how a category-axis chart positions points.
+ * The caller passes the raw y-values; gaps (null/NaN) are skipped during
+ * fitting but the fitted curve is still emitted for every x in range.
+ */
+const isFiniteNum = (v) => typeof v === "number" && Number.isFinite(v);
+/**
+ * Build (x, y) pairs from raw y-values using the category index as x.
+ * Non-finite y-values are dropped (they cannot be fitted).
+ */
+const toPairs = (values) => {
+    const pairs = [];
+    for (let i = 0; i < values.length; i++) {
+        const y = values[i];
+        if (isFiniteNum(y))
+            pairs.push({ x: i, y });
+    }
+    return pairs;
+};
+/** Compute R² between observed y and predicted f(x) over the fit pairs. */
+const rSquaredOf = (pairs, predict) => {
+    if (pairs.length < 2)
+        return null;
+    const meanY = pairs.reduce((s, p) => s + p.y, 0) / pairs.length;
+    let ssRes = 0;
+    let ssTot = 0;
+    for (const p of pairs) {
+        const yHat = predict(p.x);
+        if (!Number.isFinite(yHat))
+            return null;
+        ssRes += (p.y - yHat) ** 2;
+        ssTot += (p.y - meanY) ** 2;
+    }
+    if (ssTot === 0)
+        return null;
+    return 1 - ssRes / ssTot;
+};
+const round = (n, digits = 4) => {
+    const f = 10 ** digits;
+    return Math.round(n * f) / f;
+};
+/** Solve a small linear system A·x = b via Gaussian elimination. */
+const solveLinearSystem = (A, b) => {
+    const n = b.length;
+    // Augmented matrix
+    const m = A.map((row, i) => [...row, b[i]]);
+    for (let col = 0; col < n; col++) {
+        // Partial pivot
+        let pivot = col;
+        for (let r = col + 1; r < n; r++) {
+            if (Math.abs(m[r][col]) > Math.abs(m[pivot][col]))
+                pivot = r;
+        }
+        if (Math.abs(m[pivot][col]) < 1e-12)
+            return null;
+        [m[col], m[pivot]] = [m[pivot], m[col]];
+        // Eliminate
+        for (let r = 0; r < n; r++) {
+            if (r === col)
+                continue;
+            const factor = m[r][col] / m[col][col];
+            for (let c = col; c <= n; c++) {
+                m[r][c] -= factor * m[col][c];
+            }
+        }
+    }
+    return m.map((row, i) => row[n] / m[i][i]);
+};
+/** Linear least squares: y = m·x + b. */
+const fitLinear = (pairs) => {
+    const n = pairs.length;
+    if (n < 2)
+        return null;
+    let sx = 0;
+    let sy = 0;
+    let sxx = 0;
+    let sxy = 0;
+    for (const p of pairs) {
+        sx += p.x;
+        sy += p.y;
+        sxx += p.x * p.x;
+        sxy += p.x * p.y;
+    }
+    const denom = n * sxx - sx * sx;
+    if (denom === 0)
+        return null;
+    const m = (n * sxy - sx * sy) / denom;
+    const b = (sy - m * sx) / n;
+    return { m, b };
+};
+/**
+ * Polynomial least squares of the given order: y = c0 + c1·x + … + ck·x^k.
+ * Returns coefficients [c0, c1, …, ck] or null if singular.
+ */
+const fitPoly = (pairs, order) => {
+    const k = Math.max(2, Math.min(6, Math.floor(order)));
+    const n = k + 1;
+    if (pairs.length < n)
+        return null;
+    // Build normal equations: (X^T X) c = X^T y where X has columns x^0..x^k
+    const A = Array.from({ length: n }, () => new Array(n).fill(0));
+    const b = new Array(n).fill(0);
+    for (const p of pairs) {
+        const powers = [];
+        for (let i = 0; i < 2 * k + 1; i++) {
+            powers.push(i === 0 ? 1 : powers[i - 1] * p.x);
+        }
+        for (let row = 0; row < n; row++) {
+            for (let col = 0; col < n; col++) {
+                A[row][col] += powers[row + col];
+            }
+            b[row] += powers[row] * p.y;
+        }
+    }
+    return solveLinearSystem(A, b);
+};
+/** Exponential least squares: y = a·e^(b·x). Requires y > 0. */
+const fitExp = (pairs) => {
+    const positive = pairs.filter((p) => p.y > 0);
+    if (positive.length < 2)
+        return null;
+    // Linearize: ln(y) = ln(a) + b·x
+    const lin = fitLinear(positive.map((p) => ({ x: p.x, y: Math.log(p.y) })));
+    if (!lin)
+        return null;
+    return { a: Math.exp(lin.b), b: lin.m };
+};
+/** Logarithmic least squares: y = a + b·ln(x). Requires x > 0. */
+const fitLog = (pairs) => {
+    const positive = pairs.filter((p) => p.x > 0);
+    if (positive.length < 2)
+        return null;
+    const lin = fitLinear(positive.map((p) => ({ x: Math.log(p.x), y: p.y })));
+    if (!lin)
+        return null;
+    return { a: lin.b, b: lin.m };
+};
+/** Power least squares: y = a·x^b. Requires x > 0 and y > 0. */
+const fitPower = (pairs) => {
+    const positive = pairs.filter((p) => p.x > 0 && p.y > 0);
+    if (positive.length < 2)
+        return null;
+    const lin = fitLinear(positive.map((p) => ({ x: Math.log(p.x), y: Math.log(p.y) })));
+    if (!lin)
+        return null;
+    return { a: Math.exp(lin.b), b: lin.m };
+};
+/**
+ * Compute a trendline for a series of y-values.
+ *
+ * @param values  Raw y-values; the category index is used as x.
+ * @param spec    Trendline parameters (type/order/period/forecast).
+ */
+export const computeTrendline = (values, spec = {}) => {
+    const pairs = toPairs(values);
+    if (pairs.length < 2)
+        return null;
+    const type = spec.type ?? "linear";
+    const forward = Math.max(0, Math.floor(spec.forecastForward ?? 0));
+    const backward = Math.max(0, Math.floor(spec.forecastBackward ?? 0));
+    // Moving average is a smoothing of the observed values, not a fitted
+    // function, so it is handled separately and ignores forecasting.
+    if (type === "movingAvg") {
+        const period = Math.max(2, Math.floor(spec.period ?? 2));
+        const points = [];
+        for (let i = period - 1; i < values.length; i++) {
+            let sum = 0;
+            let count = 0;
+            for (let j = i - period + 1; j <= i; j++) {
+                const v = values[j];
+                if (isFiniteNum(v)) {
+                    sum += v;
+                    count++;
+                }
+            }
+            if (count > 0)
+                points.push({ x: i, y: sum / count });
+        }
+        return { points, rSquared: null, equation: null };
+    }
+    const lastX = values.length - 1;
+    const xStart = -backward;
+    const xEnd = lastX + forward;
+    const xs = [];
+    for (let x = xStart; x <= xEnd; x++)
+        xs.push(x);
+    let predict = null;
+    let equation = null;
+    switch (type) {
+        case "linear": {
+            const fit = fitLinear(pairs);
+            if (!fit)
+                return null;
+            predict = (x) => fit.m * x + fit.b;
+            equation = `y = ${round(fit.m)}x + ${round(fit.b)}`;
+            break;
+        }
+        case "poly": {
+            const coeffs = fitPoly(pairs, spec.order ?? 2);
+            if (!coeffs)
+                return null;
+            predict = (x) => coeffs.reduce((acc, c, i) => acc + c * x ** i, 0);
+            equation =
+                "y = " +
+                    coeffs
+                        .map((c, i) => (i === 0 ? `${round(c)}` : `${round(c)}x^${i}`))
+                        .join(" + ");
+            break;
+        }
+        case "exp": {
+            const fit = fitExp(pairs);
+            if (!fit)
+                return null;
+            predict = (x) => fit.a * Math.exp(fit.b * x);
+            equation = `y = ${round(fit.a)}e^(${round(fit.b)}x)`;
+            break;
+        }
+        case "log": {
+            const fit = fitLog(pairs);
+            if (!fit)
+                return null;
+            // ln(0) and ln(negative) are undefined; clamp x to >0 for the curve.
+            predict = (x) => fit.a + fit.b * Math.log(x <= 0 ? 1e-9 : x);
+            equation = `y = ${round(fit.a)} + ${round(fit.b)}ln(x)`;
+            break;
+        }
+        case "power": {
+            const fit = fitPower(pairs);
+            if (!fit)
+                return null;
+            predict = (x) => fit.a * (x <= 0 ? 0 : x ** fit.b);
+            equation = `y = ${round(fit.a)}x^${round(fit.b)}`;
+            break;
+        }
+        default:
+            return null;
+    }
+    const points = xs
+        .map((x) => ({ x, y: predict(x) }))
+        .filter((p) => Number.isFinite(p.y));
+    if (points.length < 2)
+        return null;
+    return {
+        points,
+        rSquared: rSquaredOf(pairs, predict),
+        equation,
+    };
+};