@rowsncolumns/charts 27.0.30

package/dist/cjs/utils/bubble.d.ts

@@ -0,0 +1,52 @@
+export declare const toLabelString: (value: unknown) => string;
+export declare const toNumericValue: (value: unknown) => number | null;
+export declare const createBubbleSizeScale: (values: number[]) => (value: number) => number;
+export type BubbleSeriesInput = {
+    name?: string | null;
+    values: (string | number | boolean | null | undefined)[];
+    /**
+     * Per-series X values. Excel's scatter charts always carry per-series
+     * `xVal` (each series has its own x/y pair). Excel's bubble charts
+     * typically share an X axis but the OOXML format allows per-series.
+     * When omitted, the shared `xValues` arg on `PrepareBubbleSeriesArgs`
+     * is used — preserves the old shared-X behaviour for fixtures that
+     * pass a single domain.
+     */
+    xValues?: (string | number | boolean | null | undefined)[];
+    /**
+     * Per-series bubble sizes. Bubble charts may carry one `bubbleSize`
+     * per series; falls back to the shared `sizeValues` when omitted.
+     */
+    sizeValues?: (string | number | boolean | null | undefined)[];
+};
+export type BubbleSeriesPoint = {
+    value: [number, number, number];
+    name: string;
+    xLabel?: string;
+};
+export type PreparedBubbleSeries = {
+    name: string;
+    points: BubbleSeriesPoint[];
+};
+export type PrepareBubbleSeriesArgs = {
+    /**
+     * Shared X values across all series. Used as the fallback when a
+     * series doesn't carry its own `xValues`. For pure-scatter charts
+     * (per-series xVal) this is typically `[]` and each series provides
+     * its own.
+     */
+    xValues: (string | number | boolean | null | undefined)[];
+    labelValues: (string | number | boolean | null | undefined)[];
+    /**
+     * Shared size values. Same fallback semantics as `xValues`.
+     */
+    sizeValues: (string | number | boolean | null | undefined)[];
+    series: BubbleSeriesInput[];
+};
+export type BubbleSeriesResult = {
+    categories: string[];
+    series: PreparedBubbleSeries[];
+    sizeValues: number[];
+};
+export declare const prepareBubbleSeriesData: ({ xValues, labelValues, sizeValues, series, }: PrepareBubbleSeriesArgs) => BubbleSeriesResult;
+//# sourceMappingURL=bubble.d.ts.map

package/dist/cjs/utils/bubble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bubble.d.ts","sourceRoot":"","sources":["../../../utils/bubble.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,MACU,CAAC;AAE1D,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAYxD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,EAAE,aAQrC,MAAM,WAOtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IACzD;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC3D;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;CAC/D,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC1D,WAAW,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC9D;;OAEG;IACH,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC7D,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAwCF,eAAO,MAAM,uBAAuB,GAAI,+CAKrC,uBAAuB,KAAG,kBAsF5B,CAAC"}

package/dist/cjs/utils/bubble.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareBubbleSeriesData = exports.createBubbleSizeScale = exports.toNumericValue = exports.toLabelString = void 0;
+var tslib_1 = require("tslib");
+var toLabelString = function (value) {
+    return value === null || value === undefined ? "" : "".concat(value);
+};
+exports.toLabelString = toLabelString;
+var toNumericValue = function (value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        var parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    if (typeof value === "boolean") {
+        return value ? 1 : 0;
+    }
+    return null;
+};
+exports.toNumericValue = toNumericValue;
+var createBubbleSizeScale = function (values) {
+    var valid = values.filter(function (value) { return Number.isFinite(value); });
+    if (valid.length === 0) {
+        return function () { return 24; };
+    }
+    var min = Math.min.apply(Math, tslib_1.__spreadArray([], tslib_1.__read(valid), false));
+    var max = Math.max.apply(Math, tslib_1.__spreadArray([], tslib_1.__read(valid), false));
+    var range = max - min || 1;
+    return function (value) {
+        if (!Number.isFinite(value)) {
+            return 24;
+        }
+        var ratio = (value - min) / range;
+        return 12 + ratio * 42;
+    };
+};
+exports.createBubbleSizeScale = createBubbleSizeScale;
+/**
+ * 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).
+ */
+var buildXCoordinates = function (xValues, categories, categoryIndex) {
+    var xCoordinates = [];
+    xValues.forEach(function (value, idx) {
+        var _a;
+        var numeric = (0, exports.toNumericValue)(value);
+        if (numeric !== null) {
+            xCoordinates[idx] = { coordinate: numeric };
+            return;
+        }
+        var label = (0, exports.toLabelString)(value);
+        if (!label) {
+            xCoordinates[idx] = { coordinate: idx };
+            return;
+        }
+        if (!categoryIndex.has(label)) {
+            categoryIndex.set(label, categories.length);
+            categories.push(label);
+        }
+        xCoordinates[idx] = {
+            coordinate: (_a = categoryIndex.get(label)) !== null && _a !== void 0 ? _a : idx,
+            label: label,
+        };
+    });
+    return xCoordinates;
+};
+var prepareBubbleSeriesData = function (_a) {
+    var xValues = _a.xValues, labelValues = _a.labelValues, sizeValues = _a.sizeValues, series = _a.series;
+    var normalizedLabels = labelValues.map(exports.toLabelString);
+    var sharedNormalizedSizeValues = sizeValues.map(function (value) {
+        return value === undefined || value === null ? null : (0, exports.toNumericValue)(value);
+    });
+    var categories = [];
+    var 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.
+    var sharedXCoordinates = buildXCoordinates(xValues, categories, categoryIndex);
+    var allSizeValues = [];
+    var preparedSeries = series.map(function (serie, seriesIndex) {
+        var _a, _b, _c;
+        // Per-series X values (scatter always; bubble may) override the
+        // shared X for this series only. Categories are still pooled.
+        var seriesXCoordinates = serie.xValues
+            ? buildXCoordinates(serie.xValues, categories, categoryIndex)
+            : sharedXCoordinates;
+        var seriesXValues = (_a = serie.xValues) !== null && _a !== void 0 ? _a : xValues;
+        // Per-series sizes — bubble charts can carry one bubbleSize per
+        // series. Falls back to the shared array.
+        var seriesNormalizedSizeValues = serie.sizeValues
+            ? serie.sizeValues.map(function (value) {
+                return value === undefined || value === null
+                    ? null
+                    : (0, exports.toNumericValue)(value);
+            })
+            : sharedNormalizedSizeValues;
+        var points = [];
+        var yValues = serie.values.map(function (value) { return (0, exports.toNumericValue)(value); });
+        var pointCount = Math.max(yValues.length, seriesXCoordinates.length);
+        for (var i = 0; i < pointCount; i++) {
+            var y = yValues[i];
+            var coordinate = seriesXCoordinates[i];
+            if (y === null || y === undefined || !coordinate) {
+                continue;
+            }
+            var sizeSource = seriesNormalizedSizeValues[i];
+            var resolvedSize = typeof sizeSource === "number" && Number.isFinite(sizeSource)
+                ? sizeSource
+                : y;
+            var sizeValue = typeof resolvedSize === "number" && Number.isFinite(resolvedSize)
+                ? resolvedSize
+                : 0;
+            allSizeValues.push(sizeValue);
+            var label = (_b = normalizedLabels[i]) !== null && _b !== void 0 ? _b : "";
+            var coordinateLabel = categories.length > 0
+                ? (_c = coordinate.label) !== null && _c !== void 0 ? _c : (0, exports.toLabelString)(seriesXValues[i])
+                : undefined;
+            points.push({
+                value: [coordinate.coordinate, y, sizeValue],
+                name: label,
+                xLabel: coordinateLabel,
+            });
+        }
+        var name = serie.name && serie.name.trim()
+            ? serie.name
+            : "Series ".concat(seriesIndex + 1);
+        return { name: name, points: points };
+    });
+    return {
+        categories: categories,
+        series: preparedSeries,
+        sizeValues: allSizeValues,
+    };
+};
+exports.prepareBubbleSeriesData = prepareBubbleSeriesData;

package/dist/cjs/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/cjs/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/cjs/utils/chart-spec-utils.js

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceCalculatedLabel = exports.getChartDataRanges = exports.mergeChartSpec = exports.mergeChartDataArray = exports.isPlaceholderChartData = exports.getPropertiesToRemove = exports.getDefaultChartTypeSpec = exports.isHierarchyChartSpec = exports.isBubbleChartSpec = exports.isBasicChartSpec = exports.getChartCategory = exports.HIERARCHY_CHART_TYPES = exports.BUBBLE_CHART_TYPES = exports.BASIC_CHART_TYPES = void 0;
+var tslib_1 = require("tslib");
+exports.BASIC_CHART_TYPES = new Set([
+    "bar",
+    "column",
+    "line",
+    "pie",
+    "area",
+    "doughnut",
+    "radar",
+    "stock",
+    "histogram",
+    "boxplot",
+    "waterfall",
+    "funnel",
+    "combo",
+    "regionMap",
+]);
+exports.BUBBLE_CHART_TYPES = new Set(["bubble", "scatter"]);
+exports.HIERARCHY_CHART_TYPES = new Set([
+    "treemap",
+    "sunburst",
+]);
+/**
+ * Returns the category of a chart type.
+ */
+var getChartCategory = function (chartType) {
+    if (exports.BASIC_CHART_TYPES.has(chartType))
+        return "basic";
+    if (exports.BUBBLE_CHART_TYPES.has(chartType))
+        return "bubble";
+    if (exports.HIERARCHY_CHART_TYPES.has(chartType))
+        return "hierarchy";
+    return "basic";
+};
+exports.getChartCategory = getChartCategory;
+/**
+ * Type guards for chart specs
+ */
+var isBasicChartSpec = function (spec) { return exports.BASIC_CHART_TYPES.has(spec.chartType); };
+exports.isBasicChartSpec = isBasicChartSpec;
+var isBubbleChartSpec = function (spec) {
+    return exports.BUBBLE_CHART_TYPES.has(spec.chartType);
+};
+exports.isBubbleChartSpec = isBubbleChartSpec;
+var isHierarchyChartSpec = function (spec) {
+    return exports.HIERARCHY_CHART_TYPES.has(spec.chartType);
+};
+exports.isHierarchyChartSpec = isHierarchyChartSpec;
+/**
+ * Default specs for each chart type.
+ * These provide sensible defaults when creating new charts.
+ */
+var 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.
+ */
+var getDefaultChartTypeSpec = function (chartType) {
+    var _a;
+    return (_a = DEFAULT_CHART_TYPE_SPECS[chartType]) !== null && _a !== void 0 ? _a : { chartType: chartType };
+};
+exports.getDefaultChartTypeSpec = getDefaultChartTypeSpec;
+/**
+ * Properties specific to individual chart types within the basic category.
+ * These should be cleared when switching between chart types within basic charts.
+ */
+var 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.
+ */
+var 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.
+ */
+var getPropertiesToRemove = function (fromType, toType) {
+    var _a;
+    // No changes needed if same chart type
+    if (fromType === toType) {
+        return [];
+    }
+    var fromCategory = (0, exports.getChartCategory)(fromType);
+    var toCategory = (0, exports.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 (_a = BASIC_CHART_TYPE_PROPERTIES[fromType]) !== null && _a !== void 0 ? _a : [];
+    }
+    return [];
+};
+exports.getPropertiesToRemove = getPropertiesToRemove;
+/**
+ * Checks if chart data array is empty or contains only placeholder entries.
+ */
+var isPlaceholderChartData = function (data) {
+    if (!data || data.length === 0)
+        return true;
+    return data.every(function (entry) {
+        var _a;
+        var sources = (_a = entry === null || entry === void 0 ? void 0 : entry.sources) !== null && _a !== void 0 ? _a : [];
+        return sources.length === 0 || sources.every(function (source) { return !source; });
+    });
+};
+exports.isPlaceholderChartData = isPlaceholderChartData;
+/**
+ * Merges chart data arrays, preserving current data if incoming is placeholder.
+ */
+var mergeChartDataArray = function (current, incoming) {
+    var _a;
+    if (!incoming || (0, exports.isPlaceholderChartData)(incoming)) {
+        return (_a = current !== null && current !== void 0 ? current : incoming) !== null && _a !== void 0 ? _a : [];
+    }
+    return incoming;
+};
+exports.mergeChartDataArray = mergeChartDataArray;
+/**
+ * Chart data fields specific to each category.
+ */
+var 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.
+ */
+var mergeChartSpec = function (existingSpec, incomingSpec) {
+    var e_1, _a, e_2, _b, e_3, _c;
+    var incomingChartType = incomingSpec.chartType;
+    var existingChartType = existingSpec.chartType;
+    var existingCategory = (0, exports.getChartCategory)(existingChartType);
+    var targetCategory = incomingChartType
+        ? (0, exports.getChartCategory)(incomingChartType)
+        : existingCategory;
+    var isCategoryChange = incomingChartType && existingCategory !== targetCategory;
+    // Start with a copy of existing spec
+    var merged = tslib_1.__assign({}, existingSpec);
+    // Handle chart type changes - remove type-specific properties
+    if (incomingChartType && incomingChartType !== existingChartType) {
+        var propertiesToRemove = (0, exports.getPropertiesToRemove)(existingChartType, incomingChartType);
+        try {
+            for (var propertiesToRemove_1 = tslib_1.__values(propertiesToRemove), propertiesToRemove_1_1 = propertiesToRemove_1.next(); !propertiesToRemove_1_1.done; propertiesToRemove_1_1 = propertiesToRemove_1.next()) {
+                var prop = propertiesToRemove_1_1.value;
+                delete merged[prop];
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (propertiesToRemove_1_1 && !propertiesToRemove_1_1.done && (_a = propertiesToRemove_1.return)) _a.call(propertiesToRemove_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    }
+    // When switching categories, remove data fields from old category
+    if (isCategoryChange) {
+        var oldCategoryDataFields = CATEGORY_DATA_FIELDS[existingCategory];
+        try {
+            for (var oldCategoryDataFields_1 = tslib_1.__values(oldCategoryDataFields), oldCategoryDataFields_1_1 = oldCategoryDataFields_1.next(); !oldCategoryDataFields_1_1.done; oldCategoryDataFields_1_1 = oldCategoryDataFields_1.next()) {
+                var field = oldCategoryDataFields_1_1.value;
+                delete merged[field];
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (oldCategoryDataFields_1_1 && !oldCategoryDataFields_1_1.done && (_b = oldCategoryDataFields_1.return)) _b.call(oldCategoryDataFields_1);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+    }
+    // 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
+    var existingWithData = existingSpec;
+    var incomingWithData = incomingSpec;
+    var targetDataFields = CATEGORY_DATA_FIELDS[targetCategory];
+    try {
+        for (var targetDataFields_1 = tslib_1.__values(targetDataFields), targetDataFields_1_1 = targetDataFields_1.next(); !targetDataFields_1_1.done; targetDataFields_1_1 = targetDataFields_1.next()) {
+            var field = targetDataFields_1_1.value;
+            var existingData = isCategoryChange ? undefined : existingWithData[field];
+            var incomingData = incomingWithData[field];
+            if (existingData !== undefined || incomingData !== undefined) {
+                merged[field] = (0, exports.mergeChartDataArray)(existingData, incomingData);
+            }
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (targetDataFields_1_1 && !targetDataFields_1_1.done && (_c = targetDataFields_1.return)) _c.call(targetDataFields_1);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    return merged;
+};
+exports.mergeChartSpec = mergeChartSpec;
+/**
+ * Extracts all SheetRange objects from a ChartSpec.
+ * Useful for subscribing to data changes across all chart data sources.
+ */
+var getChartDataRanges = function (spec) {
+    var e_4, _a, e_5, _b, e_6, _c;
+    var ranges = [];
+    var category = (0, exports.getChartCategory)(spec.chartType);
+    var dataFields = CATEGORY_DATA_FIELDS[category];
+    var specWithData = spec;
+    try {
+        for (var dataFields_1 = tslib_1.__values(dataFields), dataFields_1_1 = dataFields_1.next(); !dataFields_1_1.done; dataFields_1_1 = dataFields_1.next()) {
+            var field = dataFields_1_1.value;
+            var chartDataArray = specWithData[field];
+            if (chartDataArray) {
+                try {
+                    for (var chartDataArray_1 = (e_5 = void 0, tslib_1.__values(chartDataArray)), chartDataArray_1_1 = chartDataArray_1.next(); !chartDataArray_1_1.done; chartDataArray_1_1 = chartDataArray_1.next()) {
+                        var chartData = chartDataArray_1_1.value;
+                        if (chartData === null || chartData === void 0 ? void 0 : chartData.sources) {
+                            try {
+                                for (var _d = (e_6 = void 0, tslib_1.__values(chartData.sources)), _e = _d.next(); !_e.done; _e = _d.next()) {
+                                    var source = _e.value;
+                                    if (source) {
+                                        ranges.push(source);
+                                    }
+                                }
+                            }
+                            catch (e_6_1) { e_6 = { error: e_6_1 }; }
+                            finally {
+                                try {
+                                    if (_e && !_e.done && (_c = _d.return)) _c.call(_d);
+                                }
+                                finally { if (e_6) throw e_6.error; }
+                            }
+                        }
+                    }
+                }
+                catch (e_5_1) { e_5 = { error: e_5_1 }; }
+                finally {
+                    try {
+                        if (chartDataArray_1_1 && !chartDataArray_1_1.done && (_b = chartDataArray_1.return)) _b.call(chartDataArray_1);
+                    }
+                    finally { if (e_5) throw e_5.error; }
+                }
+            }
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (dataFields_1_1 && !dataFields_1_1.done && (_a = dataFields_1.return)) _a.call(dataFields_1);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+    return ranges;
+};
+exports.getChartDataRanges = getChartDataRanges;
+/**
+ * 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.
+ */
+var coerceCalculatedLabel = function (result) {
+    if (typeof result === "string") {
+        return result;
+    }
+    if (typeof result === "number" || typeof result === "boolean") {
+        return String(result);
+    }
+    return "";
+};
+exports.coerceCalculatedLabel = coerceCalculatedLabel;

package/dist/cjs/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/cjs/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"}