@rowsncolumns/charts 27.0.30

package/dist/esm/utils/bubble.js

@@ -0,0 +1,122 @@
+export const toLabelString = (value) => value === null || value === undefined ? "" : `${value}`;
+export const toNumericValue = (value) => {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    if (typeof value === "boolean") {
+        return value ? 1 : 0;
+    }
+    return null;
+};
+export const createBubbleSizeScale = (values) => {
+    const valid = values.filter((value) => Number.isFinite(value));
+    if (valid.length === 0) {
+        return () => 24;
+    }
+    const min = Math.min(...valid);
+    const max = Math.max(...valid);
+    const range = max - min || 1;
+    return (value) => {
+        if (!Number.isFinite(value)) {
+            return 24;
+        }
+        const ratio = (value - min) / range;
+        return 12 + ratio * 42;
+    };
+};
+/**
+ * Build the X-coordinate index for a series. Numeric values map to
+ * their own coordinate; string values become categorical (deduped into
+ * the shared `categories` array with stable indices so multiple series
+ * agree on which integer maps to which label).
+ */
+const buildXCoordinates = (xValues, categories, categoryIndex) => {
+    const xCoordinates = [];
+    xValues.forEach((value, idx) => {
+        const numeric = toNumericValue(value);
+        if (numeric !== null) {
+            xCoordinates[idx] = { coordinate: numeric };
+            return;
+        }
+        const label = toLabelString(value);
+        if (!label) {
+            xCoordinates[idx] = { coordinate: idx };
+            return;
+        }
+        if (!categoryIndex.has(label)) {
+            categoryIndex.set(label, categories.length);
+            categories.push(label);
+        }
+        xCoordinates[idx] = {
+            coordinate: categoryIndex.get(label) ?? idx,
+            label,
+        };
+    });
+    return xCoordinates;
+};
+export const prepareBubbleSeriesData = ({ xValues, labelValues, sizeValues, series, }) => {
+    const normalizedLabels = labelValues.map(toLabelString);
+    const sharedNormalizedSizeValues = sizeValues.map((value) => value === undefined || value === null ? null : toNumericValue(value));
+    const categories = [];
+    const categoryIndex = new Map();
+    // Shared X coordinates — used when a series doesn't carry its own
+    // `xValues`. Categories built here populate the shared category
+    // table so per-series string-X series stay in sync.
+    const sharedXCoordinates = buildXCoordinates(xValues, categories, categoryIndex);
+    const allSizeValues = [];
+    const preparedSeries = series.map((serie, seriesIndex) => {
+        // Per-series X values (scatter always; bubble may) override the
+        // shared X for this series only. Categories are still pooled.
+        const seriesXCoordinates = serie.xValues
+            ? buildXCoordinates(serie.xValues, categories, categoryIndex)
+            : sharedXCoordinates;
+        const seriesXValues = serie.xValues ?? xValues;
+        // Per-series sizes — bubble charts can carry one bubbleSize per
+        // series. Falls back to the shared array.
+        const seriesNormalizedSizeValues = serie.sizeValues
+            ? serie.sizeValues.map((value) => value === undefined || value === null
+                ? null
+                : toNumericValue(value))
+            : sharedNormalizedSizeValues;
+        const points = [];
+        const yValues = serie.values.map((value) => toNumericValue(value));
+        const pointCount = Math.max(yValues.length, seriesXCoordinates.length);
+        for (let i = 0; i < pointCount; i++) {
+            const y = yValues[i];
+            const coordinate = seriesXCoordinates[i];
+            if (y === null || y === undefined || !coordinate) {
+                continue;
+            }
+            const sizeSource = seriesNormalizedSizeValues[i];
+            const resolvedSize = typeof sizeSource === "number" && Number.isFinite(sizeSource)
+                ? sizeSource
+                : y;
+            const sizeValue = typeof resolvedSize === "number" && Number.isFinite(resolvedSize)
+                ? resolvedSize
+                : 0;
+            allSizeValues.push(sizeValue);
+            const label = normalizedLabels[i] ?? "";
+            const coordinateLabel = categories.length > 0
+                ? coordinate.label ?? toLabelString(seriesXValues[i])
+                : undefined;
+            points.push({
+                value: [coordinate.coordinate, y, sizeValue],
+                name: label,
+                xLabel: coordinateLabel,
+            });
+        }
+        const name = serie.name && serie.name.trim()
+            ? serie.name
+            : `Series ${seriesIndex + 1}`;
+        return { name, points };
+    });
+    return {
+        categories,
+        series: preparedSeries,
+        sizeValues: allSizeValues,
+    };
+};

package/dist/esm/utils/chart-spec-utils.d.ts

@@ -0,0 +1,67 @@
+import type { BasicChartSpec, ChartData, EmbeddedChart, SheetRange, TreemapChart } from "@rowsncolumns/spreadsheet";
+type ChartType = EmbeddedChart["spec"]["chartType"];
+type ChartCategory = "basic" | "bubble" | "hierarchy";
+type ChartSpec = EmbeddedChart["spec"];
+export declare const BASIC_CHART_TYPES: Set<"bar" | "column" | "line" | "pie" | "area" | "doughnut" | "radar" | "stock" | "histogram" | "boxplot" | "waterfall" | "funnel" | "combo" | "regionMap" | "treemap" | "sunburst" | "bubble" | "scatter">;
+export declare const BUBBLE_CHART_TYPES: Set<"bar" | "column" | "line" | "pie" | "area" | "doughnut" | "radar" | "stock" | "histogram" | "boxplot" | "waterfall" | "funnel" | "combo" | "regionMap" | "treemap" | "sunburst" | "bubble" | "scatter">;
+export declare const HIERARCHY_CHART_TYPES: Set<"bar" | "column" | "line" | "pie" | "area" | "doughnut" | "radar" | "stock" | "histogram" | "boxplot" | "waterfall" | "funnel" | "combo" | "regionMap" | "treemap" | "sunburst" | "bubble" | "scatter">;
+/**
+ * Returns the category of a chart type.
+ */
+export declare const getChartCategory: (chartType: ChartType) => ChartCategory;
+/**
+ * Type guards for chart specs
+ */
+export declare const isBasicChartSpec: (spec: ChartSpec) => spec is ChartSpec & BasicChartSpec;
+export type BubbleChartEditorSpec = {
+    chartType: "bubble" | "scatter";
+    domains: ChartData[];
+    series: ChartData[];
+    bubbleLabels?: ChartData[];
+    bubbleSizes?: ChartData[];
+    useFirstRowAsHeaders?: boolean;
+    /** Scatter only — line/marker mix (mirrors OOXML `<c:scatterStyle>`). */
+    scatterStyle?: "line" | "marker" | "lineMarker" | "smoothMarker" | "smooth" | "none" | null;
+};
+export declare const isBubbleChartSpec: (spec: ChartSpec) => spec is ChartSpec & BubbleChartEditorSpec;
+export type HierarchyChartSpec = TreemapChart & {
+    useFirstRowAsHeaders?: boolean;
+};
+export declare const isHierarchyChartSpec: (spec: ChartSpec) => spec is ChartSpec & HierarchyChartSpec;
+/**
+ * Returns the default spec for a given chart type.
+ */
+export declare const getDefaultChartTypeSpec: (chartType: ChartType) => Partial<ChartSpec>;
+/**
+ * Returns the properties that should be removed when transitioning
+ * from one chart type to another.
+ */
+export declare const getPropertiesToRemove: (fromType: ChartType, toType: ChartType) => string[];
+/**
+ * Checks if chart data array is empty or contains only placeholder entries.
+ */
+export declare const isPlaceholderChartData: (data?: ChartData[]) => boolean;
+/**
+ * Merges chart data arrays, preserving current data if incoming is placeholder.
+ */
+export declare const mergeChartDataArray: (current?: ChartData[], incoming?: ChartData[]) => ChartData[];
+/**
+ * Merges chart specs, handling chart type transitions by clearing
+ * type-specific properties when the chart type changes.
+ * Also handles special merging for chart data arrays.
+ */
+export declare const mergeChartSpec: (existingSpec: ChartSpec, incomingSpec: Partial<ChartSpec>) => ChartSpec;
+/**
+ * Extracts all SheetRange objects from a ChartSpec.
+ * Useful for subscribing to data changes across all chart data sources.
+ */
+export declare const getChartDataRanges: (spec: ChartSpec) => SheetRange[];
+/**
+ * Coerce an `onRequestCalculate` result into a chart label. Formula
+ * errors (#NAME?, #REF!, …) resolve as FormulaError values, and array
+ * previews aren't printable — both blank the label instead of
+ * rendering an error object in the legend.
+ */
+export declare const coerceCalculatedLabel: (result: unknown) => string;
+export {};
+//# sourceMappingURL=chart-spec-utils.d.ts.map

package/dist/esm/utils/chart-spec-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-spec-utils.d.ts","sourceRoot":"","sources":["../../../utils/chart-spec-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,UAAU,EACV,YAAY,EACb,MAAM,2BAA2B,CAAC;AAEnC,KAAK,SAAS,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC;AACpD,KAAK,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AACtD,KAAK,SAAS,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAEvC,eAAO,MAAM,iBAAiB,6MAe5B,CAAC;AAEH,eAAO,MAAM,kBAAkB,6MAA4C,CAAC;AAE5E,eAAO,MAAM,qBAAqB,6MAGhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,SAAS,KAAG,aAKvD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,SAAS,KACd,IAAI,IAAI,SAAS,GAAG,cAAuD,CAAC;AAE/E,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,EAAE,QAAQ,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,yEAAyE;IACzE,YAAY,CAAC,EACT,MAAM,GACN,QAAQ,GACR,YAAY,GACZ,cAAc,GACd,QAAQ,GACR,MAAM,GACN,IAAI,CAAC;CACV,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,MAAM,SAAS,KACd,IAAI,IAAI,SAAS,GAAG,qBACiB,CAAC;AAEzC,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG;IAC9C,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,MAAM,SAAS,KACd,IAAI,IAAI,SAAS,GAAG,kBACoB,CAAC;AAwC5C;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAClC,WAAW,SAAS,KACnB,OAAO,CAAC,SAAS,CAEnB,CAAC;AA2DF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAChC,UAAU,SAAS,EACnB,QAAQ,SAAS,KAChB,MAAM,EAoBR,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,SAAS,EAAE,KAAG,OAM3D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,SAAS,EAAE,EACrB,WAAW,SAAS,EAAE,KACrB,SAAS,EAKX,CAAC;AA+BF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,cAAc,SAAS,EACvB,cAAc,OAAO,CAAC,SAAS,CAAC,KAC/B,SAmDF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,SAAS,KAAG,UAAU,EAsB9D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,OAAO,KAAG,MAQvD,CAAC"}

package/dist/esm/utils/chart-spec-utils.js

@@ -0,0 +1,270 @@
+export const BASIC_CHART_TYPES = new Set([
+    "bar",
+    "column",
+    "line",
+    "pie",
+    "area",
+    "doughnut",
+    "radar",
+    "stock",
+    "histogram",
+    "boxplot",
+    "waterfall",
+    "funnel",
+    "combo",
+    "regionMap",
+]);
+export const BUBBLE_CHART_TYPES = new Set(["bubble", "scatter"]);
+export const HIERARCHY_CHART_TYPES = new Set([
+    "treemap",
+    "sunburst",
+]);
+/**
+ * Returns the category of a chart type.
+ */
+export const getChartCategory = (chartType) => {
+    if (BASIC_CHART_TYPES.has(chartType))
+        return "basic";
+    if (BUBBLE_CHART_TYPES.has(chartType))
+        return "bubble";
+    if (HIERARCHY_CHART_TYPES.has(chartType))
+        return "hierarchy";
+    return "basic";
+};
+/**
+ * Type guards for chart specs
+ */
+export const isBasicChartSpec = (spec) => BASIC_CHART_TYPES.has(spec.chartType);
+export const isBubbleChartSpec = (spec) => BUBBLE_CHART_TYPES.has(spec.chartType);
+export const isHierarchyChartSpec = (spec) => HIERARCHY_CHART_TYPES.has(spec.chartType);
+/**
+ * Default specs for each chart type.
+ * These provide sensible defaults when creating new charts.
+ */
+const DEFAULT_CHART_TYPE_SPECS = {
+    line: { chartType: "line", smooth: false },
+    bar: { chartType: "bar", stackedType: "UNSTACKED" },
+    column: { chartType: "column", stackedType: "UNSTACKED" },
+    pie: { chartType: "pie", stackedType: "UNSTACKED", radius: [0, "75%"] },
+    area: { chartType: "area" },
+    doughnut: {
+        chartType: "doughnut",
+        stackedType: "UNSTACKED",
+        doughnutHoleSize: 0.5,
+    },
+    radar: { chartType: "radar" },
+    stock: { chartType: "stock" },
+    histogram: { chartType: "histogram" },
+    boxplot: { chartType: "boxplot" },
+    waterfall: { chartType: "waterfall" },
+    funnel: { chartType: "funnel" },
+    combo: { chartType: "combo" },
+    regionMap: { chartType: "regionMap", geoScope: "world" },
+    bubble: {
+        chartType: "bubble",
+        bubbleLabels: [{ sources: [] }],
+        useFirstRowAsHeaders: true,
+    },
+    scatter: {
+        chartType: "scatter",
+        bubbleLabels: [{ sources: [] }],
+        useFirstRowAsHeaders: true,
+    },
+    treemap: { chartType: "treemap", useFirstRowAsHeaders: true },
+    sunburst: { chartType: "sunburst", useFirstRowAsHeaders: true },
+};
+/**
+ * Returns the default spec for a given chart type.
+ */
+export const getDefaultChartTypeSpec = (chartType) => {
+    return DEFAULT_CHART_TYPE_SPECS[chartType] ?? { chartType };
+};
+/**
+ * Properties specific to individual chart types within the basic category.
+ * These should be cleared when switching between chart types within basic charts.
+ */
+const BASIC_CHART_TYPE_PROPERTIES = {
+    line: ["smooth"],
+    // `doughnutHoleSize` is deliberately NOT cleared when leaving pie so
+    // upgrading a legacy pie-based doughnut (pie + doughnutHoleSize) to
+    // the first-class doughnut token keeps the authored hole size.
+    pie: [
+        "radius",
+        // Of-pie composite fields (pie-of-pie / bar-of-pie) — meaningless
+        // on any other chart type, so drop them on transition.
+        "sourceChartType",
+        "ofPieType",
+        "splitType",
+        "splitPos",
+        "secondPieSize",
+    ],
+    doughnut: ["doughnutHoleSize"],
+    waterfall: ["totalIndices"],
+    boxplot: ["quartileMethod", "showOutliers", "showMeanMarker"],
+    // Region map (filled map / choropleth) — the geo scope and the
+    // authored-class marker are meaningless on any other chart type.
+    regionMap: ["sourceChartType", "geoScope"],
+};
+/**
+ * Properties specific to each chart category.
+ * These should be cleared when switching between categories.
+ */
+const CATEGORY_SPECIFIC_PROPERTIES = {
+    basic: [
+        "smooth",
+        "radius",
+        "stackedType",
+        "doughnutHoleSize",
+        "totalIndices",
+        "sourceChartType",
+        "ofPieType",
+        "splitType",
+        "splitPos",
+        "secondPieSize",
+        "quartileMethod",
+        "showOutliers",
+        "showMeanMarker",
+        "geoScope",
+    ],
+    bubble: [
+        "bubbleLabels",
+        "bubbleSizes",
+        "useFirstRowAsHeaders",
+        "scatterStyle",
+    ],
+    hierarchy: ["labels", "parentLabels", "sizeData", "useFirstRowAsHeaders"],
+};
+/**
+ * Returns the properties that should be removed when transitioning
+ * from one chart type to another.
+ */
+export const getPropertiesToRemove = (fromType, toType) => {
+    // No changes needed if same chart type
+    if (fromType === toType) {
+        return [];
+    }
+    const fromCategory = getChartCategory(fromType);
+    const toCategory = getChartCategory(toType);
+    if (fromCategory !== toCategory) {
+        // Switching between categories - remove all category-specific properties
+        return CATEGORY_SPECIFIC_PROPERTIES[fromCategory];
+    }
+    // Switching within basic charts - only remove chart-specific properties
+    if (fromCategory === "basic") {
+        return BASIC_CHART_TYPE_PROPERTIES[fromType] ?? [];
+    }
+    return [];
+};
+/**
+ * Checks if chart data array is empty or contains only placeholder entries.
+ */
+export const isPlaceholderChartData = (data) => {
+    if (!data || data.length === 0)
+        return true;
+    return data.every((entry) => {
+        const sources = entry?.sources ?? [];
+        return sources.length === 0 || sources.every((source) => !source);
+    });
+};
+/**
+ * Merges chart data arrays, preserving current data if incoming is placeholder.
+ */
+export const mergeChartDataArray = (current, incoming) => {
+    if (!incoming || isPlaceholderChartData(incoming)) {
+        return current ?? incoming ?? [];
+    }
+    return incoming;
+};
+/**
+ * Chart data fields specific to each category.
+ */
+const CATEGORY_DATA_FIELDS = {
+    basic: ["domains", "series"],
+    bubble: ["domains", "series", "bubbleLabels", "bubbleSizes"],
+    hierarchy: ["labels", "parentLabels", "sizeData"],
+};
+/**
+ * Merges chart specs, handling chart type transitions by clearing
+ * type-specific properties when the chart type changes.
+ * Also handles special merging for chart data arrays.
+ */
+export const mergeChartSpec = (existingSpec, incomingSpec) => {
+    const incomingChartType = incomingSpec.chartType;
+    const existingChartType = existingSpec.chartType;
+    const existingCategory = getChartCategory(existingChartType);
+    const targetCategory = incomingChartType
+        ? getChartCategory(incomingChartType)
+        : existingCategory;
+    const isCategoryChange = incomingChartType && existingCategory !== targetCategory;
+    // Start with a copy of existing spec
+    const merged = { ...existingSpec };
+    // Handle chart type changes - remove type-specific properties
+    if (incomingChartType && incomingChartType !== existingChartType) {
+        const propertiesToRemove = getPropertiesToRemove(existingChartType, incomingChartType);
+        for (const prop of propertiesToRemove) {
+            delete merged[prop];
+        }
+    }
+    // When switching categories, remove data fields from old category
+    if (isCategoryChange) {
+        const oldCategoryDataFields = CATEGORY_DATA_FIELDS[existingCategory];
+        for (const field of oldCategoryDataFields) {
+            delete merged[field];
+        }
+    }
+    // Apply incoming spec properties
+    Object.assign(merged, incomingSpec);
+    // Handle chart data array merging - preserve existing if incoming is placeholder
+    // Only merge data fields that belong to the target category
+    const existingWithData = existingSpec;
+    const incomingWithData = incomingSpec;
+    const targetDataFields = CATEGORY_DATA_FIELDS[targetCategory];
+    for (const field of targetDataFields) {
+        const existingData = isCategoryChange ? undefined : existingWithData[field];
+        const incomingData = incomingWithData[field];
+        if (existingData !== undefined || incomingData !== undefined) {
+            merged[field] = mergeChartDataArray(existingData, incomingData);
+        }
+    }
+    return merged;
+};
+/**
+ * Extracts all SheetRange objects from a ChartSpec.
+ * Useful for subscribing to data changes across all chart data sources.
+ */
+export const getChartDataRanges = (spec) => {
+    const ranges = [];
+    const category = getChartCategory(spec.chartType);
+    const dataFields = CATEGORY_DATA_FIELDS[category];
+    const specWithData = spec;
+    for (const field of dataFields) {
+        const chartDataArray = specWithData[field];
+        if (chartDataArray) {
+            for (const chartData of chartDataArray) {
+                if (chartData?.sources) {
+                    for (const source of chartData.sources) {
+                        if (source) {
+                            ranges.push(source);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return ranges;
+};
+/**
+ * Coerce an `onRequestCalculate` result into a chart label. Formula
+ * errors (#NAME?, #REF!, …) resolve as FormulaError values, and array
+ * previews aren't printable — both blank the label instead of
+ * rendering an error object in the legend.
+ */
+export const coerceCalculatedLabel = (result) => {
+    if (typeof result === "string") {
+        return result;
+    }
+    if (typeof result === "number" || typeof result === "boolean") {
+        return String(result);
+    }
+    return "";
+};

package/dist/esm/utils/echarts-gl-loader.d.ts

@@ -0,0 +1,11 @@
+export type EchartsGlLoadState = "unloaded" | "loading" | "ready" | "failed";
+export declare const getEchartsGlState: () => EchartsGlLoadState;
+/**
+ * Kick off (or join) the echarts-gl dynamic import and register the 3-D
+ * charts/components the renderer uses. Resolves true when 3-D rendering is
+ * available, false when the import failed (renderer keeps the 2-D fallback).
+ */
+export declare const loadEchartsGl: () => Promise<boolean>;
+/** Test hook — resets the module-level load state. */
+export declare const __resetEchartsGlLoaderForTests: () => void;
+//# sourceMappingURL=echarts-gl-loader.d.ts.map

package/dist/esm/utils/echarts-gl-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echarts-gl-loader.d.ts","sourceRoot":"","sources":["../../../utils/echarts-gl-loader.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAK7E,eAAO,MAAM,iBAAiB,QAAO,kBAA2B,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,aAAa,QAAO,OAAO,CAAC,OAAO,CAyB/C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,8BAA8B,QAAO,IAGjD,CAAC"}

package/dist/esm/utils/echarts-gl-loader.js

@@ -0,0 +1,51 @@
+/**
+ * Lazy loader for echarts-gl.
+ *
+ * echarts-gl (plus its claygl dependency) is a large chunk that only 3-D /
+ * surface specs need, so it is NEVER imported eagerly — the renderer calls
+ * `loadEchartsGl()` the first time a 3-D spec is actually about to render,
+ * draws the 2-D fallback immediately, and upgrades to 3-D when the module
+ * resolves. A failed import latches the "failed" state so the renderer
+ * keeps the 2-D fallback without retrying on every update.
+ */
+import { VisualMapComponent } from "echarts/components";
+import * as echarts from "echarts/core";
+let state = "unloaded";
+let loadPromise = null;
+export const getEchartsGlState = () => state;
+/**
+ * Kick off (or join) the echarts-gl dynamic import and register the 3-D
+ * charts/components the renderer uses. Resolves true when 3-D rendering is
+ * available, false when the import failed (renderer keeps the 2-D fallback).
+ */
+export const loadEchartsGl = () => {
+    if (!loadPromise) {
+        state = "loading";
+        loadPromise = Promise.all([
+            import("echarts-gl/charts"),
+            import("echarts-gl/components"),
+        ])
+            .then(([glCharts, glComponents]) => {
+            echarts.use([
+                glCharts.Bar3DChart,
+                glCharts.Line3DChart,
+                glCharts.SurfaceChart,
+                glComponents.Grid3DComponent,
+                // Surface plots color their z-heights through a visualMap ramp.
+                VisualMapComponent,
+            ]);
+            state = "ready";
+            return true;
+        })
+            .catch(() => {
+            state = "failed";
+            return false;
+        });
+    }
+    return loadPromise;
+};
+/** Test hook — resets the module-level load state. */
+export const __resetEchartsGlLoaderForTests = () => {
+    state = "unloaded";
+    loadPromise = null;
+};

package/dist/esm/utils/error-bars.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Error-bar magnitudes shared by chart renderers.
+ *
+ * Mirrors OOXML `<c:errBars>`. Given a series' numeric values and an
+ * error-bar spec, this returns the +/- magnitude for each data point so
+ * the renderer can draw whiskers. Both echarts (via a custom series) and
+ * plotly (via native `error_y`/`error_x`) consume the same arrays.
+ *
+ * Supported valueTypes: fixedVal, percentage, stdDev, stdErr, custom.
+ * `custom` (Excel `errValType="cust"`) reads per-point plus/minus
+ * magnitudes from `plusValues` / `minusValues` — resolved from the
+ * spec's `plusRange` / `minusRange` worksheet ranges via
+ * `resolveCustomErrorBarValues` before this runs.
+ */
+export type ErrorBarValueType = "fixedVal" | "percentage" | "stdDev" | "stdErr" | "custom";
+export type ErrorBarSpecInput = {
+    valueType?: ErrorBarValueType | null;
+    value?: number | null;
+    barType?: "both" | "plus" | "minus" | null;
+    /**
+     * Custom only — per-point upward magnitudes, index-aligned with the
+     * series values. Missing/non-finite entries draw no upper whisker.
+     */
+    plusValues?: (number | null | undefined)[] | null;
+    /** Custom only — per-point downward magnitudes. */
+    minusValues?: (number | null | undefined)[] | null;
+};
+export type ErrorBarMagnitudes = {
+    /** Upward magnitude per point (>= 0). */
+    plus: number[];
+    /** Downward magnitude per point (>= 0). */
+    minus: number[];
+};
+/**
+ * Resolve a custom error-bar spec's `plusRange` / `minusRange` into the
+ * `plusValues` / `minusValues` arrays `computeErrorBars` consumes.
+ *
+ * Range resolution is injected so this stays renderer-agnostic — both
+ * chart renderers pass the same `getSeriesValuesFromRange` extractor
+ * they already use for series data. Non-custom specs pass through
+ * untouched. Cells that don't hold finite numbers resolve to null
+ * (zero magnitude), keeping the arrays index-aligned with the range.
+ */
+export declare const resolveCustomErrorBarValues: <TRange>(spec: (ErrorBarSpecInput & {
+    plusRange?: TRange | null;
+    minusRange?: TRange | null;
+}) | null | undefined, getValuesFromRange: (range: TRange) => unknown[] | null | undefined) => ErrorBarSpecInput | null | undefined;
+/**
+ * Compute per-point error-bar magnitudes for a series.
+ *
+ * @param values    Raw series y-values (non-finite entries become 0
+ *                  magnitude so the arrays stay index-aligned).
+ * @param spec      The parsed error-bar spec.
+ * @returns         Plus/minus magnitude arrays, or null when the spec is
+ *                  undrawable (zero magnitude, or custom without values).
+ */
+export declare const computeErrorBars: (values: (number | null | undefined)[], spec: ErrorBarSpecInput | null | undefined) => ErrorBarMagnitudes | null;
+//# sourceMappingURL=error-bars.d.ts.map

package/dist/esm/utils/error-bars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-bars.d.ts","sourceRoot":"","sources":["../../../utils/error-bars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAC3C;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;IAClD,mDAAmD;IACnD,WAAW,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,yCAAyC;IACzC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2CAA2C;IAC3C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAoBF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,EAChD,MACI,CAAC,iBAAiB,GAAG;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,GACF,IAAI,GACJ,SAAS,EACb,oBAAoB,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,EAAE,GAAG,IAAI,GAAG,SAAS,KAClE,iBAAiB,GAAG,IAAI,GAAG,SAgB7B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACrC,MAAM,iBAAiB,GAAG,IAAI,GAAG,SAAS,KACzC,kBAAkB,GAAG,IAsEvB,CAAC"}