@rowsncolumns/charts 27.0.30

package/dist/esm/basic-chart/basic-chart.js

@@ -0,0 +1,2343 @@
+import { ChevronRightIcon, DotsVerticalIcon } from "@rowsncolumns/icons";
+import { getStringifiedColor, useFocusSheet } from "@rowsncolumns/spreadsheet";
+import { useSubscribeToMultipleRanges } from "@rowsncolumns/spreadsheet-state";
+import { createDownloadableFile } from "@rowsncolumns/toolkit";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, DropdownRightSlot, IconButton, useIsomorphicLayoutEffect, useOnVisibilityChange, } from "@rowsncolumns/ui";
+import { debug, isAFormula, isNil } from "@rowsncolumns/utils";
+import { BarChart, BoxplotChart, CandlestickChart, CustomChart, FunnelChart, LineChart, PieChart, RadarChart as EchartsRadarChart, ScatterChart, SunburstChart, TreemapChart as EchartsTreemapChart, } from "echarts/charts";
+import { DatasetComponent, GridComponent, LegendComponent, RadarComponent, TitleComponent, TooltipComponent, } from "echarts/components";
+import * as echarts from "echarts/core";
+import { CanvasRenderer } from "echarts/renderers";
+import React, { useCallback, useMemo, useRef, useState } from "react";
+import { aggregateSeriesByDomain, getDomainValuesForAxis, sanitizeDomainValues, shouldAggregateSeries, } from "../utils/aggregation";
+import { gapWidthToBarCategoryGap, overlapToBarGap, } from "../utils/bar-layout";
+import { computeBoxplotSummary } from "../utils/boxplot";
+import { createBubbleSizeScale, prepareBubbleSeriesData, } from "../utils/bubble";
+import { coerceCalculatedLabel, getChartDataRanges, } from "../utils/chart-spec-utils";
+import { getEchartsGlState, loadEchartsGl, } from "../utils/echarts-gl-loader";
+import { computeErrorBars, resolveCustomErrorBarValues, } from "../utils/error-bars";
+import { gradientToEcharts } from "../utils/gradient";
+import { buildHierarchyTree, extractHierarchyRows, getHierarchyHeaderTitle, } from "../utils/hierarchy";
+import { binHistogram, computePareto, isParetoSpec, } from "../utils/histogram";
+import { clampSecondPieSize, isOfPieChartSpec, otherSliceHalfAngle, resolveOfPieType, splitOfPie, } from "../utils/of-pie";
+import { applyAxisOverrides, applyLegendOverrides, buildSeriesLabelOption, } from "../utils/overrides";
+import { buildRadarIndicators, buildRadarSeriesData } from "../utils/radar";
+import { buildRegionMapData, buildSequentialColorRamp, isRegionMapSpec, resolveGeoScope, warnOnceForUnmatchedRegions, } from "../utils/region-map";
+import { loadRegionMapGeo } from "../utils/region-map-loader";
+import { toCandlestick, toLineSeries, toVolumeSeries, } from "../utils/stock";
+import { buildBar3DData, buildLine3DSeries, buildSurfaceData, getValueExtent, resolve3DRenderKind, SURFACE_COLOR_RAMP, } from "../utils/three-d";
+import { computeTrendline } from "../utils/trendline";
+import { computeWaterfall } from "../utils/waterfall";
+import { isWebGLAvailable } from "../utils/webgl";
+import { chartTypeToEchartsType, getEchartsSeriesStyle, mapMarkerSymbolToEcharts, showXAxis, } from "./helpers";
+// Excel error values that should be treated as null in charts
+const EXCEL_ERROR_VALUES = new Set([
+    "#N/A",
+    "#REF!",
+    "#VALUE!",
+    "#DIV/0!",
+    "#NAME?",
+    "#NULL!",
+    "#NUM!",
+    "#ERROR!",
+    "#GETTING_DATA",
+]);
+/**
+ * Check if a value is an Excel error string
+ */
+const isErrorValue = (value) => {
+    if (typeof value !== "string")
+        return false;
+    return EXCEL_ERROR_VALUES.has(value.toUpperCase());
+};
+/**
+ * Sanitize a value for chart display - convert errors to undefined
+ */
+const sanitizeChartValue = (value) => {
+    if (value === null || value === undefined)
+        return undefined;
+    if (isErrorValue(value))
+        return undefined;
+    if (typeof value === "number" && !isNaN(value))
+        return value;
+    if (typeof value === "string") {
+        const num = parseFloat(value);
+        return isNaN(num) ? undefined : num;
+    }
+    return undefined;
+};
+const BASIC_CHART_TYPES = new Set([
+    "bar",
+    "column",
+    "line",
+    "pie",
+    "area",
+    "doughnut",
+    "radar",
+    "stock",
+    "histogram",
+    "boxplot",
+    "waterfall",
+    "funnel",
+    "combo",
+    "regionMap",
+]);
+const BUBBLE_CHART_TYPES = new Set([
+    "bubble",
+    "scatter",
+]);
+const HIERARCHY_CHART_TYPES = new Set([
+    "treemap",
+    "sunburst",
+]);
+const isBasicChartSpec = (spec) => BASIC_CHART_TYPES.has(spec.chartType);
+const isBubbleChartSpec = (spec) => BUBBLE_CHART_TYPES.has(spec.chartType);
+const isHierarchyChartSpec = (spec) => HIERARCHY_CHART_TYPES.has(spec.chartType);
+const HIERARCHY_LEVEL_STYLES = [
+    {
+        itemStyle: {
+            gapWidth: 1,
+            borderColorSaturation: 0.6,
+        },
+        upperLabel: { show: false },
+    },
+    {
+        colorSaturation: [0.35, 0.65],
+        itemStyle: {
+            gapWidth: 1,
+            borderColorSaturation: 0.6,
+        },
+    },
+    {
+        colorSaturation: [0.45, 0.75],
+        itemStyle: {
+            gapWidth: 1,
+            borderColorSaturation: 0.6,
+        },
+    },
+];
+const getHierarchyDepth = (nodes, depth = 1) => {
+    let maxDepth = depth;
+    nodes.forEach((node) => {
+        if (node.children && node.children.length > 0) {
+            maxDepth = Math.max(maxDepth, getHierarchyDepth(node.children, depth + 1));
+        }
+    });
+    return maxDepth;
+};
+const flattenChartDataValues = (chartData, extractor, hiddenStrategy, skipFirstRow = false) => {
+    if (!chartData || chartData.length === 0)
+        return [];
+    const values = [];
+    chartData.forEach((entry) => {
+        // Inline values (`<c:strLit>` / `<c:numLit>` embedded in the chart
+        // XML) take precedence over cell-range sources — by spec only one
+        // is populated, but if both happen to exist the inline value is
+        // the authored "ground truth".
+        const inline = entry
+            .inlineValues;
+        if (inline && inline.length) {
+            const trimmed = skipFirstRow ? inline.slice(1) : inline;
+            values.push(...trimmed);
+            return;
+        }
+        entry.sources.forEach((source) => {
+            const extracted = extractor(source, hiddenStrategy) ?? [];
+            const trimmed = skipFirstRow && extracted.length > 0 ? extracted.slice(1) : extracted;
+            values.push(...trimmed);
+        });
+    });
+    return values;
+};
+const buildHierarchyLevels = (maxDepth) => {
+    if (maxDepth <= 0)
+        return undefined;
+    const levels = [];
+    for (let i = 0; i < maxDepth; i++) {
+        const baseStyle = HIERARCHY_LEVEL_STYLES[Math.min(i, HIERARCHY_LEVEL_STYLES.length - 1)];
+        levels.push({
+            ...baseStyle,
+            itemStyle: {
+                ...baseStyle.itemStyle,
+            },
+        });
+    }
+    return levels;
+};
+const defaultLegendConfig = {
+    padding: 10,
+    itemWidth: 10,
+    itemHeight: 4,
+    top: 20,
+};
+export const BasicChart = ({ width, height, chart, theme, isDarkMode, sheetId, readonly, getDomainValuesFromRange, getSeriesValuesFromRange, onDeleteChart, onRequestEdit, onRequestCalculate, isSelected, }) => {
+    const spec = chart.spec;
+    const explicitChartTitle = chart.spec.title ?? undefined;
+    const hierarchyTitleRef = useRef(explicitChartTitle);
+    const title = explicitChartTitle ?? hierarchyTitleRef.current;
+    const el = useRef(null);
+    const chartRef = useRef(undefined);
+    const focusSheet = useFocusSheet();
+    const shouldFocusSheetRef = useRef(false);
+    const previousChartType = useRef(undefined);
+    const previousSeriesCount = useRef(undefined);
+    // 3-D pipeline state. echarts-gl is lazy-loaded the first time a 3-D
+    // spec renders; the tick re-runs updateChart when the module lands so
+    // the chart upgrades from the immediate 2-D fallback to true 3-D.
+    const renderedIn3D = useRef(false);
+    const glUpgradeRequested = useRef(false);
+    const [glUpgradeTick, setGlUpgradeTick] = useState(0);
+    // Region-map (choropleth) pipeline state. The map option (geo +
+    // visualMap) doesn't merge back into a cartesian one, so the instance
+    // is re-initialized when entering/leaving the region-map rendering.
+    const renderedAsRegionMap = useRef(false);
+    // Initialize line chart
+    const initializeChart = () => {
+        if (el.current && !chartRef.current) {
+            chartRef.current = echarts.init(el.current);
+            chartRef.current.setOption({
+                title: {
+                    left: "top",
+                    padding: 10,
+                    textStyle: {
+                        fontSize: 16,
+                        fontWeight: "normal",
+                        fontFamily: "Untitled Sans, apple-system, sans-serif",
+                    },
+                },
+                tooltip: {
+                    textStyle: {
+                        fontSize: 12,
+                    },
+                    trigger: "axis",
+                },
+                legend: defaultLegendConfig,
+                grid: {
+                    left: "3%",
+                    right: "4%",
+                    bottom: "3%",
+                    containLabel: true,
+                },
+                xAxis: [
+                    {
+                        type: "category",
+                        name: spec.horizontalAxisTitle ?? "", // Set your x-axis title here
+                        nameLocation: "middle",
+                        nameGap: 30,
+                    },
+                ],
+                yAxis: [
+                    {
+                        type: "value",
+                        name: spec.verticalAxisTitle ?? "", // Set your y-axis title here
+                        nameLocation: "middle",
+                        nameGap: 50,
+                    },
+                ],
+                series: [],
+            });
+        }
+    };
+    const getSeriesData = useCallback((spec, sheetRange, options) => {
+        const rawSeriesValues = getSeriesValuesFromRange(sheetRange, spec.hiddenDimensionStrategy);
+        // Sanitize values - convert error strings like #N/A to null
+        const seriesValues = rawSeriesValues.map(sanitizeChartValue);
+        const { aggregateEnabled, aggregateType, rawDomainValues, orderedDomainValues, } = options;
+        const canAggregate = aggregateEnabled &&
+            !!aggregateType &&
+            rawDomainValues.length > 0 &&
+            orderedDomainValues.length > 0 &&
+            rawDomainValues.length === seriesValues.length;
+        if (canAggregate) {
+            const aggregatedValues = aggregateSeriesByDomain(rawDomainValues, seriesValues, aggregateType, orderedDomainValues);
+            if (spec.chartType === "pie") {
+                return orderedDomainValues.map((name, idx) => ({
+                    value: aggregatedValues[idx] ?? 0,
+                    name,
+                }));
+            }
+            return aggregatedValues;
+        }
+        const numericValues = seriesValues;
+        if (spec.chartType === "pie") {
+            const domainSheetRange = spec.domains[0]?.sources[0];
+            if (!domainSheetRange) {
+                return [];
+            }
+            const domainValues = getDomainValuesFromRange(domainSheetRange, spec.hiddenDimensionStrategy);
+            return domainValues.map((name, idx) => ({
+                value: numericValues[idx],
+                name,
+            }));
+        }
+        return numericValues;
+    }, [getSeriesValuesFromRange, getDomainValuesFromRange]);
+    // Resize a chart
+    const resizeChart = () => {
+        chartRef.current?.resize();
+    };
+    /**
+     * Triggers a chart update
+     */
+    const updateChart = async () => {
+        debug("Updating chart", chart);
+        // ---------------------------- 3-D gating ----------------------------
+        // 3-D / surface payloads degrade to a 2-D fallback `chartType` with the
+        // authored class preserved as `sourceChartType` (BAR_3D, LINE_3D,
+        // PIE_3D, AREA_3D, SURFACE, SURFACE_3D). When WebGL is available and
+        // the lazily loaded echarts-gl module is ready, the dedicated 3-D
+        // branch below renders a true 3-D plot; in every other case (no WebGL,
+        // SSR, import failure, PIE_3D) the 2-D fallback renders untouched.
+        // The 3-D and region-map gates key off disjoint sourceChartType
+        // tokens, so a spec can never satisfy both.
+        const threeDRenderKind = resolve3DRenderKind(spec.sourceChartType);
+        const canRender3D = threeDRenderKind !== null && isWebGLAvailable();
+        const willRender3D = canRender3D && getEchartsGlState() === "ready";
+        if (canRender3D && !willRender3D && getEchartsGlState() !== "failed") {
+            // Kick off the echarts-gl load in the background (once). The 2-D
+            // fallback renders immediately; the tick re-runs updateChart to
+            // upgrade to 3-D when the module resolves. A failed load latches
+            // and the chart simply stays 2-D.
+            if (!glUpgradeRequested.current) {
+                glUpgradeRequested.current = true;
+                loadEchartsGl().then((loaded) => {
+                    if (loaded) {
+                        setGlUpgradeTick((tick) => tick + 1);
+                    }
+                });
+            }
+        }
+        if (renderedIn3D.current && !willRender3D) {
+            // Leaving 3-D (spec edit) — the grid3D option doesn't merge back
+            // into a cartesian one, so re-initialize from a clean slate and
+            // let the normal 2-D flow below do a full structural render.
+            chartRef.current?.dispose();
+            chartRef.current = undefined;
+            renderedIn3D.current = false;
+            previousChartType.current = undefined;
+            previousSeriesCount.current = undefined;
+            initializeChart();
+            applyThemeOptions();
+        }
+        // ------------------------- Region map -------------------------
+        // Filled map / choropleth: `chartType: "regionMap"`, or a payload
+        // degraded to another basic `chartType` that preserves the authored
+        // class as `sourceChartType: "REGION_MAP"`. Category labels are the
+        // region names and the first series carries the values. The geo
+        // assets (echarts map module + world GeoJSON) are lazy-loaded on
+        // first use, so non-map charts never pay for them.
+        const isRegionMap = isRegionMapSpec(spec);
+        if (renderedAsRegionMap.current && !isRegionMap) {
+            // Leaving the region map (spec edit) — the geo/visualMap option
+            // doesn't merge back into a cartesian one, so re-initialize from
+            // a clean slate and let the normal flow below do a full
+            // structural render.
+            chartRef.current?.dispose();
+            chartRef.current = undefined;
+            renderedAsRegionMap.current = false;
+            previousChartType.current = undefined;
+            previousSeriesCount.current = undefined;
+            initializeChart();
+            applyThemeOptions();
+        }
+        if (isRegionMap) {
+            const regionSpec = spec;
+            const geoScope = resolveGeoScope(regionSpec.geoScope);
+            const geo = await loadRegionMapGeo(geoScope);
+            // Entering the region map from a cartesian render: the previous
+            // grid/axis option doesn't merge into the map one, so start from
+            // a bare instance (theme options are re-applied after setOption).
+            if (!renderedAsRegionMap.current && chartRef.current) {
+                chartRef.current.dispose();
+                chartRef.current = undefined;
+            }
+            if (el.current && !chartRef.current) {
+                chartRef.current = echarts.init(el.current);
+            }
+            if (!geo) {
+                // Map asset failed to load (or unknown scope) — the loader
+                // already warned once; render an empty chart, never crash.
+                chartRef.current?.setOption({ series: [] }, { replaceMerge: ["series", "visualMap"] });
+                renderedAsRegionMap.current = true;
+                applyThemeOptions();
+                previousChartType.current = spec.chartType;
+                previousSeriesCount.current = 0;
+                return;
+            }
+            const labels = flattenChartDataValues(regionSpec.domains, getDomainValuesFromRange, regionSpec.hiddenDimensionStrategy, false);
+            const seriesEntry = regionSpec.series?.[0];
+            const values = seriesEntry
+                ? flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, regionSpec.hiddenDimensionStrategy)
+                : [];
+            const { data, unmatched, min, max } = buildRegionMapData(labels, values, geo.regionNames);
+            warnOnceForUnmatchedRegions(geoScope, unmatched);
+            const textColor = getStringifiedColor({ theme: 1, tint: isDarkMode ? 1 : 0 }, theme);
+            // Sequential single-hue value ramp derived from the theme accent;
+            // regions without data keep a neutral fill so "no data" reads
+            // differently from "small value".
+            const ramp = buildSequentialColorRamp(theme.themeColors.accent1, !!isDarkMode);
+            const noDataColor = isDarkMode
+                ? "rgba(255,255,255,0.08)"
+                : "rgba(0,0,0,0.06)";
+            const borderColor = isDarkMode ? "rgba(255,255,255,0.3)" : "#FFFFFF";
+            const regionSeriesLabel = buildSeriesLabelOption(spec.dataLabels);
+            const seriesName = seriesEntry?.dataLabel && !isAFormula(seriesEntry.dataLabel)
+                ? seriesEntry.dataLabel
+                : "";
+            chartRef.current?.setOption({
+                // The visualMap color scale is the value legend; the series
+                // legend stays hidden unless an authored override turns it on.
+                legend: applyLegendOverrides({ ...defaultLegendConfig, show: false }, spec.legend),
+                tooltip: {
+                    textStyle: { fontSize: 12 },
+                    trigger: "item",
+                    formatter: (params) => {
+                        const value = Array.isArray(params?.value)
+                            ? params.value[params.value.length - 1]
+                            : params?.value;
+                        return typeof value === "number" && Number.isFinite(value)
+                            ? `${params?.name}: ${value}`
+                            : `${params?.name ?? ""}`;
+                    },
+                },
+                visualMap: [
+                    {
+                        type: "continuous",
+                        min,
+                        max,
+                        left: "left",
+                        bottom: 10,
+                        inRange: { color: ramp },
+                        textStyle: { color: textColor, fontSize: 12 },
+                    },
+                ],
+                series: [
+                    {
+                        type: "map",
+                        map: geoScope,
+                        name: seriesName,
+                        data,
+                        roam: false,
+                        // Region names label the shapes only when the authored
+                        // dataLabels override asks for them.
+                        label: { show: false, ...(regionSeriesLabel ?? {}) },
+                        emphasis: { label: { show: false } },
+                        select: { disabled: true },
+                        itemStyle: {
+                            areaColor: noDataColor,
+                            borderColor,
+                            borderWidth: 0.5,
+                        },
+                    },
+                ],
+            }, { replaceMerge: ["series", "visualMap", "legend", "tooltip"] });
+            // Re-apply theme-derived title / palette / tooltip colors — lost
+            // when the instance was re-initialized on entry.
+            renderedAsRegionMap.current = true;
+            applyThemeOptions();
+            previousChartType.current = spec.chartType;
+            previousSeriesCount.current = 1;
+            return;
+        }
+        const chartDomains = [];
+        const chartSeries = [];
+        const legend = { ...defaultLegendConfig, data: [] };
+        const chartType = chartTypeToEchartsType(spec?.chartType);
+        const position = chart.position;
+        const showAxis = showXAxis(spec?.chartType);
+        const isBubble = isBubbleChartSpec(spec);
+        const isHierarchy = isHierarchyChartSpec(spec);
+        if (isBubble) {
+            hierarchyTitleRef.current = explicitChartTitle;
+            const skipHeaders = spec.useFirstRowAsHeaders !== false;
+            const labelValues = flattenChartDataValues(spec.bubbleLabels, getDomainValuesFromRange, spec.hiddenDimensionStrategy, skipHeaders);
+            // Per-series X / size — scatter (always) and bubble (often) carry
+            // a separate xVal/bubbleSize per series in OOXML. Earlier code
+            // flattened them into a single shared array which broke when
+            // series had different ranges.
+            const perSeriesX = (spec.domains ?? []).map((dom) => flattenChartDataValues([dom], getSeriesValuesFromRange, spec.hiddenDimensionStrategy, skipHeaders));
+            const perSeriesSize = (spec.bubbleSizes ?? []).map((sz) => flattenChartDataValues([sz], getSeriesValuesFromRange, spec.hiddenDimensionStrategy, skipHeaders));
+            const seriesInputs = [];
+            for (let i = 0; i < spec.series.length; i++) {
+                const seriesEntry = spec.series[i];
+                let resolvedLabel = seriesEntry.dataLabel ?? "";
+                if (resolvedLabel && isAFormula(resolvedLabel)) {
+                    resolvedLabel = coerceCalculatedLabel(await onRequestCalculate(resolvedLabel, position.sheetId ?? sheetId, position.overlayPosition.anchorCell.rowIndex, position.overlayPosition.anchorCell.columnIndex));
+                }
+                const xValues = perSeriesX[i] ?? perSeriesX[0];
+                const sizeValues = perSeriesSize[i] ?? perSeriesSize[0];
+                seriesInputs.push({
+                    name: resolvedLabel,
+                    values: flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, spec.hiddenDimensionStrategy, skipHeaders),
+                    ...(xValues ? { xValues } : {}),
+                    ...(sizeValues ? { sizeValues } : {}),
+                });
+            }
+            const sharedXValues = perSeriesX[0] ?? [];
+            const sharedSizeValues = perSeriesSize[0] ?? [];
+            const { categories, series: preparedSeries, sizeValues, } = prepareBubbleSeriesData({
+                xValues: sharedXValues,
+                labelValues,
+                sizeValues: sharedSizeValues,
+                series: seriesInputs,
+            });
+            const sizeScale = createBubbleSizeScale(sizeValues);
+            const xAxisConfig = categories.length > 0
+                ? {
+                    type: "category",
+                    data: categories,
+                    name: spec.horizontalAxisTitle ?? "",
+                    nameLocation: "middle",
+                    nameGap: 30,
+                }
+                : {
+                    type: "value",
+                    name: spec.horizontalAxisTitle ?? "",
+                    nameLocation: "middle",
+                    nameGap: 30,
+                };
+            const tooltipFormatter = (params) => {
+                const [rawX, y, size] = (params.value ?? []);
+                const label = categories.length > 0
+                    ? params.data?.xLabel ?? categories[Math.round(rawX)] ?? rawX
+                    : rawX;
+                const bubbleName = params.name ? `${params.name}<br/>` : "";
+                const seriesName = params.seriesName ? `${params.seriesName}<br/>` : "";
+                return `${seriesName}${bubbleName}X: ${label ?? ""}<br/>Y: ${y ?? ""}<br/>Size: ${size ?? ""}`;
+            };
+            // Spec-level overrides — axis min/max/visibility/textFormat, legend
+            // position/visibility, dataLabel toggles. Same helpers as the
+            // non-bubble layout below.
+            const bubbleSeriesLabel = buildSeriesLabelOption(spec.dataLabels);
+            chartRef.current?.setOption({
+                xAxis: [
+                    applyAxisOverrides({ ...xAxisConfig }, spec.categoryAxisOptions),
+                ],
+                yAxis: [
+                    applyAxisOverrides({
+                        type: "value",
+                        name: spec.verticalAxisTitle ?? "",
+                        nameLocation: "middle",
+                        nameGap: 45,
+                    }, spec.valueAxisOptions),
+                ],
+                legend: applyLegendOverrides({
+                    ...legend,
+                    show: preparedSeries.length > 1,
+                    data: preparedSeries.map((entry) => entry.name),
+                }, spec.legend),
+                grid: {
+                    left: "3%",
+                    right: "4%",
+                    bottom: "3%",
+                    containLabel: true,
+                },
+                tooltip: {
+                    trigger: "item",
+                    formatter: tooltipFormatter,
+                },
+                // Scatter vs bubble — scatter uses small fixed markers
+                // (optionally connected with a line per scatterStyle); bubble
+                // applies a size scale on the 3rd dimension. Pre-fix scatter
+                // routed through the bubble code, producing Y-scaled giant
+                // circles instead of Excel's small dots.
+                series: preparedSeries.map((entry, index) => {
+                    const isScatter = spec.chartType === "scatter";
+                    const scatterStyle = spec.scatterStyle ??
+                        (isScatter ? "lineMarker" : undefined);
+                    const seriesEntry = spec.series?.[index];
+                    const seriesColor = seriesEntry?.color;
+                    const perMarker = seriesEntry?.marker;
+                    if (isScatter) {
+                        const symbol = perMarker?.symbol;
+                        const noMarkers = symbol === "none";
+                        const wantsLine = scatterStyle === "line" ||
+                            scatterStyle === "lineMarker" ||
+                            scatterStyle === "smooth" ||
+                            scatterStyle === "smoothMarker";
+                        const wantsMarkers = !noMarkers &&
+                            (scatterStyle === "marker" ||
+                                scatterStyle === "lineMarker" ||
+                                scatterStyle === "smoothMarker" ||
+                                !scatterStyle);
+                        const smooth = scatterStyle === "smooth" || scatterStyle === "smoothMarker";
+                        return wantsLine
+                            ? {
+                                type: "line",
+                                name: entry.name,
+                                data: entry.points,
+                                showSymbol: wantsMarkers,
+                                smooth,
+                                symbol: mapMarkerSymbolToEcharts(symbol) ?? "circle",
+                                symbolSize: perMarker?.size ?? 6,
+                                ...(seriesColor
+                                    ? {
+                                        itemStyle: { color: seriesColor },
+                                        lineStyle: { color: seriesColor },
+                                    }
+                                    : {}),
+                            }
+                            : {
+                                type: "scatter",
+                                name: entry.name,
+                                data: entry.points,
+                                symbol: mapMarkerSymbolToEcharts(symbol) ?? "circle",
+                                symbolSize: perMarker?.size ?? 6,
+                                ...(seriesColor
+                                    ? { itemStyle: { color: seriesColor } }
+                                    : {}),
+                            };
+                    }
+                    return {
+                        type: chartType,
+                        name: entry.name,
+                        data: entry.points,
+                        symbolSize: (data) => sizeScale(data?.[2] ?? 0),
+                        label: {
+                            show: true,
+                            formatter: (params) => params.name ?? "",
+                        },
+                        ...(seriesColor ? { itemStyle: { color: seriesColor } } : {}),
+                    };
+                }).map((s) => bubbleSeriesLabel
+                    ? { ...s, label: { ...(s.label ?? {}), ...bubbleSeriesLabel } }
+                    : s),
+            }, {
+                replaceMerge: [
+                    "series",
+                    "xAxis",
+                    "yAxis",
+                    "legend",
+                    "grid",
+                    "tooltip",
+                ],
+            });
+            previousChartType.current = spec.chartType;
+            previousSeriesCount.current = preparedSeries.length;
+            return;
+        }
+        if (isHierarchy) {
+            const hierarchyRows = extractHierarchyRows(spec, {
+                getDomainValuesFromRange,
+                getSeriesValuesFromRange,
+                hiddenDimensionStrategy: spec.hiddenDimensionStrategy,
+            });
+            const headerTitle = getHierarchyHeaderTitle(spec, {
+                getDomainValuesFromRange,
+                getSeriesValuesFromRange,
+                hiddenDimensionStrategy: spec.hiddenDimensionStrategy,
+            });
+            hierarchyTitleRef.current = explicitChartTitle ?? headerTitle;
+            const hierarchyData = buildHierarchyTree(hierarchyRows);
+            const rootName = hierarchyData.length === 1 ? hierarchyData[0]?.name ?? "" : "";
+            const seriesDisplayName = explicitChartTitle ?? headerTitle ?? rootName ?? "";
+            const hierarchyDepth = getHierarchyDepth(hierarchyData);
+            const levels = buildHierarchyLevels(hierarchyDepth);
+            const tooltipFormatter = (params) => {
+                const value = Array.isArray(params.value)
+                    ? params.value[params.value.length - 1]
+                    : params.value ?? "";
+                return `${params.name}: ${value}`;
+            };
+            // Spec-level overrides — treemap/sunburst default to no legend,
+            // but an authored legend (visibility/position) still wins.
+            const hierarchySeriesLabel = buildSeriesLabelOption(spec.dataLabels);
+            chartRef.current?.setOption({
+                xAxis: [
+                    {
+                        type: "category",
+                        show: false,
+                    },
+                ],
+                yAxis: [
+                    {
+                        type: "value",
+                        show: false,
+                    },
+                ],
+                legend: applyLegendOverrides({ ...defaultLegendConfig, show: false }, spec.legend),
+                grid: {
+                    left: 0,
+                    right: 0,
+                    top: 0,
+                    bottom: 0,
+                },
+                tooltip: {
+                    trigger: "item",
+                    formatter: tooltipFormatter,
+                },
+                series: [
+                    {
+                        type: chartType,
+                        name: seriesDisplayName,
+                        rootName: rootName || seriesDisplayName || "",
+                        data: hierarchyData,
+                        label: {
+                            show: true,
+                            formatter: "{b}",
+                            ...(hierarchySeriesLabel ?? {}),
+                        },
+                        upperLabel: spec.chartType === "treemap"
+                            ? {
+                                show: true,
+                                padding: [0, 0, 0, 4],
+                            }
+                            : undefined,
+                        levels,
+                        colorMappingBy: "index",
+                    },
+                ],
+            }, {
+                replaceMerge: [
+                    "series",
+                    "xAxis",
+                    "yAxis",
+                    "legend",
+                    "grid",
+                    "tooltip",
+                ],
+            });
+            previousChartType.current = spec.chartType;
+            previousSeriesCount.current = 1;
+            return;
+        }
+        else {
+            hierarchyTitleRef.current = explicitChartTitle;
+        }
+        if (!isBasicChartSpec(spec)) {
+            debug("Unsupported chart type", spec.chartType);
+            return;
+        }
+        // ----------------------------- 3-D -----------------------------
+        // True 3-D rendering for degraded Excel 3-D / surface payloads,
+        // keyed off `sourceChartType` (see the gating block above):
+        // - BAR_3D  -> bar3D   (x = category, y = series row, z = value)
+        // - LINE_3D -> line3D  (one polyline per series at its depth row)
+        // - AREA_3D -> line3D  (echarts-gl has no area3D)
+        // - SURFACE / SURFACE_3D -> surface (values grid as z-heights)
+        // - PIE_3D never reaches here (echarts-gl has no pie3D; the 2-D pie
+        //   fallback renders instead — matching what Excel-degraded payloads
+        //   did before this pipeline existed).
+        if (willRender3D && threeDRenderKind) {
+            const categories = flattenChartDataValues(spec.domains, getDomainValuesFromRange, spec.hiddenDimensionStrategy, false).map((v) => String(v ?? ""));
+            const threeDSeriesInputs = [];
+            for (const seriesEntry of spec.series ?? []) {
+                const dataLabel = !isNil(seriesEntry.dataLabel) && isAFormula(seriesEntry.dataLabel)
+                    ? coerceCalculatedLabel(await onRequestCalculate(seriesEntry.dataLabel, position.sheetId ?? sheetId, position.overlayPosition.anchorCell.rowIndex, position.overlayPosition.anchorCell.columnIndex))
+                    : seriesEntry.dataLabel ?? "";
+                const values = flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, spec.hiddenDimensionStrategy).map(sanitizeChartValue);
+                threeDSeriesInputs.push({ name: dataLabel, values });
+            }
+            const seriesNames = threeDSeriesInputs.map((entry, index) => entry.name || `Series ${index + 1}`);
+            const threeDPalette = [
+                theme.themeColors.accent1,
+                theme.themeColors.accent2,
+                theme.themeColors.accent3,
+                theme.themeColors.accent4,
+                theme.themeColors.accent5,
+                theme.themeColors.accent6,
+            ];
+            const seriesColorAt = (index) => spec.series?.[index]?.color ??
+                threeDPalette[index % threeDPalette.length];
+            // Entering 3-D from a 2-D render: the cartesian option doesn't
+            // merge into a grid3D one, so re-initialize the echarts instance
+            // from scratch (theme options are re-applied after setOption).
+            if (!renderedIn3D.current && chartRef.current) {
+                chartRef.current.dispose();
+                chartRef.current = undefined;
+            }
+            if (el.current && !chartRef.current) {
+                chartRef.current = echarts.init(el.current);
+            }
+            // Value axes label integer positions with the category / series
+            // name they map to; fractional ticks stay blank.
+            const categoryAxisLabel = (value) => Number.isInteger(value) ? categories[value] ?? "" : "";
+            const seriesAxisLabel = (value) => Number.isInteger(value) ? seriesNames[value] ?? "" : "";
+            const threeDTooltipFormatter = (params) => {
+                const value = (params?.value ?? []);
+                const categoryLabel = categories[Math.round(value[0] ?? 0)] ?? String(value[0] ?? "");
+                const seriesLabel = seriesNames[Math.round(value[1] ?? 0)] ?? params?.seriesName ?? "";
+                return `${seriesLabel ? `${seriesLabel}<br/>` : ""}${categoryLabel}: ${value[2] ?? ""}`;
+            };
+            let threeDSeries;
+            let visualMap;
+            let xAxis3D;
+            let yAxis3D;
+            if (threeDRenderKind === "bar3D") {
+                xAxis3D = { type: "category", data: categories };
+                yAxis3D = { type: "category", data: seriesNames };
+                threeDSeries = [
+                    {
+                        type: "bar3D",
+                        shading: "lambert",
+                        data: buildBar3DData(threeDSeriesInputs).map(([x, y, z]) => ({
+                            value: [x, y, z],
+                            itemStyle: { color: seriesColorAt(y) },
+                        })),
+                    },
+                ];
+            }
+            else if (threeDRenderKind === "line3D") {
+                xAxis3D = {
+                    type: "value",
+                    axisLabel: { formatter: categoryAxisLabel },
+                    min: 0,
+                    max: Math.max(categories.length - 1, 1),
+                };
+                yAxis3D = {
+                    type: "value",
+                    axisLabel: { formatter: seriesAxisLabel },
+                    min: 0,
+                    max: Math.max(seriesNames.length - 1, 1),
+                };
+                threeDSeries = buildLine3DSeries(threeDSeriesInputs).map((entry, index) => ({
+                    type: "line3D",
+                    name: seriesNames[index],
+                    data: entry.data,
+                    lineStyle: { width: 3, color: seriesColorAt(index) },
+                }));
+            }
+            else {
+                const surfacePoints = buildSurfaceData(threeDSeriesInputs);
+                const [zMin, zMax] = getValueExtent(surfacePoints);
+                xAxis3D = {
+                    type: "value",
+                    axisLabel: { formatter: categoryAxisLabel },
+                    min: 0,
+                    max: Math.max(categories.length - 1, 1),
+                };
+                yAxis3D = {
+                    type: "value",
+                    axisLabel: { formatter: seriesAxisLabel },
+                    min: 0,
+                    max: Math.max(seriesNames.length - 1, 1),
+                };
+                threeDSeries = [
+                    {
+                        type: "surface",
+                        data: surfacePoints,
+                        wireframe: { show: true },
+                        shading: "color",
+                    },
+                ];
+                visualMap = {
+                    show: false,
+                    dimension: 2,
+                    min: zMin,
+                    max: zMax,
+                    seriesIndex: 0,
+                    inRange: { color: [...SURFACE_COLOR_RAMP] },
+                };
+            }
+            chartRef.current?.setOption({
+                tooltip: {
+                    textStyle: { fontSize: 12 },
+                    formatter: threeDTooltipFormatter,
+                },
+                legend: threeDRenderKind === "line3D"
+                    ? applyLegendOverrides({
+                        ...defaultLegendConfig,
+                        show: seriesNames.length > 1,
+                        data: seriesNames,
+                    }, spec.legend)
+                    : { show: false },
+                xAxis3D: { ...xAxis3D, name: spec.horizontalAxisTitle ?? "" },
+                yAxis3D: { ...yAxis3D, name: "" },
+                zAxis3D: { type: "value", name: spec.verticalAxisTitle ?? "" },
+                grid3D: {
+                    boxDepth: Math.max(20, Math.min(100, seriesNames.length * 20)),
+                    viewControl: { autoRotate: false },
+                },
+                ...(visualMap ? { visualMap: [visualMap] } : {}),
+                series: threeDSeries,
+            }, {
+                replaceMerge: [
+                    "series",
+                    "xAxis3D",
+                    "yAxis3D",
+                    "zAxis3D",
+                    "visualMap",
+                    "legend",
+                    "tooltip",
+                ],
+            });
+            // Re-apply theme-derived title / palette / tooltip colors — lost
+            // when the instance was re-initialized on entry into 3-D.
+            renderedIn3D.current = true;
+            applyThemeOptions();
+            previousChartType.current = spec.chartType;
+            previousSeriesCount.current = threeDSeries.length;
+            return;
+        }
+        // ---------------------------- Radar ----------------------------
+        // Radar is polar: a top-level `radar.indicator` list (one axis per
+        // category) plus one `radar`-type series carrying every data series'
+        // value vector. radarStyle controls markers / filled area.
+        if (spec.chartType === "radar") {
+            const skipHeaders = false;
+            const categories = flattenChartDataValues(spec.domains, getDomainValuesFromRange, spec.hiddenDimensionStrategy, skipHeaders);
+            const radarSeriesInputs = [];
+            for (const seriesEntry of spec.series ?? []) {
+                const label = seriesEntry.dataLabel && !isAFormula(seriesEntry.dataLabel)
+                    ? seriesEntry.dataLabel
+                    : "";
+                const values = flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, spec.hiddenDimensionStrategy).map((v) => (typeof v === "number" ? v : Number(v)));
+                radarSeriesInputs.push({ name: label, values });
+            }
+            const indicators = buildRadarIndicators(categories, radarSeriesInputs);
+            const radarData = buildRadarSeriesData(radarSeriesInputs, indicators.length);
+            const radarStyle = spec.radarStyle ?? "standard";
+            const radarColors = radarSeriesInputs.map((_, i) => spec.series?.[i]?.color);
+            // Spec-level overrides — radar is polar (no cartesian axes), so
+            // only legend + dataLabel overrides apply here.
+            const radarSeriesLabel = buildSeriesLabelOption(spec.dataLabels);
+            chartRef.current?.setOption({
+                radar: {
+                    indicator: indicators.length
+                        ? indicators
+                        : [{ name: "", max: 1 }],
+                },
+                legend: applyLegendOverrides({
+                    ...legend,
+                    show: radarData.length > 1,
+                    data: radarData.map((d) => d.name),
+                }, spec.legend),
+                tooltip: { trigger: "item" },
+                series: [
+                    {
+                        type: "radar",
+                        symbol: radarStyle === "standard" ? "none" : "circle",
+                        ...(radarSeriesLabel ? { label: radarSeriesLabel } : {}),
+                        data: radarData.map((d, i) => ({
+                            value: d.value,
+                            name: d.name,
+                            ...(radarStyle === "filled" ? { areaStyle: {} } : {}),
+                            ...(radarColors[i]
+                                ? {
+                                    itemStyle: { color: radarColors[i] },
+                                    lineStyle: { color: radarColors[i] },
+                                }
+                                : {}),
+                        })),
+                    },
+                ],
+            }, {
+                replaceMerge: [
+                    "series",
+                    "xAxis",
+                    "yAxis",
+                    "radar",
+                    "legend",
+                    "grid",
+                    "tooltip",
+                ],
+            });
+            previousChartType.current = spec.chartType;
+            previousSeriesCount.current = radarData.length;
+            return;
+        }
+        // ---------------------------- Stock ----------------------------
+        // Line-derived stock: fan the price-role series (open/high/low/close)
+        // out into separate line series over the category (date) domain. The
+        // V-variants additionally get a volume column sub-pane below the
+        // price plot.
+        if (spec.chartType === "stock") {
+            const variant = (spec.stockVariant ?? "HLC");
+            const categories = flattenChartDataValues(spec.domains, getDomainValuesFromRange, spec.hiddenDimensionStrategy, false).map((v) => String(v ?? ""));
+            const seriesValues = (spec.series ?? []).map((seriesEntry) => flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, spec.hiddenDimensionStrategy).map((v) => (typeof v === "number" ? v : Number(v))));
+            // Spec-level overrides — stock is cartesian, so axis min/max/
+            // visibility apply alongside legend + dataLabel toggles. They
+            // target the price plot's axes: the category-axis overrides land
+            // on the shared base x-axis (so both panes stay in sync when a
+            // volume pane exists), the value-axis overrides on the price
+            // pane's y-axis only — the volume pane keeps its own hidden-label
+            // value axis.
+            const stockSeriesLabel = buildSeriesLabelOption(spec.dataLabels);
+            // V-variants (VHLC / VOHLC) carry a volume series that renders as
+            // a column sub-pane under the price plot: two grids stacked
+            // vertically (price ~70% of the plot, volume below on its own
+            // value axis) with the category axes linked through axisPointer.
+            // Up days color like the candlestick body, down days like its
+            // shadow, so the panes read as one chart.
+            const upColor = theme.themeColors.accent1;
+            const downColor = theme.themeColors.accent2;
+            const volumePoints = toVolumeSeries(seriesValues, variant);
+            const hasVolume = (volumePoints?.length ?? 0) > 0;
+            const stockGrid = hasVolume
+                ? [
+                    { left: "10%", right: "4%", top: "8%", height: "56%" },
+                    { left: "10%", right: "4%", top: "74%", height: "18%" },
+                ]
+                : [{ left: "3%", right: "4%", bottom: "3%", containLabel: true }];
+            const baseStockXAxis = applyAxisOverrides({
+                type: "category",
+                data: categories,
+                show: true,
+                axisLine: { show: true },
+                axisTick: { show: true },
+                splitLine: { show: false },
+                name: spec.horizontalAxisTitle ?? "",
+                nameLocation: "middle",
+                nameGap: 30,
+            }, spec.categoryAxisOptions);
+            const stockXAxis = hasVolume
+                ? [
+                    // Price pane keeps its axis line but the shared category
+                    // labels + title live on the volume pane below. Spread after
+                    // the overridden base so the pane's labels stay hidden even
+                    // when the overrides carry an axisLabel text style.
+                    {
+                        ...baseStockXAxis,
+                        gridIndex: 0,
+                        axisLabel: { show: false },
+                        axisTick: { show: false },
+                        name: "",
+                    },
+                    { ...baseStockXAxis, gridIndex: 1 },
+                ]
+                : [baseStockXAxis];
+            const volumeYAxis = {
+                type: "value",
+                gridIndex: 1,
+                scale: true,
+                splitNumber: 2,
+                axisLabel: { show: false },
+                axisLine: { show: false },
+                axisTick: { show: false },
+                splitLine: { show: false },
+            };
+            const volumeSeries = hasVolume
+                ? [
+                    {
+                        type: "bar",
+                        name: "Volume",
+                        xAxisIndex: 1,
+                        yAxisIndex: 1,
+                        data: (volumePoints ?? []).map((p) => ({
+                            value: p.value,
+                            itemStyle: { color: p.up ? upColor : downColor },
+                        })),
+                    },
+                ]
+                : [];
+            // Link the panes' category axes so hovering either pane raises the
+            // axis pointer (and tooltip) across both. Cleared when no volume.
+            const stockAxisPointer = {
+                link: hasVolume ? [{ xAxisIndex: "all" }] : [],
+            };
+            // OHLC / VOHLC variants carry an `open`, so they render as a
+            // candlestick (Excel's open-high-low-close stock chart). HLC / VHLC
+            // (no open) fall through to the line-derived rendering below.
+            if (variant === "OHLC" || variant === "VOHLC") {
+                const candleData = toCandlestick(seriesValues, variant);
+                chartRef.current?.setOption({
+                    xAxis: stockXAxis,
+                    yAxis: [
+                        applyAxisOverrides({
+                            type: "value",
+                            show: true,
+                            scale: true,
+                            name: spec.verticalAxisTitle ?? "",
+                            nameLocation: "middle",
+                            nameGap: 50,
+                            gridIndex: 0,
+                        }, spec.valueAxisOptions),
+                        ...(hasVolume ? [volumeYAxis] : []),
+                    ],
+                    legend: applyLegendOverrides({ ...legend, show: false }, spec.legend),
+                    grid: stockGrid,
+                    tooltip: { trigger: "axis" },
+                    axisPointer: stockAxisPointer,
+                    series: [
+                        {
+                            type: "candlestick",
+                            name: spec.title || "Stock",
+                            data: candleData,
+                            itemStyle: {
+                                color: upColor,
+                                color0: downColor,
+                                borderColor: upColor,
+                                borderColor0: downColor,
+                            },
+                        },
+                        ...volumeSeries,
+                    ],
+                }, {
+                    replaceMerge: [
+                        "series",
+                        "xAxis",
+                        "yAxis",
+                        "legend",
+                        "grid",
+                        "tooltip",
+                    ],
+                });
+                previousChartType.current = spec.chartType;
+                previousSeriesCount.current = 1 + volumeSeries.length;
+                return;
+            }
+            const lineSeries = toLineSeries(seriesValues, variant);
+            const stockColors = [
+                theme.themeColors.accent1,
+                theme.themeColors.accent2,
+                theme.themeColors.accent3,
+                theme.themeColors.accent4,
+            ];
+            chartRef.current?.setOption({
+                xAxis: stockXAxis,
+                yAxis: [
+                    applyAxisOverrides({
+                        type: "value",
+                        show: true,
+                        name: spec.verticalAxisTitle ?? "",
+                        nameLocation: "middle",
+                        nameGap: 50,
+                        gridIndex: 0,
+                    }, spec.valueAxisOptions),
+                    ...(hasVolume ? [volumeYAxis] : []),
+                ],
+                legend: applyLegendOverrides({
+                    ...legend,
+                    show: lineSeries.length > 1,
+                    data: lineSeries.map((s) => s.name),
+                }, spec.legend),
+                grid: stockGrid,
+                tooltip: { trigger: "axis" },
+                axisPointer: stockAxisPointer,
+                series: [
+                    ...lineSeries.map((s, i) => ({
+                        type: "line",
+                        name: s.name,
+                        data: s.values,
+                        showSymbol: false,
+                        itemStyle: { color: stockColors[i % stockColors.length] },
+                        lineStyle: { color: stockColors[i % stockColors.length] },
+                        ...(stockSeriesLabel ? { label: stockSeriesLabel } : {}),
+                    })),
+                    ...volumeSeries,
+                ],
+            }, {
+                replaceMerge: [
+                    "series",
+                    "xAxis",
+                    "yAxis",
+                    "legend",
+                    "grid",
+                    "tooltip",
+                ],
+            });
+            previousChartType.current = spec.chartType;
+            previousSeriesCount.current = lineSeries.length + volumeSeries.length;
+            return;
+        }
+        const isStacked = spec.stackedType && spec.stackedType !== "UNSTACKED";
+        const isCircularChart = spec.chartType === "pie" || spec.chartType === "doughnut";
+        // Pie-of-pie / bar-of-pie composite. The of-pie branch below fills
+        // `ofPieLayout` so the grid/axis assembly at the bottom can add the
+        // secondary-bar grid and the 0-1 value axes the connector series
+        // needs.
+        const isOfPie = isCircularChart && isOfPieChartSpec(spec);
+        let ofPieLayout = null;
+        const isHorizontalBarChart = spec.chartType === "bar";
+        const shouldAggregate = shouldAggregateSeries(spec.series);
+        const primaryDomainSource = spec?.domains?.[0]?.sources?.[0];
+        const rawPrimaryDomainValues = primaryDomainSource
+            ? sanitizeDomainValues(getDomainValuesFromRange(primaryDomainSource, spec.hiddenDimensionStrategy) ?? [])
+            : [];
+        const aggregateDomainValues = getDomainValuesForAxis(rawPrimaryDomainValues, shouldAggregate);
+        spec.domains?.forEach((domain, domainIndex) => {
+            domain.sources.forEach((sheetRange, sourceIndex) => {
+                let axisData = [];
+                if (domainIndex === 0 && sourceIndex === 0) {
+                    axisData = aggregateDomainValues;
+                }
+                else {
+                    const rawValues = sanitizeDomainValues(getDomainValuesFromRange(sheetRange, spec.hiddenDimensionStrategy) ?? []);
+                    axisData = getDomainValuesForAxis(rawValues, shouldAggregate);
+                }
+                const axisTitle = domainIndex === 0 && sourceIndex === 0 && !isCircularChart
+                    ? isHorizontalBarChart
+                        ? spec.verticalAxisTitle ?? ""
+                        : spec.horizontalAxisTitle ?? ""
+                    : undefined;
+                chartDomains.push({
+                    type: "category",
+                    data: axisData,
+                    show: showAxis && !isCircularChart,
+                    axisLine: { show: !isCircularChart },
+                    axisTick: { show: !isCircularChart },
+                    splitLine: { show: !isCircularChart },
+                    name: axisTitle,
+                    nameLocation: "middle",
+                    nameGap: 30,
+                });
+            });
+        });
+        if (chartDomains.length === 0 && !isCircularChart) {
+            chartDomains.push({
+                type: "category",
+                show: showAxis,
+                axisLine: { show: true },
+                axisTick: { show: true },
+                splitLine: { show: true },
+                gridIndex: 0,
+                name: isHorizontalBarChart
+                    ? spec.verticalAxisTitle ?? ""
+                    : spec.horizontalAxisTitle ?? "",
+                nameLocation: "middle",
+                nameGap: 30,
+            });
+        }
+        // Trendline + error-bar overlays are extra series appended after the
+        // base series. The redraw/series-count accounting below derives from
+        // the final `chartSeries.length`, so these just push onto the array.
+        /**
+         * Append trendline and error-bar overlay series for one data series.
+         * `data` is the resolved numeric value array (may be number[] or
+         * objects with a `value` field for pie — overlays are skipped for
+         * non-numeric shapes).
+         */
+        const pushSeriesOverlays = (series, data, dataLabel) => {
+            const numericValues = Array.isArray(data)
+                ? data.map((v) => typeof v === "number"
+                    ? v
+                    : v && typeof v === "object" && "value" in v
+                        ? v.value
+                        : Number(v))
+                : [];
+            if (numericValues.length === 0)
+                return;
+            const seriesColor = series.color ?? theme.themeColors.accent1;
+            const useSecondary = series.useSecondaryAxis ? { yAxisIndex: 1 } : {};
+            // Trendlines — one overlay line series per spec.
+            for (const tl of series.trendlines ?? []) {
+                const result = computeTrendline(numericValues, {
+                    type: tl.type,
+                    order: tl.order,
+                    period: tl.period,
+                    forecastForward: tl.forecastForward,
+                    forecastBackward: tl.forecastBackward,
+                });
+                if (!result || result.points.length < 2)
+                    continue;
+                const tlName = tl.name ??
+                    `${dataLabel ? dataLabel + " " : ""}${tl.type ?? "linear"} trend`;
+                chartSeries.push({
+                    type: "line",
+                    name: tlName,
+                    // Index x lets the trendline overlay the category axis even
+                    // when forecasting extends beyond the data range.
+                    data: result.points.map((p) => [p.x, p.y]),
+                    showSymbol: false,
+                    smooth: tl.type === "poly",
+                    lineStyle: {
+                        color: tl.color ?? seriesColor,
+                        type: "dashed",
+                        width: 2,
+                    },
+                    itemStyle: { color: tl.color ?? seriesColor },
+                    tooltip: { show: false },
+                    z: 5,
+                    ...useSecondary,
+                });
+            }
+            // Error bars — drawn as a custom series of vertical/horizontal
+            // whiskers. valueType "custom" reads per-point magnitudes from the
+            // spec's plus/minus ranges, resolved through the same extractor
+            // the series values use.
+            const magnitudes = computeErrorBars(numericValues, resolveCustomErrorBarValues(series.errorBars, (range) => getSeriesValuesFromRange(range, spec.hiddenDimensionStrategy)));
+            if (magnitudes) {
+                const direction = series.errorBars?.direction ?? "y";
+                const noEndCap = series.errorBars?.noEndCap ?? false;
+                const errorData = numericValues.map((v, i) => [
+                    i,
+                    typeof v === "number" ? v : 0,
+                    magnitudes.plus[i] ?? 0,
+                    magnitudes.minus[i] ?? 0,
+                ]);
+                chartSeries.push({
+                    type: "custom",
+                    name: `${dataLabel ? dataLabel + " " : ""}error`,
+                    data: errorData,
+                    z: 6,
+                    tooltip: { show: false },
+                    ...useSecondary,
+                    renderItem: (_params, api) => {
+                        const value = api.value(1);
+                        const plus = api.value(2);
+                        const minus = api.value(3);
+                        const capHalf = 5;
+                        if (direction === "x") {
+                            const center = api.coord([value, api.value(0)]);
+                            const hi = api.coord([value + plus, api.value(0)]);
+                            const lo = api.coord([value - minus, api.value(0)]);
+                            const children = [
+                                {
+                                    type: "line",
+                                    shape: { x1: lo[0], y1: center[1], x2: hi[0], y2: center[1] },
+                                    style: { stroke: seriesColor, lineWidth: 1 },
+                                },
+                            ];
+                            if (!noEndCap) {
+                                children.push({
+                                    type: "line",
+                                    shape: {
+                                        x1: hi[0],
+                                        y1: center[1] - capHalf,
+                                        x2: hi[0],
+                                        y2: center[1] + capHalf,
+                                    },
+                                    style: { stroke: seriesColor, lineWidth: 1 },
+                                }, {
+                                    type: "line",
+                                    shape: {
+                                        x1: lo[0],
+                                        y1: center[1] - capHalf,
+                                        x2: lo[0],
+                                        y2: center[1] + capHalf,
+                                    },
+                                    style: { stroke: seriesColor, lineWidth: 1 },
+                                });
+                            }
+                            return { type: "group", children };
+                        }
+                        const center = api.coord([api.value(0), value]);
+                        const hi = api.coord([api.value(0), value + plus]);
+                        const lo = api.coord([api.value(0), value - minus]);
+                        const children = [
+                            {
+                                type: "line",
+                                shape: { x1: center[0], y1: lo[1], x2: center[0], y2: hi[1] },
+                                style: { stroke: seriesColor, lineWidth: 1 },
+                            },
+                        ];
+                        if (!noEndCap) {
+                            children.push({
+                                type: "line",
+                                shape: {
+                                    x1: center[0] - capHalf,
+                                    y1: hi[1],
+                                    x2: center[0] + capHalf,
+                                    y2: hi[1],
+                                },
+                                style: { stroke: seriesColor, lineWidth: 1 },
+                            }, {
+                                type: "line",
+                                shape: {
+                                    x1: center[0] - capHalf,
+                                    y1: lo[1],
+                                    x2: center[0] + capHalf,
+                                    y2: lo[1],
+                                },
+                                style: { stroke: seriesColor, lineWidth: 1 },
+                            });
+                        }
+                        return { type: "group", children };
+                    },
+                });
+            }
+        };
+        // Excel `<c:overlap>` / `<c:gapWidth>` → echarts barGap /
+        // barCategoryGap (see utils/bar-layout.ts for the exact mapping).
+        // The category-gap conversion needs the number of side-by-side bars
+        // per category slot: 1 when stacked (all series share the slot),
+        // otherwise the count of rendered bar/column series.
+        const sideBySideBarCount = isStacked
+            ? 1
+            : (spec.series ?? []).reduce((count, s) => {
+                const seriesType = s.seriesChartType ?? spec.chartType;
+                return seriesType === "bar" || seriesType === "column"
+                    ? count + Math.max(1, s.sources?.length ?? 0)
+                    : count;
+            }, 0);
+        const specBarGap = overlapToBarGap(spec.overlap);
+        const specBarCategoryGap = gapWidthToBarCategoryGap(spec.gapWidth, {
+            seriesCount: sideBySideBarCount,
+            overlap: isStacked ? 0 : spec.overlap,
+        });
+        for (const series of spec.series ?? []) {
+            const dataLabel = !isNil(series.dataLabel) && isAFormula(series.dataLabel)
+                ? coerceCalculatedLabel(await onRequestCalculate(series.dataLabel, position.sheetId ?? sheetId, position.overlayPosition.anchorCell.rowIndex, position.overlayPosition.anchorCell.columnIndex))
+                : series.dataLabel ?? "";
+            // Label
+            if (dataLabel) {
+                legend.data?.push(dataLabel);
+            }
+            for (const sheetRange of series.sources) {
+                const data = getSeriesData(spec, sheetRange, {
+                    aggregateEnabled: shouldAggregate,
+                    aggregateType: series.aggregateType,
+                    rawDomainValues: rawPrimaryDomainValues,
+                    orderedDomainValues: aggregateDomainValues,
+                });
+                // Support per-series chart type for combo charts
+                const effectiveChartType = series.seriesChartType ?? spec.chartType;
+                const seriesEchartsType = chartTypeToEchartsType(effectiveChartType);
+                const seriesStyleAttrs = getEchartsSeriesStyle(effectiveChartType);
+                const seriesEntry = {
+                    type: seriesEchartsType,
+                    name: dataLabel,
+                    data,
+                    stack: isStacked ? "dataLabel" : undefined,
+                    smooth: spec.smooth ?? undefined,
+                    radius: spec.radius ?? (isCircularChart ? [0, "75%"] : undefined),
+                    ...seriesStyleAttrs,
+                };
+                // Plot this series against a secondary value axis. The 2nd
+                // yAxis element is appended below (when any series opts in);
+                // here we point the series at index 1.
+                if (series.useSecondaryAxis) {
+                    seriesEntry.yAxisIndex = 1;
+                }
+                // Handle invertIfNegative for bar/column charts
+                const isBarOrColumn = effectiveChartType === "bar" || effectiveChartType === "column";
+                // Bar layout (overlap/gapWidth) — echarts reads barGap /
+                // barCategoryGap from bar series (the last bar series wins for
+                // the whole coordinate system), so apply them to every
+                // bar/column series. Set before the gradient/noFill branches so
+                // every push path carries them.
+                if (isBarOrColumn) {
+                    if (specBarGap !== undefined) {
+                        seriesEntry.barGap = specBarGap;
+                    }
+                    if (specBarCategoryGap !== undefined) {
+                        seriesEntry.barCategoryGap = specBarCategoryGap;
+                    }
+                }
+                const seriesAny = series;
+                // Gradient fill — overrides solid color when present. echarts
+                // paints it natively via a LinearGradient on itemStyle.color
+                // (and areaStyle for area series / lineStyle for lines).
+                const gradientArgs = gradientToEcharts(series.gradient);
+                if (gradientArgs && !seriesAny.noFill) {
+                    const gradient = new echarts.graphic.LinearGradient(gradientArgs.x, gradientArgs.y, gradientArgs.x2, gradientArgs.y2, gradientArgs.colorStops);
+                    seriesEntry.itemStyle = {
+                        ...(seriesEntry.itemStyle ?? {}),
+                        color: gradient,
+                    };
+                    if (effectiveChartType === "area") {
+                        seriesEntry.areaStyle = {
+                            ...(seriesEntry.areaStyle ?? {}),
+                            color: gradient,
+                        };
+                    }
+                    chartSeries.push(seriesEntry);
+                    pushSeriesOverlays(series, data, dataLabel);
+                    continue;
+                }
+                if (seriesAny.noFill) {
+                    // Transparent series (Gantt lag offset, etc.) — fill it
+                    // with `transparent` so layout is preserved but nothing
+                    // paints. Legend entries are also suppressed via `name: ""`
+                    // since the series carries no semantic information.
+                    seriesEntry.itemStyle = {
+                        ...(seriesEntry.itemStyle ?? {}),
+                        color: "transparent",
+                        borderColor: "transparent",
+                    };
+                }
+                else if (isBarOrColumn &&
+                    Array.isArray(seriesAny.dataPointColors) &&
+                    seriesAny.dataPointColors.length) {
+                    // Per-data-point color overrides — Gantt-style charts colour
+                    // each task differently via `<c:dPt>`. Echarts accepts an
+                    // `itemStyle.color` function that receives the data index;
+                    // we look up the override or fall back to the series color.
+                    const overrides = new Map();
+                    for (const dp of seriesAny.dataPointColors) {
+                        if (typeof dp.idx === "number" && typeof dp.color === "string") {
+                            overrides.set(dp.idx, dp.color);
+                        }
+                    }
+                    const fallback = series.color ?? theme.themeColors.accent1;
+                    seriesEntry.itemStyle = {
+                        ...(seriesEntry.itemStyle ?? {}),
+                        color: (params) => overrides.get(params.dataIndex) ?? fallback,
+                    };
+                }
+                else if (isBarOrColumn && series.invertIfNegative) {
+                    const positiveColor = series.color ?? theme.themeColors.accent1;
+                    const negativeColor = series.negativeColor ?? "#FF0000";
+                    // Use a color function that returns different colors based on value
+                    seriesEntry.itemStyle = {
+                        ...(seriesEntry.itemStyle ?? {}),
+                        color: (params) => {
+                            const value = Array.isArray(params.data)
+                                ? params.data[1]
+                                : params.data?.value ?? params.data;
+                            return typeof value === "number" && value < 0
+                                ? negativeColor
+                                : positiveColor;
+                        },
+                    };
+                }
+                else if (series.color) {
+                    seriesEntry.itemStyle = {
+                        ...(seriesEntry.itemStyle ?? {}),
+                        color: series.color,
+                    };
+                    seriesEntry.lineStyle = {
+                        ...(seriesEntry.lineStyle ?? {}),
+                        color: series.color,
+                    };
+                    if (effectiveChartType === "area") {
+                        seriesEntry.areaStyle = {
+                            ...(seriesEntry.areaStyle ?? {}),
+                            color: series.color,
+                        };
+                    }
+                }
+                chartSeries.push(seriesEntry);
+                pushSeriesOverlays(series, data, dataLabel);
+            }
+        }
+        if (isOfPie) {
+            // Pie-of-pie / bar-of-pie — Excel splits the minor slices into a
+            // secondary pie or stacked bar beside the main pie, replaces them
+            // with an aggregated "Other" slice, and joins the two plots with
+            // connector lines. The split rule comes from splitType/splitPos
+            // (default: last 3 categories) and the secondary plot's size from
+            // secondPieSize (percent of the main pie, default 75).
+            const labels = rawPrimaryDomainValues.map((v) => String(v ?? ""));
+            const seriesEntry = spec.series?.[0];
+            const rawValues = seriesEntry
+                ? flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, spec.hiddenDimensionStrategy).map((v) => (typeof v === "number" ? v : Number(v)))
+                : [];
+            const { main, secondary, otherTotal, total } = splitOfPie(rawValues, labels, {
+                splitType: spec.splitType,
+                splitPos: spec.splitPos,
+            });
+            const ofPieType = resolveOfPieType(spec.ofPieType);
+            const secondScale = clampSecondPieSize(spec.secondPieSize) / 100;
+            const halfAngle = otherSliceHalfAngle(otherTotal, total);
+            const hasSecondary = secondary.length > 0;
+            // Layout, as fractions of the chart container. The main pie sits
+            // left-of-center; the secondary plot on the right. Pie radii are
+            // echarts-style percentages of min(width, height) / 2.
+            const MAIN_CX = 0.3;
+            const CY = 0.5;
+            const MAIN_RADIUS_PCT = 55;
+            const SECONDARY_CX = 0.78;
+            const secondaryRadiusPct = Math.min(80, MAIN_RADIUS_PCT * secondScale);
+            const BAR_LEFT = 0.68;
+            const BAR_RIGHT = 0.88;
+            // Bar-of-pie: the stacked bar's height tracks secondPieSize the
+            // same way the secondary pie's diameter does.
+            const barHalfFrac = Math.min(0.45, Math.max(0.08, 0.28 * secondScale));
+            ofPieLayout = {
+                ofPieType,
+                hasSecondary,
+                barGrid: ofPieType === "bar" && hasSecondary
+                    ? {
+                        left: `${BAR_LEFT * 100}%`,
+                        right: `${(1 - BAR_RIGHT) * 100}%`,
+                        top: `${(CY - barHalfFrac) * 100}%`,
+                        bottom: `${(1 - CY - barHalfFrac) * 100}%`,
+                    }
+                    : undefined,
+            };
+            chartDomains.length = 0;
+            chartSeries.length = 0;
+            // Palette continues from the main plot into the secondary one so
+            // slices keep distinct colors across both plots (Excel behavior).
+            const ofPiePalette = [
+                theme.themeColors.accent1,
+                theme.themeColors.accent2,
+                theme.themeColors.accent3,
+                theme.themeColors.accent4,
+                theme.themeColors.accent5,
+                theme.themeColors.accent6,
+            ];
+            const paletteAt = (index) => ofPiePalette[index % ofPiePalette.length];
+            chartSeries.push({
+                type: "pie",
+                name: seriesEntry?.dataLabel ?? "",
+                center: [`${MAIN_CX * 100}%`, `${CY * 100}%`],
+                radius: [0, `${MAIN_RADIUS_PCT}%`],
+                // Rotate the pie so the "Other" slice's angular midpoint faces
+                // the secondary plot (Excel's layout). Slices sweep clockwise
+                // and Other is last, ending the sweep at startAngle; putting
+                // the midpoint at 0° (3 o'clock) needs startAngle 360 - 180f.
+                startAngle: 360 - (halfAngle * 180) / Math.PI,
+                data: main.map((s, i) => ({
+                    name: s.label,
+                    value: s.value,
+                    itemStyle: { color: paletteAt(i) },
+                })),
+            });
+            if (hasSecondary) {
+                if (ofPieType === "pie") {
+                    chartSeries.push({
+                        type: "pie",
+                        name: seriesEntry?.dataLabel ?? "",
+                        center: [`${SECONDARY_CX * 100}%`, `${CY * 100}%`],
+                        radius: [0, `${secondaryRadiusPct}%`],
+                        data: secondary.map((s, i) => ({
+                            name: s.label,
+                            value: s.value,
+                            itemStyle: { color: paletteAt(main.length + i) },
+                        })),
+                    });
+                }
+                else {
+                    // Bar-of-pie — a single-category stacked bar on the second
+                    // grid, one series per point so each segment keeps its own
+                    // color, legend entry and tooltip.
+                    secondary.forEach((s, i) => {
+                        chartSeries.push({
+                            type: "bar",
+                            name: s.label,
+                            stack: "rnc-of-pie-secondary",
+                            xAxisIndex: 1,
+                            yAxisIndex: 1,
+                            barWidth: "75%",
+                            data: [s.value],
+                            itemStyle: { color: paletteAt(main.length + i) },
+                            tooltip: { formatter: "{a}: {c}" },
+                        });
+                    });
+                }
+                // Connector lines from the Other slice's edges to the secondary
+                // plot, drawn by a custom series over hidden 0-1 value axes so
+                // they re-render on resize. Geometry mirrors the fractions used
+                // for the pie centers/radii above.
+                const connectorColor = isDarkMode
+                    ? "rgba(255,255,255,0.45)"
+                    : "#999999";
+                chartSeries.push({
+                    type: "custom",
+                    name: "",
+                    silent: true,
+                    animation: false,
+                    tooltip: { show: false },
+                    z: 1,
+                    data: [[0, 0]],
+                    renderItem: (params) => {
+                        const cs = params?.coordSys ?? {};
+                        const width = cs.width ?? 0;
+                        const height = cs.height ?? 0;
+                        if (!(width > 0) || !(height > 0)) {
+                            return { type: "group", children: [] };
+                        }
+                        const x0 = cs.x ?? 0;
+                        const y0 = cs.y ?? 0;
+                        const r = ((MAIN_RADIUS_PCT / 100) * Math.min(width, height)) / 2;
+                        const cx = x0 + MAIN_CX * width;
+                        const cy = y0 + CY * height;
+                        // Boundary points of the Other slice on the main circle —
+                        // ±halfAngle around 3 o'clock (screen y grows downwards).
+                        const px = cx + r * Math.cos(halfAngle);
+                        const pyTop = cy - r * Math.sin(halfAngle);
+                        const pyBottom = cy + r * Math.sin(halfAngle);
+                        let tx;
+                        let tyTop;
+                        let tyBottom;
+                        if (ofPieType === "pie") {
+                            const r2 = ((secondaryRadiusPct / 100) * Math.min(width, height)) / 2;
+                            tx = x0 + SECONDARY_CX * width;
+                            tyTop = cy - r2;
+                            tyBottom = cy + r2;
+                        }
+                        else {
+                            tx = x0 + BAR_LEFT * width;
+                            tyTop = y0 + (CY - barHalfFrac) * height;
+                            tyBottom = y0 + (CY + barHalfFrac) * height;
+                        }
+                        const style = { stroke: connectorColor, lineWidth: 1 };
+                        return {
+                            type: "group",
+                            children: [
+                                {
+                                    type: "line",
+                                    shape: { x1: px, y1: pyTop, x2: tx, y2: tyTop },
+                                    style,
+                                },
+                                {
+                                    type: "line",
+                                    shape: { x1: px, y1: pyBottom, x2: tx, y2: tyBottom },
+                                    style,
+                                },
+                            ],
+                        };
+                    },
+                });
+            }
+            // Legend lists every category (main + secondary); the Other slice
+            // only exists in the main pie.
+            legend.data = [
+                ...main.map((s) => s.label),
+                ...secondary.map((s) => s.label),
+            ];
+        }
+        else if (spec.chartType === "waterfall") {
+            const primaryDomainSource = spec?.domains?.[0]?.sources?.[0];
+            const rawDomainValues = primaryDomainSource
+                ? sanitizeDomainValues(getDomainValuesFromRange(primaryDomainSource, spec.hiddenDimensionStrategy) ?? [])
+                : [];
+            const labels = rawDomainValues.map((v) => String(v ?? ""));
+            const seriesEntry = spec.series?.[0];
+            const rawValues = seriesEntry
+                ? flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, spec.hiddenDimensionStrategy).map((v) => (typeof v === "number" ? v : Number(v)))
+                : [];
+            const totalIndices = new Set(spec.totalIndices ?? []);
+            const steps = computeWaterfall(rawValues, labels, totalIndices);
+            chartDomains.length = 0;
+            chartDomains.push({
+                type: "category",
+                data: steps.map((s) => s.label),
+                show: showAxis,
+                axisLine: { show: true },
+                axisTick: { show: true },
+                splitLine: { show: false },
+                name: spec.horizontalAxisTitle ?? "",
+                nameLocation: "middle",
+                nameGap: 30,
+            });
+            chartSeries.length = 0;
+            chartSeries.push({
+                type: "bar",
+                stack: "waterfall",
+                itemStyle: { color: "transparent" },
+                emphasis: { itemStyle: { color: "transparent" } },
+                data: steps.map((s) => s.placeholder),
+                silent: true,
+            });
+            const accent = seriesEntry?.color ?? theme.themeColors.accent1;
+            const decreaseColor = seriesEntry?.negativeColor ?? theme.themeColors.accent2 ?? accent;
+            const totalColor = theme.themeColors.accent3 ?? accent;
+            // Excel-style connector lines: a horizontal segment at the running
+            // total after bar i, spanning across to bar i+1. Within the bars
+            // the segment overlaps their top/bottom edges, so only the gap
+            // between bars is visually distinct.
+            const connectors = steps.slice(0, -1).map((s, i) => [
+                { coord: [i, s.cumulative] },
+                { coord: [i + 1, s.cumulative] },
+            ]);
+            chartSeries.push({
+                type: "bar",
+                stack: "waterfall",
+                name: seriesEntry?.dataLabel ?? "",
+                data: steps.map((s, i) => ({
+                    value: s.value,
+                    itemStyle: {
+                        color: s.isTotal
+                            ? totalColor
+                            : rawValues[i] < 0
+                                ? decreaseColor
+                                : accent,
+                    },
+                })),
+                markLine: {
+                    silent: true,
+                    symbol: "none",
+                    animation: false,
+                    label: { show: false },
+                    lineStyle: {
+                        color: isDarkMode ? "rgba(255,255,255,0.45)" : "#999999",
+                        width: 1,
+                        type: "solid",
+                    },
+                    data: connectors,
+                },
+            });
+            legend.data = [];
+        }
+        else if (spec.chartType === "funnel") {
+            const primaryDomainSource = spec?.domains?.[0]?.sources?.[0];
+            const rawDomainValues = primaryDomainSource
+                ? sanitizeDomainValues(getDomainValuesFromRange(primaryDomainSource, spec.hiddenDimensionStrategy) ?? [])
+                : [];
+            const labels = rawDomainValues.map((v) => String(v ?? ""));
+            const seriesEntry = spec.series?.[0];
+            const rawValues = seriesEntry
+                ? flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, spec.hiddenDimensionStrategy).map((v) => (typeof v === "number" ? v : 0))
+                : [];
+            chartDomains.length = 0;
+            chartSeries.length = 0;
+            chartSeries.push({
+                type: "funnel",
+                name: seriesEntry?.dataLabel ?? "",
+                data: rawValues.map((value, i) => ({
+                    name: labels[i] ?? String(i),
+                    value,
+                })),
+                label: { show: true, position: "inside" },
+            });
+            legend.data = [];
+        }
+        else if (spec.chartType === "boxplot") {
+            const quartileMethod = spec.quartileMethod;
+            const showOutliers = spec.showOutliers;
+            const showMeanMarker = spec.showMeanMarker === true;
+            const boxStats = [];
+            const boxLabels = [];
+            // [categoryIndex, value] pairs for the outlier / mean overlay
+            // scatter series (only populated when the options are on).
+            const outlierPoints = [];
+            const meanPoints = [];
+            for (const seriesEntry of spec.series ?? []) {
+                const label = seriesEntry.dataLabel && !isAFormula(seriesEntry.dataLabel)
+                    ? seriesEntry.dataLabel
+                    : "";
+                const rawValues = flattenChartDataValues([seriesEntry], getSeriesValuesFromRange, spec.hiddenDimensionStrategy).map((v) => (typeof v === "number" ? v : Number(v)));
+                const summary = computeBoxplotSummary(rawValues, { quartileMethod });
+                if (summary) {
+                    const boxIndex = boxStats.length;
+                    // `showOutliers === true` clips the whiskers to the most
+                    // extreme data points inside the 1.5×IQR fences and plots
+                    // the points beyond them (Excel's "show outlier points").
+                    // Otherwise the whiskers span the full min/max — today's
+                    // rendering.
+                    const lo = showOutliers === true ? summary.lowerWhisker : summary.min;
+                    const hi = showOutliers === true ? summary.upperWhisker : summary.max;
+                    boxStats.push([lo, summary.q1, summary.median, summary.q3, hi]);
+                    boxLabels.push(label);
+                    if (showOutliers === true) {
+                        for (const outlier of summary.outliers) {
+                            outlierPoints.push([boxIndex, outlier]);
+                        }
+                    }
+                    if (showMeanMarker) {
+                        meanPoints.push([boxIndex, summary.mean]);
+                    }
+                }
+            }
+            chartDomains.length = 0;
+            chartDomains.push({
+                type: "category",
+                data: boxLabels,
+                show: showAxis,
+                axisLine: { show: true },
+                axisTick: { show: true },
+                splitLine: { show: false },
+                name: spec.horizontalAxisTitle ?? "",
+                nameLocation: "middle",
+                nameGap: 30,
+            });
+            chartSeries.length = 0;
+            const boxSeries = {
+                type: "boxplot",
+                name: "",
+                data: boxStats,
+            };
+            const boxColor = spec.series?.[0]?.color;
+            if (boxColor) {
+                boxSeries.itemStyle = { color: boxColor, borderColor: boxColor };
+            }
+            chartSeries.push(boxSeries);
+            if (outlierPoints.length > 0) {
+                chartSeries.push({
+                    type: "scatter",
+                    name: "",
+                    data: outlierPoints,
+                    symbolSize: 6,
+                    ...(boxColor ? { itemStyle: { color: boxColor } } : {}),
+                    tooltip: { show: false },
+                });
+            }
+            if (meanPoints.length > 0) {
+                chartSeries.push({
+                    type: "scatter",
+                    name: "",
+                    data: meanPoints,
+                    symbol: "diamond",
+                    symbolSize: 9,
+                    ...(boxColor ? { itemStyle: { color: boxColor } } : {}),
+                    tooltip: { show: false },
+                });
+            }
+            legend.data = [];
+        }
+        else if (spec.chartType === "histogram") {
+            const rawValues = flattenChartDataValues(spec.series, getSeriesValuesFromRange, spec.hiddenDimensionStrategy).map((v) => (typeof v === "number" ? v : Number(v)));
+            let { labels, counts } = binHistogram(rawValues, spec.binCount);
+            // Pareto — a histogram whose bins are sorted descending with a
+            // cumulative-% line overlaid on a secondary 0-100% axis. The
+            // authored type arrives as `sourceChartType: "PARETO"` on an
+            // otherwise plain histogram spec.
+            const isPareto = isParetoSpec(spec);
+            let cumulativePercents = [];
+            if (isPareto) {
+                const pareto = computePareto({ labels, counts });
+                labels = pareto.labels;
+                counts = pareto.counts;
+                cumulativePercents = pareto.cumulativePercents;
+            }
+            chartDomains.length = 0;
+            chartDomains.push({
+                type: "category",
+                data: labels,
+                show: showAxis,
+                axisLine: { show: true },
+                axisTick: { show: true },
+                splitLine: { show: false },
+                name: spec.horizontalAxisTitle ?? "",
+                nameLocation: "middle",
+                nameGap: 30,
+            });
+            chartSeries.length = 0;
+            const histogramSeries = {
+                type: "bar",
+                name: spec.series?.[0]?.dataLabel ?? "",
+                data: counts,
+                barCategoryGap: "1%",
+            };
+            const histogramColor = spec.series?.[0]?.color;
+            if (histogramColor) {
+                histogramSeries.itemStyle = { color: histogramColor };
+            }
+            chartSeries.push(histogramSeries);
+            if (isPareto) {
+                // Cumulative-% overlay on the secondary axis (yAxisIndex 1);
+                // the matching 0-100% axis element is appended with the other
+                // value axes below.
+                chartSeries.push({
+                    type: "line",
+                    name: "Cumulative %",
+                    data: cumulativePercents,
+                    yAxisIndex: 1,
+                    symbol: "circle",
+                    symbolSize: 6,
+                });
+            }
+            legend.data = [];
+        }
+        // Only redraw chart
+        // if chart type has changed
+        // if series count has changed. Use the rendered series count
+        // (`chartSeries.length`) rather than `spec.series.length` because
+        // trendline / error-bar overlays add extra series; comparing the
+        // raw spec count would miss those and skip the structural redraw.
+        const renderedSeriesCount = chartSeries.length;
+        const replaceMerge = previousChartType.current !== spec.chartType ||
+            previousSeriesCount.current !== renderedSeriesCount
+            ? ["series", "xAxis", "yAxis", "legend", "grid", "tooltip"]
+            : [];
+        // Of-pie uses a full-container grid (for the connector overlay's
+        // hidden 0-1 axes) plus, for bar-of-pie, a second grid hosting the
+        // stacked secondary bar.
+        const gridConfig = isOfPie
+            ? [
+                { left: 0, right: 0, top: 0, bottom: 0 },
+                ...(ofPieLayout?.barGrid ? [ofPieLayout.barGrid] : []),
+            ]
+            : isCircularChart
+                ? {
+                    left: 0,
+                    right: 0,
+                    top: 0,
+                    bottom: 0,
+                }
+                : {
+                    left: "3%",
+                    right: "4%",
+                    bottom: "3%",
+                    containLabel: true,
+                };
+        const valueAxisBase = {
+            type: "value",
+            show: !isCircularChart,
+            axisLine: { show: !isCircularChart },
+            axisTick: { show: !isCircularChart },
+            splitLine: { show: !isCircularChart },
+            nameLocation: "middle",
+            nameGap: 50,
+        };
+        // Secondary (right-hand) value axis. Series with useSecondaryAxis
+        // were pointed at yAxisIndex 1 in the loop above; the matching axis
+        // element is appended here. Pareto histograms always carry one for
+        // the cumulative-% line, clamped to 0-100%.
+        const isPareto = spec.chartType === "histogram" && isParetoSpec(spec);
+        const hasSecondaryAxis = !isCircularChart &&
+            !isHorizontalBarChart &&
+            ((spec.series ?? []).some((s) => s.useSecondaryAxis) || isPareto);
+        const tooltipConfig = {
+            textStyle: {
+                fontSize: 12,
+            },
+            trigger: isCircularChart ? "item" : "axis",
+            formatter: isCircularChart ? "{b}: {c} ({d}%)" : undefined,
+        };
+        // Phase 5.1: apply legend / axis / dataLabels / doughnut overrides.
+        const finalLegend = applyLegendOverrides(legend, spec.legend);
+        const seriesLabelOption = buildSeriesLabelOption(spec.dataLabels);
+        // For doughnut, surface the inner-radius hole on each pie series.
+        // Excel persists `holeSize` as a 0-90 percentage; we normalize to a
+        // 0-1 fraction (doughnutHoleSize). Default to 0.5 when unset.
+        const isDoughnut = spec.chartType === "doughnut";
+        const doughnutHoleSize = spec.doughnutHoleSize;
+        // PERCENT_STACKED — echarts has no built-in `barnorm: 'percent'`,
+        // so we normalize per category here: each cell becomes
+        // (value / category_total) * 100, while the original value is
+        // tucked into a sibling field so the label formatter can still
+        // surface the dollar amount. Touches only bar/column series in
+        // the percent-stacked spec; other charts pass through unchanged.
+        if (spec.stackedType === "PERCENT_STACKED" &&
+            (spec.chartType === "bar" || spec.chartType === "column")) {
+            const barSeries = chartSeries.filter((s) => s?.type === "bar");
+            // Length of the value axis = max length across stacked series.
+            const len = barSeries.reduce((m, s) => Math.max(m, Array.isArray(s.data) ? s.data.length : 0), 0);
+            const categoryTotals = new Array(len).fill(0);
+            for (const s of barSeries) {
+                if (!Array.isArray(s.data))
+                    continue;
+                for (let i = 0; i < s.data.length; i++) {
+                    const raw = s.data[i];
+                    const n = typeof raw === "number" ? raw : Number(raw);
+                    if (Number.isFinite(n))
+                        categoryTotals[i] += n;
+                }
+            }
+            for (const s of barSeries) {
+                if (!Array.isArray(s.data))
+                    continue;
+                s.data = s.data.map((raw, i) => {
+                    const n = typeof raw === "number" ? raw : Number(raw);
+                    const total = categoryTotals[i];
+                    if (!Number.isFinite(n) || total === 0) {
+                        return { value: 0, originalValue: raw };
+                    }
+                    return { value: (n / total) * 100, originalValue: n };
+                });
+            }
+        }
+        const seriesWithLabels = chartSeries.map((s) => {
+            const next = { ...s };
+            if (seriesLabelOption) {
+                next.label = { ...(s?.label ?? {}), ...seriesLabelOption };
+            }
+            if (isDoughnut && next.type === "pie") {
+                const inner = typeof doughnutHoleSize === "number"
+                    ? Math.round(Math.max(0, Math.min(0.9, doughnutHoleSize)) * 100)
+                    : 50;
+                next.radius = [`${inner}%`, "75%"];
+            }
+            return next;
+        });
+        // Update charts
+        chartRef.current?.setOption({
+            xAxis: (() => {
+                if (isOfPie) {
+                    // Hidden 0-1 value axis on the full-container grid for the
+                    // connector overlay, plus a hidden single-category axis on
+                    // the secondary grid for bar-of-pie.
+                    const axes = [
+                        {
+                            type: "value",
+                            min: 0,
+                            max: 1,
+                            show: false,
+                            axisLine: { show: false },
+                            axisTick: { show: false },
+                            splitLine: { show: false },
+                        },
+                    ];
+                    if (ofPieLayout?.barGrid) {
+                        axes.push({
+                            type: "category",
+                            data: [""],
+                            gridIndex: 1,
+                            show: false,
+                            axisLine: { show: false },
+                            axisTick: { show: false },
+                            splitLine: { show: false },
+                        });
+                    }
+                    return axes;
+                }
+                if (isCircularChart) {
+                    return [
+                        {
+                            type: "category",
+                            show: false,
+                            axisLine: { show: false },
+                            axisTick: { show: false },
+                            splitLine: { show: false },
+                        },
+                    ];
+                }
+                if (isHorizontalBarChart) {
+                    return [
+                        applyAxisOverrides({
+                            ...valueAxisBase,
+                            name: spec.horizontalAxisTitle ?? "",
+                        }, spec.valueAxisOptions),
+                    ];
+                }
+                const base = chartDomains.length > 0
+                    ? chartDomains
+                    : [
+                        {
+                            type: "category",
+                            show: showAxis,
+                            axisLine: { show: true },
+                            axisTick: { show: true },
+                            splitLine: { show: true },
+                            name: spec.horizontalAxisTitle ?? "",
+                            nameLocation: "middle",
+                            nameGap: 30,
+                        },
+                    ];
+                return base.map((axis) => applyAxisOverrides(axis, spec.categoryAxisOptions));
+            })(),
+            yAxis: (() => {
+                if (isOfPie) {
+                    const axes = [
+                        {
+                            ...valueAxisBase,
+                            min: 0,
+                            max: 1,
+                            show: false,
+                            axisLine: { show: false },
+                            axisTick: { show: false },
+                            splitLine: { show: false },
+                            name: undefined,
+                        },
+                    ];
+                    if (ofPieLayout?.barGrid) {
+                        axes.push({
+                            type: "value",
+                            gridIndex: 1,
+                            show: false,
+                            axisLine: { show: false },
+                            axisTick: { show: false },
+                            splitLine: { show: false },
+                        });
+                    }
+                    return axes;
+                }
+                if (isCircularChart) {
+                    return [
+                        {
+                            ...valueAxisBase,
+                            show: false,
+                            axisLine: { show: false },
+                            axisTick: { show: false },
+                            splitLine: { show: false },
+                            name: undefined,
+                        },
+                    ];
+                }
+                if (isHorizontalBarChart) {
+                    const base = chartDomains.length > 0
+                        ? chartDomains
+                        : [
+                            {
+                                type: "category",
+                                show: showAxis,
+                                axisLine: { show: true },
+                                axisTick: { show: true },
+                                splitLine: { show: true },
+                                name: spec.verticalAxisTitle ?? "",
+                                nameLocation: "middle",
+                                nameGap: 30,
+                            },
+                        ];
+                    return base.map((axis) => applyAxisOverrides(axis, spec.categoryAxisOptions));
+                }
+                const axes = [
+                    applyAxisOverrides({ ...valueAxisBase, name: spec.verticalAxisTitle ?? "" }, spec.valueAxisOptions),
+                ];
+                if (hasSecondaryAxis) {
+                    axes.push(applyAxisOverrides({
+                        ...valueAxisBase,
+                        name: "",
+                        splitLine: { show: false },
+                        // Pareto — the cumulative-% axis is clamped 0-100%.
+                        ...(isPareto
+                            ? {
+                                min: 0,
+                                max: 100,
+                                axisLabel: { formatter: "{value}%" },
+                            }
+                            : {}),
+                    }, spec.secondaryValueAxisOptions));
+                }
+                return axes;
+            })(),
+            series: seriesWithLabels,
+            legend: finalLegend,
+            grid: gridConfig,
+            tooltip: tooltipConfig,
+        }, { replaceMerge, lazyUpdate: true });
+        previousChartType.current = spec.chartType;
+        previousSeriesCount.current = renderedSeriesCount;
+    };
+    useIsomorphicLayoutEffect(() => {
+        echarts.use([
+            TitleComponent,
+            TooltipComponent,
+            GridComponent,
+            LegendComponent,
+            RadarComponent,
+            BarChart,
+            BoxplotChart,
+            CandlestickChart,
+            CustomChart,
+            FunnelChart,
+            LineChart,
+            PieChart,
+            EchartsRadarChart,
+            ScatterChart,
+            EchartsTreemapChart,
+            SunburstChart,
+            CanvasRenderer,
+            DatasetComponent,
+        ]);
+        initializeChart();
+    }, []);
+    // Subscribe to all chart data sources (domains, series, etc.)
+    const chartDataRanges = useMemo(() => getChartDataRanges(chart.spec), [chart.spec]);
+    useSubscribeToMultipleRanges(chart.chartId, chartDataRanges, updateChart);
+    // Theme-derived chart properties (title/legend/tooltip colors, series
+    // palette). Shared by the theme effect below and the 3-D / region-map
+    // pipelines, which re-initialize the echarts instance when switching
+    // between the cartesian 2-D option and the grid3D / map one and must
+    // re-apply these.
+    const applyThemeOptions = () => {
+        if (chartRef.current) {
+            const textColor = getStringifiedColor({
+                theme: 1,
+                tint: isDarkMode ? 1 : 0,
+            }, theme);
+            const bgColor = getStringifiedColor({ theme: 0, tint: isDarkMode ? -1 : 1 }, theme);
+            const showAxis = showXAxis(chart.spec.chartType);
+            // Authored chart-level text formats override the theme-derived
+            // defaults. Title, legend, and data-label colors flow through
+            // here; per-axis label colors land on each axis via
+            // `applyAxisOverrides` later in the layout build.
+            const authoredTitleFmt = chart.spec.titleTextFormat;
+            const authoredLegendFmt = chart.spec.legend?.textFormat;
+            const authoredDataLabelFmt = chart.spec.dataLabels?.textFormat;
+            const options = {
+                title: {
+                    text: title ?? undefined,
+                    textStyle: {
+                        color: authoredTitleFmt?.color ?? textColor,
+                        ...(authoredTitleFmt?.fontFamily
+                            ? { fontFamily: authoredTitleFmt.fontFamily }
+                            : {}),
+                        ...(typeof authoredTitleFmt?.fontSize === "number"
+                            ? { fontSize: authoredTitleFmt.fontSize }
+                            : {}),
+                        ...(authoredTitleFmt?.bold ? { fontWeight: "bold" } : {}),
+                        ...(authoredTitleFmt?.italic ? { fontStyle: "italic" } : {}),
+                    },
+                },
+                legend: {
+                    textStyle: {
+                        color: authoredLegendFmt?.color ?? textColor,
+                        ...(authoredLegendFmt?.fontFamily
+                            ? { fontFamily: authoredLegendFmt.fontFamily }
+                            : {}),
+                        ...(typeof authoredLegendFmt?.fontSize === "number"
+                            ? { fontSize: authoredLegendFmt.fontSize }
+                            : {}),
+                    },
+                },
+                axisLabel: {
+                    color: authoredDataLabelFmt?.color ?? textColor,
+                },
+                tooltip: {
+                    backgroundColor: bgColor,
+                    textStyle: {
+                        color: textColor,
+                    },
+                },
+                color: [
+                    theme.themeColors.accent1,
+                    theme.themeColors.accent2,
+                    theme.themeColors.accent3,
+                    theme.themeColors.accent4,
+                    theme.themeColors.accent5,
+                    theme.themeColors.accent6,
+                ],
+            };
+            // Skip when rendering 3-D or a region map: merging a cartesian
+            // yAxis into a grid3D / map option would create a stray empty
+            // 2-D axis over the WebGL scene / choropleth.
+            if (showAxis &&
+                !renderedIn3D.current &&
+                !renderedAsRegionMap.current) {
+                options.yAxis = {
+                    splitLine: {
+                        lineStyle: {
+                            color: isDarkMode ? "rgba(255,255,255,0.3)" : "#CCCCCC",
+                        },
+                    },
+                };
+            }
+            chartRef.current.setOption(options);
+        }
+    };
+    // Update chart properties
+    useIsomorphicLayoutEffect(() => {
+        applyThemeOptions();
+    }, [theme, title, isDarkMode, chart.spec.chartType]);
+    // Draw chart. `glUpgradeTick` re-runs the draw when the lazily loaded
+    // echarts-gl module resolves, upgrading a 3-D spec's immediate 2-D
+    // fallback to the true 3-D rendering.
+    useIsomorphicLayoutEffect(() => {
+        updateChart();
+    }, [
+        chart.spec,
+        getDomainValuesFromRange,
+        getSeriesValuesFromRange,
+        glUpgradeTick,
+    ]);
+    // Resize chart
+    useIsomorphicLayoutEffect(() => {
+        resizeChart();
+    }, [
+        chart.position.overlayPosition.widthPixels,
+        chart.position.overlayPosition.heightPixels,
+    ]);
+    // Chrome bug
+    useOnVisibilityChange((state) => state === "visible" ? resizeChart() : null);
+    useIsomorphicLayoutEffect(() => {
+        chartRef.current?.resize({ silent: true });
+    }, [width, height]);
+    const onDownloadChart = () => {
+        if (chartRef.current) {
+            const url = chartRef.current.getDataURL({
+                type: "png",
+                backgroundColor: getStringifiedColor({ theme: 0, tint: isDarkMode ? -1 : 1 }, theme),
+            });
+            createDownloadableFile(chart.spec.title ?? "Chart", url);
+        }
+    };
+    // Excel's "Rounded Corners" chart style (`<c:roundedCorners val="1"/>`
+    // at the chartSpace root). Default per OOXML §21.2.2.183 is square,
+    // so only opt in when the workbook explicitly set the flag — otherwise
+    // every imported chart would silently gain a radius.
+    const roundedCornersStyle = spec.roundedCorners
+        ? { borderRadius: 8, overflow: "hidden" }
+        : undefined;
+    return (React.createElement("div", { className: "flex flex-1", style: roundedCornersStyle },
+        isSelected ? (React.createElement(DropdownMenu, null,
+            React.createElement(DropdownMenuTrigger, { asChild: true },
+                React.createElement(IconButton, { className: "absolute right-1 top-1 z-10" },
+                    React.createElement(DotsVerticalIcon, null))),
+            React.createElement(DropdownMenuPortal, null,
+                React.createElement(DropdownMenuContent, { align: "start", onCloseAutoFocus: (event) => {
+                        event.preventDefault();
+                        if (shouldFocusSheetRef.current) {
+                            focusSheet?.();
+                        }
+                    }, onInteractOutside: () => {
+                        shouldFocusSheetRef.current = false;
+                    } },
+                    readonly ? null : (React.createElement(DropdownMenuItem, { onClick: () => onRequestEdit?.(chart) }, "Edit chart")),
+                    readonly ? null : (React.createElement(DropdownMenuItem, { onClick: () => {
+                            shouldFocusSheetRef.current = true;
+                            onDeleteChart?.(chart.chartId);
+                        } }, "Delete chart")),
+                    React.createElement(DropdownMenuSub, null,
+                        React.createElement(DropdownMenuSubTrigger, null,
+                            "Download chart",
+                            React.createElement(DropdownRightSlot, null,
+                                React.createElement(ChevronRightIcon, null))),
+                        React.createElement(DropdownMenuSubContent, null,
+                            React.createElement(DropdownMenuItem, { onClick: () => onDownloadChart?.() }, "PNG Image (.png)"))))))) : null,
+        React.createElement("div", { className: "flex-1", ref: el })));
+};