@rowsncolumns/toolkit 24.4.5 → 24.5.0

package/dist/esm/exporter/xlsx/chart-builder.js

@@ -11,6 +11,37 @@ const chartBuilder = new XMLBuilder({
 });
 const sanitizeXmlText = (value) => value ? value.replace(INVALID_XML_CHAR_REGEX, "") : value;
 const cloneTemplate = (template) => JSON.parse(JSON.stringify(template));
+/**
+ * Put `groups` where the template's `slotKey` chart group sat, in place, so
+ * every chart group keeps preceding `c:catAx` / `c:valAx` (CT_PlotArea:
+ * layout, chart groups, axes, dTable, spPr). Assigning a new key onto the
+ * plotArea object would append it after the axes.
+ */
+const replacePlotAreaChartGroups = (plotArea, groups, slotKey = "c:barChart") => {
+    const rebuilt = {};
+    let placed = false;
+    for (const [key, value] of Object.entries(plotArea)) {
+        if (key === slotKey) {
+            for (const [groupKey, group] of groups)
+                rebuilt[groupKey] = group;
+            placed = true;
+            continue;
+        }
+        if (!placed && (key === "c:catAx" || key === "c:valAx")) {
+            for (const [groupKey, group] of groups)
+                rebuilt[groupKey] = group;
+            placed = true;
+        }
+        rebuilt[key] = value;
+    }
+    if (!placed) {
+        for (const [groupKey, group] of groups)
+            rebuilt[groupKey] = group;
+    }
+    for (const key of Object.keys(plotArea))
+        delete plotArea[key];
+    Object.assign(plotArea, rebuilt);
+};
 const removeProp = (obj, key) => {
     delete obj[key];
 };
@@ -764,10 +795,20 @@ const buildBarSeriesNode = (index, ref, seriesData, domainRef, sheetName, isFirs
 /**
  * Build a line series node.
  */
-const buildLineSeriesNode = (index, ref, seriesData, domainRef, sheetName, smooth) => {
+const buildLineSeriesNode = (index, ref, seriesData, domainRef, sheetName, smooth, showMarkers = false) => {
     const seriesNode = cloneTemplate(line_series);
     seriesNode["c:idx"] = { a$: { val: index.toString() } };
     seriesNode["c:order"] = { a$: { val: index.toString() } };
+    // A series' own marker wins; otherwise "Line with Markers" leaves the
+    // symbol to Excel's automatic marker and a plain Line keeps the
+    // template's <c:symbol val="none"/> — same rule as the pure line branch.
+    const markerNode = buildMarkerNode(seriesData?.marker);
+    if (markerNode) {
+        seriesNode["c:marker"] = markerNode;
+    }
+    else if (showMarkers) {
+        removeProp(seriesNode, "c:marker");
+    }
     const seriesColor = seriesData?.color;
     // Line series carry the stroke fill on `c:spPr/a:ln`. A gradient on
     // a line stroke is unusual (Excel renders a flat-color stroke even
@@ -891,8 +932,7 @@ const buildPieChart = (domainRef, valueRef, title, subtitle) => {
     const plotArea = pieChart["c:plotArea"];
     const donut = plotArea["c:doughnutChart"];
     removeProp(donut, "c:holeSize");
-    plotArea["c:pieChart"] = donut;
-    removeProp(plotArea, "c:doughnutChart");
+    replacePlotAreaChartGroups(plotArea, [["c:pieChart", donut]], "c:doughnutChart");
     const seriesNode = plotArea["c:pieChart"]["c:ser"];
     if (domainRef) {
         seriesNode["c:cat"]["c:strRef"]["c:f"] = domainRef;
@@ -944,8 +984,7 @@ const buildOfPieChart = (domainRef, valueRef, title, spec, subtitle) => {
             : {}),
         "c:serLines": {},
     };
-    plotArea["c:ofPieChart"] = ofPieNode;
-    removeProp(plotArea, "c:doughnutChart");
+    replacePlotAreaChartGroups(plotArea, [["c:ofPieChart", ofPieNode]], "c:doughnutChart");
     const seriesNode = ofPieNode["c:ser"];
     if (domainRef) {
         seriesNode["c:cat"]["c:strRef"]["c:f"] = domainRef;
@@ -977,8 +1016,7 @@ const buildRadarLikeChart = (chartElementKey, domainRef, seriesRefs, title, rada
             a$: { val: radarStyle ?? "standard" },
         };
     }
-    removeProp(plotArea, "c:barChart");
-    plotArea[chartElementKey] = containerNode;
+    replacePlotAreaChartGroups(plotArea, [[chartElementKey, containerNode]]);
     const seriesContainer = containerNode["c:ser"];
     seriesRefs.forEach((ref, index) => {
         if (!ref)
@@ -997,6 +1035,68 @@ const buildRadarLikeChart = (chartElementKey, domainRef, seriesRefs, title, rada
     });
     return chartObj;
 };
+/**
+ * Stock chart. The price series (high/low/close, or open/high/low/close)
+ * go in `<c:stockChart>`; Excel's VHLC / VOHLC layouts carry the volume
+ * as the first series in a sibling `<c:barChart>`, which the parser reads
+ * back as the V-variant. Excel plots that volume on a secondary value
+ * axis; here both groups share the primary axes. CT_StockChart order is
+ * ser, hiLowLines, upDownBars, axId: every layout draws the high-low
+ * lines, and an open (OHLC / VOHLC) adds Excel's up/down bars between
+ * open and close — without them Excel renders bare, disconnected markers.
+ */
+const buildStockChart = (domainRef, seriesRefs, title, stockVariant, subtitle) => {
+    const hasVolume = stockVariant === "VHLC" || stockVariant === "VOHLC";
+    const hasOpen = stockVariant === "OHLC" || stockVariant === "VOHLC";
+    const chartObj = cloneTemplate(column_json);
+    applyChartTitle(chartObj, title, undefined, subtitle);
+    const plotArea = chartObj["c:plotArea"];
+    const axisIds = plotArea["c:barChart"]?.["c:axId"] ?? [];
+    const buildSeriesNode = (ref, index) => ({
+        "c:idx": { a$: { val: String(index) } },
+        "c:order": { a$: { val: String(index) } },
+        ...(domainRef ? { "c:cat": { "c:strRef": { "c:f": domainRef } } } : {}),
+        "c:val": { "c:numRef": { "c:f": ref } },
+    });
+    const volumeRef = hasVolume ? seriesRefs[0] : undefined;
+    const priceRefs = hasVolume ? seriesRefs.slice(1) : seriesRefs;
+    const priceOffset = hasVolume ? 1 : 0;
+    const stockNode = {
+        "c:ser": priceRefs.flatMap((ref, index) => ref ? [buildSeriesNode(ref, index + priceOffset)] : []),
+        "c:hiLowLines": {},
+        ...(hasOpen
+            ? {
+                "c:upDownBars": {
+                    "c:gapWidth": { a$: { val: "150" } },
+                    "c:upBars": {},
+                    "c:downBars": {},
+                },
+            }
+            : {}),
+        "c:axId": axisIds,
+    };
+    // Swap the template's bar group in place so the chart groups keep
+    // preceding the axes (CT_PlotArea order).
+    const rebuilt = {};
+    for (const [key, value] of Object.entries(plotArea)) {
+        if (key !== "c:barChart") {
+            rebuilt[key] = value;
+            continue;
+        }
+        if (volumeRef) {
+            rebuilt["c:barChart"] = {
+                "c:barDir": { a$: { val: "col" } },
+                "c:grouping": { a$: { val: "clustered" } },
+                "c:varyColors": { a$: { val: "0" } },
+                "c:ser": [buildSeriesNode(volumeRef, 0)],
+                "c:axId": axisIds,
+            };
+        }
+        rebuilt["c:stockChart"] = stockNode;
+    }
+    chartObj["c:plotArea"] = rebuilt;
+    return chartObj;
+};
 const buildDoughnutChart = (domainRef, valueRef, title, subtitle) => {
     // Doughnut uses the same donut_json template as pie but keeps the
     // <c:doughnutChart> wrapper (and the holeSize, which we set later
@@ -1013,13 +1113,48 @@ const buildDoughnutChart = (domainRef, valueRef, title, subtitle) => {
     }
     return chartObj;
 };
-export const buildChartXml = (chart, sheetNameById) => {
+/**
+ * Excel's Change Colors palette has no OOXML element of its own — the
+ * colours it implies are written on each `<c:ser><c:spPr>`. Resolve
+ * `spec.palette` onto every series that carries no fill of its own so the
+ * file shows the palette in Excel and the parser reads the colours back.
+ */
+const resolvePaletteIntoSeries = (chart) => {
+    const palette = chart.spec.palette;
+    const series = chart.spec?.series;
+    if (!palette?.length || !Array.isArray(series))
+        return chart;
+    // A pie / doughnut colours SLICES from the palette, not the series — a
+    // series fill would paint every slice alike. `applySliceColors` writes
+    // the palette per slice as `<c:dPt>` instead.
+    if (isCircularChartType(chart.spec.chartType))
+        return chart;
+    return {
+        ...chart,
+        spec: {
+            ...chart.spec,
+            series: series.map((entry, index) => entry?.color || entry?.gradient || entry?.noFill
+                ? entry
+                : { ...entry, color: palette[index % palette.length] }),
+        },
+    };
+};
+export const buildChartXml = (input, sheetNameById, resolvePivotSourceName) => {
+    const chart = resolvePaletteIntoSeries(input);
     const series = chart.spec?.series ?? [];
     if (!series.length)
         return undefined;
     const domainRef = formatSourcesRef(chart.spec.domains?.[0]?.sources, sheetNameById);
     const seriesRefs = series.map((entry) => formatSourcesRef(entry?.sources, sheetNameById));
-    const seriesCatRefs = series.map((entry) => seriesCategoryRef(entry, sheetNameById));
+    // Excel keeps one category axis per axis group: a series on the
+    // secondary axis takes the second chart domain (`domains[1]`) as its
+    // `<c:cat>` when it carries no category range of its own.
+    const secondaryDomainRef = formatSourcesRef(chart.spec.domains?.[1]?.sources, sheetNameById);
+    const seriesCatRefs = series.map((entry) => seriesCategoryRef(entry, sheetNameById) ??
+        (entry
+            ?.useSecondaryAxis && secondaryDomainRef
+            ? secondaryDomainRef
+            : undefined));
     if (!seriesRefs.some(Boolean))
         return undefined;
     const chartType = chart.spec.chartType;
@@ -1044,9 +1179,11 @@ export const buildChartXml = (chart, sheetNameById) => {
         const baseBarChart = plotArea["c:barChart"];
         const axisIds = baseBarChart?.["c:axId"] ?? [];
         const dLbls = baseBarChart?.["c:dLbls"] ?? {};
-        // Remove the default bar chart - we'll add specific chart types
-        removeProp(plotArea, "c:barChart");
-        // Add chart type containers for each group
+        const comboStackedType = chart.spec.stackedType;
+        const showMarkers = Boolean(chart.spec.showMarkers);
+        // One container per chart type, swapped into the template's bar slot
+        // together so they all precede the axes (CT_PlotArea order).
+        const comboGroups = [];
         for (const [groupType, groupSeries] of groups) {
             if (groupType === "bar" || groupType === "column") {
                 const barChartNode = {
@@ -1062,21 +1199,32 @@ export const buildChartXml = (chart, sheetNameById) => {
                     const seriesNode = buildBarSeriesNode(index, ref, data, seriesCatRefs[index] ?? domainRef, sheetName, i === 0);
                     barChartNode["c:ser"].push(seriesNode);
                 }
-                plotArea["c:barChart"] = barChartNode;
+                comboGroups.push(["c:barChart", barChartNode]);
             }
             else if (groupType === "line") {
+                // The line group honours the same grouping / marker rules as the
+                // pure line branch (CT_LineChart: ser, dLbls, marker, axId).
                 const lineChartNode = {
-                    "c:grouping": { a$: { val: "standard" } },
+                    "c:grouping": {
+                        a$: {
+                            val: comboStackedType === "STACKED"
+                                ? "stacked"
+                                : comboStackedType === "PERCENT_STACKED"
+                                    ? "percentStacked"
+                                    : "standard",
+                        },
+                    },
                     "c:varyColors": { a$: { val: "0" } },
                     "c:ser": [],
                     "c:dLbls": dLbls,
+                    "c:marker": { a$: { val: "1" } },
                     "c:axId": axisIds,
                 };
                 for (const { index, ref, data } of groupSeries) {
-                    const seriesNode = buildLineSeriesNode(index, ref, data, seriesCatRefs[index] ?? domainRef, sheetName, smooth);
+                    const seriesNode = buildLineSeriesNode(index, ref, data, seriesCatRefs[index] ?? domainRef, sheetName, smooth, showMarkers);
                     lineChartNode["c:ser"].push(seriesNode);
                 }
-                plotArea["c:lineChart"] = lineChartNode;
+                comboGroups.push(["c:lineChart", lineChartNode]);
             }
             else if (groupType === "area") {
                 const areaChartNode = {
@@ -1090,15 +1238,16 @@ export const buildChartXml = (chart, sheetNameById) => {
                     const seriesNode = buildAreaSeriesNode(index, ref, data, seriesCatRefs[index] ?? domainRef, sheetName);
                     areaChartNode["c:ser"].push(seriesNode);
                 }
-                plotArea["c:areaChart"] = areaChartNode;
+                comboGroups.push(["c:areaChart", areaChartNode]);
             }
         }
+        replacePlotAreaChartGroups(plotArea, comboGroups);
+        // Legend, data labels, axis options, overlays and the secondary axis
+        // group are applied by the shared formatting pass below, like every
+        // other chart type.
         chartSpace["c:chartSpace"]["c:chart"] = comboChart;
-        const xml = chartBuilder.build(chartSpace);
-        return `${XML_DECLARATION}${xml}`;
     }
-    // Handle non-combo charts (original logic)
-    if (isC15ChartType(chartType)) {
+    else if (isC15ChartType(chartType)) {
         // Histogram / boxplot / waterfall / funnel emit as a barChart for
         // older Excel compatibility. For histogram (Phase 5.5b), the
         // barChart is wrapped in mc:AlternateContent with a c15:histogramChart
@@ -1169,8 +1318,9 @@ export const buildChartXml = (chart, sheetNameById) => {
             c15Chart = buildC15FunnelChartNode(chart.spec, c15Args.seriesRefs, c15Args.series, c15Args.domainRef, c15Args.axIds);
         }
         const altContent = buildC15AlternateContent(chartType, c15Chart, bar);
-        removeProp(barChartDoc["c:plotArea"], "c:barChart");
-        barChartDoc["c:plotArea"]["mc:AlternateContent"] = altContent;
+        replacePlotAreaChartGroups(barChartDoc["c:plotArea"], [
+            ["mc:AlternateContent", altContent],
+        ]);
         chartSpace["c:chartSpace"]["c:chart"] = barChartDoc;
     }
     else if (chartType === "bar" || chartType === "column") {
@@ -1248,7 +1398,7 @@ export const buildChartXml = (chart, sheetNameById) => {
         chartSpace["c:chartSpace"]["c:chart"] = radarChart;
     }
     else if (chartType === "stock") {
-        const stockChart = buildRadarLikeChart("c:stockChart", domainRef, seriesRefs, chartTitle, undefined, chartSubtitle);
+        const stockChart = buildStockChart(domainRef, seriesRefs, chartTitle, chart.spec.stockVariant, chartSubtitle);
         chartSpace["c:chartSpace"]["c:chart"] = stockChart;
     }
     else if (chartType === "line") {
@@ -1256,10 +1406,16 @@ export const buildChartXml = (chart, sheetNameById) => {
         applyChartTitle(lineChart, chartTitle, chartTitleFmt, chartSubtitle);
         const plotArea = lineChart["c:plotArea"];
         const barChart = plotArea["c:barChart"];
+        const lineStackedType = chart.spec.stackedType;
+        const showMarkers = Boolean(chart.spec.showMarkers);
         const lineChartNode = {
             "c:grouping": {
                 a$: {
-                    val: "standard",
+                    val: lineStackedType === "STACKED"
+                        ? "stacked"
+                        : lineStackedType === "PERCENT_STACKED"
+                            ? "percentStacked"
+                            : "standard",
                 },
             },
             "c:varyColors": {
@@ -1269,10 +1425,12 @@ export const buildChartXml = (chart, sheetNameById) => {
             },
             "c:ser": [],
             "c:dLbls": barChart?.["c:dLbls"] ?? {},
+            // Excel writes the chart-level flag on every line chart and hides
+            // a plain Line's markers per series (<c:symbol val="none"/>).
+            "c:marker": { a$: { val: "1" } },
             "c:axId": barChart?.["c:axId"] ?? [],
         };
-        removeProp(plotArea, "c:barChart");
-        plotArea["c:lineChart"] = lineChartNode;
+        replacePlotAreaChartGroups(plotArea, [["c:lineChart", lineChartNode]]);
         const seriesContainer = lineChartNode["c:ser"];
         seriesRefs.forEach((ref, index) => {
             if (!ref)
@@ -1301,6 +1459,16 @@ export const buildChartXml = (chart, sheetNameById) => {
             if (smooth) {
                 seriesNode["c:smooth"].a$.val = "1";
             }
+            // A series' own marker wins; otherwise "Line with Markers" leaves
+            // the symbol to Excel's automatic marker and a plain Line keeps the
+            // template's <c:symbol val="none"/>.
+            const markerNode = buildMarkerNode(series[index]?.marker);
+            if (markerNode) {
+                seriesNode["c:marker"] = markerNode;
+            }
+            else if (showMarkers) {
+                removeProp(seriesNode, "c:marker");
+            }
             const labelNode = buildSeriesLabel(series[index]?.dataLabel ?? undefined, sheetNameById.get(chart.position.sheetId), series[index]?.dataLabelRef);
             if (labelNode) {
                 seriesNode["c:tx"] = labelNode["c:tx"];
@@ -1329,8 +1497,7 @@ export const buildChartXml = (chart, sheetNameById) => {
             "c:dLbls": barChart?.["c:dLbls"] ?? {},
             "c:axId": barChart?.["c:axId"] ?? [],
         };
-        removeProp(plotArea, "c:barChart");
-        plotArea["c:areaChart"] = areaChartNode;
+        replacePlotAreaChartGroups(plotArea, [["c:areaChart", areaChartNode]]);
         const seriesContainer = areaChartNode["c:ser"];
         seriesRefs.forEach((ref, index) => {
             if (!ref)
@@ -1426,12 +1593,11 @@ export const buildChartXml = (chart, sheetNameById) => {
         const plotArea = chartDoc["c:plotArea"];
         const scatterChart = plotArea["c:scatterChart"];
         if (chartType === "bubble") {
-            removeProp(plotArea, "c:scatterChart");
             removeProp(scatterChart, "c:scatterStyle");
             scatterChart["c:bubbleScale"] = { a$: { val: "100" } };
             scatterChart["c:showNegBubbles"] = { a$: { val: "0" } };
             scatterChart["c:sizeRepresents"] = { a$: { val: "area" } };
-            plotArea["c:bubbleChart"] = scatterChart;
+            replacePlotAreaChartGroups(plotArea, [["c:bubbleChart", scatterChart]], "c:scatterChart");
         }
         else {
             // <c:scatterStyle> — Excel default is "lineMarker". Round-trip
@@ -1477,9 +1643,40 @@ export const buildChartXml = (chart, sheetNameById) => {
     if (chart.spec.roundedCorners) {
         chartSpace["c:chartSpace"]["c:roundedCorners"] = { a$: { val: "1" } };
     }
+    // Chart Styles gallery pick — `<c:style val>` (1-48) with the Office
+    // 2010+ `<c14:style>` twin at +100 in the mc:Choice the template
+    // already carries. Unstyled charts keep the template's default (2).
+    const chartStyle = Number(chart.spec.chartStyle);
+    if (Number.isInteger(chartStyle) && chartStyle >= 1 && chartStyle <= 48) {
+        const alternate = chartSpace["c:chartSpace"]["mc:AlternateContent"];
+        alternate["mc:Choice"]["c14:style"].a$.val = String(100 + chartStyle);
+        alternate["mc:Fallback"]["c:style"].a$.val = String(chartStyle);
+    }
+    applyPivotChartBinding(chartSpace, chart.spec, resolvePivotSourceName);
+    // Format Chart Area → Fill / Border: the chartSpace `<c:spPr>`. The
+    // template's theme fill (`bg1`) and hairline stay when nothing is
+    // authored so untouched charts export exactly as before.
+    const chartSpacePr = chartSpace["c:chartSpace"]["c:spPr"];
+    const backgroundHex = toHex(chart.spec.backgroundColor);
+    if (backgroundHex) {
+        chartSpacePr["a:solidFill"] = { "a:srgbClr": { a$: { val: backgroundHex } } };
+    }
+    const borderHex = toHex(chart.borderColor);
+    if (borderHex) {
+        chartSpacePr["a:ln"]["a:solidFill"] = {
+            "a:srgbClr": { a$: { val: borderHex } },
+        };
+    }
     const xml = chartBuilder.build(chartSpace);
     return `${XML_DECLARATION}${xml}`;
 };
+/** `#RRGGBB` / `RRGGBB` → uppercase `RRGGBB`; anything else is not emitted. */
+const toHex = (color) => {
+    if (typeof color !== "string")
+        return undefined;
+    const hex = color.trim().replace(/^#/, "");
+    return /^[0-9a-fA-F]{6}$/.test(hex) ? hex.toUpperCase() : undefined;
+};
 // -------------------------- 3-D / surface --------------------------
 /** Series-axis id for the 3-D chart groups that take a third axis. */
 const SER_AX_ID = "1789284465";
@@ -1656,6 +1853,7 @@ const applyChartFormatting = (chartSpace, spec, sheetNameById) => {
     if (!chartNode)
         return;
     applyLegend(chartNode, spec?.legend);
+    applyEmptyCellsOptions(chartNode, spec?.emptyCells, spec?.showNaAsEmpty);
     const plotArea = chartNode["c:plotArea"];
     if (!plotArea)
         return;
@@ -1663,8 +1861,10 @@ const applyChartFormatting = (chartSpace, spec, sheetNameById) => {
     applyAxisOptions(plotArea, spec?.valueAxisOptions, "value");
     applyAxisOptions(plotArea, spec?.categoryAxisOptions, "category");
     applyDoughnutHole(plotArea, spec?.doughnutHoleSize);
+    applyExplosion(plotArea, spec?.explosion);
+    applySliceColors(plotArea, spec);
     applySeriesOverlays(plotArea, spec?.series, sheetNameById);
-    applySecondaryAxis(plotArea, spec?.secondaryValueAxisOptions);
+    applySecondaryAxisGroup(plotArea, spec, spec?.series ?? []);
 };
 const SERIES_CONTAINER_KEYS = [
     "c:barChart",
@@ -1685,29 +1885,42 @@ const applySeriesOverlays = (plotArea, series, sheetNameById) => {
         return;
     let seriesIndex = 0;
     for (const key of SERIES_CONTAINER_KEYS) {
-        const container = plotArea[key];
-        if (!container)
+        const containers = plotArea[key];
+        if (!containers)
             continue;
-        const ser = container["c:ser"];
-        if (!ser)
-            continue;
-        const list = Array.isArray(ser) ? ser : [ser];
-        for (const node of list) {
-            const data = series[seriesIndex++];
-            if (!data)
+        // A split secondary axis group is an array of containers.
+        const containerList = Array.isArray(containers)
+            ? containers
+            : [containers];
+        for (const container of containerList) {
+            const ser = container?.["c:ser"];
+            if (!ser)
                 continue;
-            if (Array.isArray(data.trendlines) && data.trendlines.length) {
-                const built = data.trendlines
-                    .map(buildTrendlineNode)
-                    .filter(Boolean);
-                // OOXML allows multiple <c:trendline> on a series; preserve the
-                // order from the spec.
-                node["c:trendline"] = built.length === 1 ? built[0] : built;
-            }
-            if (data.errorBars) {
-                const built = buildErrorBarsNode(data.errorBars, sheetNameById);
-                if (built)
-                    node["c:errBars"] = built;
+            const list = Array.isArray(ser) ? ser : [ser];
+            for (const node of list) {
+                // A combo chart groups its series by chart type, so the emitted
+                // order differs from spec.series — `<c:idx>` carries the spec
+                // index; fall back to emission order for nodes without one.
+                const idx = Number(node?.["c:idx"]?.a$?.val);
+                const data = Number.isInteger(idx)
+                    ? series[idx]
+                    : series[seriesIndex];
+                seriesIndex++;
+                if (!data)
+                    continue;
+                if (Array.isArray(data.trendlines) && data.trendlines.length) {
+                    const built = data.trendlines
+                        .map(buildTrendlineNode)
+                        .filter(Boolean);
+                    // OOXML allows multiple <c:trendline> on a series; preserve the
+                    // order from the spec.
+                    node["c:trendline"] = built.length === 1 ? built[0] : built;
+                }
+                if (data.errorBars) {
+                    const built = buildErrorBarsNode(data.errorBars, sheetNameById);
+                    if (built)
+                        node["c:errBars"] = built;
+                }
             }
         }
     }
@@ -1798,12 +2011,297 @@ const applySecondaryAxis = (plotArea, opts) => {
         "c:scaling": { "c:orientation": { a$: { val: "minMax" } } },
         "c:delete": { a$: { val: "0" } },
         "c:axPos": { a$: { val: "r" } },
+        "c:numFmt": { a$: { formatCode: "General", sourceLinked: "1" } },
         "c:crossAx": { a$: { val: String(primaryAxId) } },
     };
     // Apply the same logarithmic / reverse / min / max / gridlines etc.
     applyAxisOptions({ "c:valAx": secondary }, opts, "value");
     plotArea["c:valAx"] = [...existingArr, secondary];
 };
+/** Category-axis chart groups a series can be plotted on a secondary axis in. */
+const CATEGORY_GROUP_KEYS = ["c:barChart", "c:lineChart", "c:areaChart"];
+/** `<c:axPos>` opposite the primary axis — where Excel draws the secondary one. */
+const OPPOSITE_AX_POS = { b: "t", t: "b", l: "r", r: "l" };
+const asNodeArray = (value) => value === undefined || value === null
+    ? []
+    : Array.isArray(value)
+        ? value
+        : [value];
+const axIdValueOf = (axis) => axis?.["c:axId"]?.a$?.val;
+/**
+ * Excel plots "Plot Series On: Secondary Axis" series in their own chart
+ * group bound to a second `<c:catAx>` / `<c:valAx>` pair (one category axis
+ * and one value axis per axis group). Move every `useSecondaryAxis` series
+ * out of its primary group into a clone of that group carrying the
+ * secondary axIds (so a bar-primary + line-secondary combo keeps one bar
+ * group and one line group), then add the secondary axis pair: the
+ * category axis sits opposite the primary and is hidden (`<c:delete
+ * val="1"/>`) when it shares the primary categories, shown when the spec
+ * carries its own `domains[1]`; the value axis sits opposite the primary,
+ * crosses at `max`, and takes `secondaryValueAxisOptions`.
+ *
+ * Charts with no secondary-axis series keep the old single-group layout
+ * (a bare second `<c:valAx>` for `secondaryValueAxisOptions` alone), as do
+ * the 3-D and c15 (histogram / boxplot / waterfall / funnel) bodies.
+ */
+const applySecondaryAxisGroup = (plotArea, spec, series) => {
+    const opts = spec?.secondaryValueAxisOptions;
+    const secondaryIdx = new Set();
+    let plottedSeries = 0;
+    (series ?? []).forEach((entry, index) => {
+        if (!entry)
+            return;
+        plottedSeries += 1;
+        if (entry.useSecondaryAxis)
+            secondaryIdx.add(String(index));
+    });
+    const groupKeys = CATEGORY_GROUP_KEYS.filter((key) => plotArea?.[key]);
+    const catAxes = asNodeArray(plotArea?.["c:catAx"]);
+    const valAxes = asNodeArray(plotArea?.["c:valAx"]);
+    if (!secondaryIdx.size ||
+        secondaryIdx.size >= plottedSeries ||
+        !groupKeys.length ||
+        plotArea["mc:AlternateContent"] ||
+        normalizeThreeDToken(spec?.sourceChartType) ||
+        catAxes.length !== 1 ||
+        valAxes.length !== 1) {
+        applySecondaryAxis(plotArea, opts);
+        return;
+    }
+    const primaryCat = catAxes[0];
+    const primaryVal = valAxes[0];
+    const catAxId = parseInt(axIdValueOf(primaryCat) ?? "47003664", 10);
+    const valAxId = parseInt(axIdValueOf(primaryVal) ?? "1789284464", 10);
+    const secondaryCatAxId = String(catAxId + 100);
+    const secondaryValAxId = String(valAxId + 100);
+    const secondaryAxIds = [
+        { a$: { val: secondaryCatAxId } },
+        { a$: { val: secondaryValAxId } },
+    ];
+    let moved = false;
+    for (const key of groupKeys) {
+        const primaries = [];
+        const secondaries = [];
+        for (const container of asNodeArray(plotArea[key])) {
+            const sers = asNodeArray(container["c:ser"]);
+            const keep = sers.filter((node) => !secondaryIdx.has(String(node?.["c:idx"]?.a$?.val)));
+            const move = sers.filter((node) => secondaryIdx.has(String(node?.["c:idx"]?.a$?.val)));
+            if (!move.length) {
+                primaries.push(container);
+                continue;
+            }
+            moved = true;
+            if (keep.length)
+                primaries.push({ ...container, "c:ser": keep });
+            // Same group shape (grouping, gapWidth, dLbls, …) — only the series
+            // and the axis binding differ.
+            const secondary = cloneTemplate(container);
+            secondary["c:ser"] = move;
+            secondary["c:axId"] = secondaryAxIds;
+            secondaries.push(secondary);
+        }
+        const groups = [...primaries, ...secondaries];
+        plotArea[key] = groups.length === 1 ? groups[0] : groups;
+    }
+    if (!moved) {
+        applySecondaryAxis(plotArea, opts);
+        return;
+    }
+    // Secondary category axis — opposite the primary; hidden unless the
+    // secondary group has its own category list (domains[1]).
+    const hasSecondaryDomain = Boolean(spec?.domains?.[1]?.sources?.length);
+    const catAx2 = cloneTemplate(column_json["c:plotArea"]["c:catAx"]);
+    catAx2["c:axId"] = { a$: { val: secondaryCatAxId } };
+    catAx2["c:delete"] = { a$: { val: hasSecondaryDomain ? "0" : "1" } };
+    catAx2["c:axPos"] = {
+        a$: { val: OPPOSITE_AX_POS[primaryCat?.["c:axPos"]?.a$?.val] ?? "t" },
+    };
+    catAx2["c:crossAx"] = { a$: { val: secondaryValAxId } };
+    catAx2["c:crosses"] = { a$: { val: "autoZero" } };
+    // Secondary value axis — opposite the primary, crossing at max, no
+    // gridlines (Excel's default for a secondary axis).
+    const valAx2 = cloneTemplate(column_json["c:plotArea"]["c:valAx"]);
+    valAx2["c:axId"] = { a$: { val: secondaryValAxId } };
+    valAx2["c:delete"] = { a$: { val: "0" } };
+    valAx2["c:axPos"] = {
+        a$: { val: OPPOSITE_AX_POS[primaryVal?.["c:axPos"]?.a$?.val] ?? "r" },
+    };
+    removeProp(valAx2, "c:majorGridlines");
+    valAx2["c:crossAx"] = { a$: { val: secondaryCatAxId } };
+    valAx2["c:crosses"] = { a$: { val: "max" } };
+    applyAxisOptions({ "c:valAx": valAx2 }, opts, "value");
+    plotArea["c:catAx"] = [primaryCat, catAx2];
+    plotArea["c:valAx"] = [primaryVal, valAx2];
+};
+const PIVOT_OPTIONS_EXT_URI = "{781A3756-C4B2-4CAC-9D66-4F8BD8637D16}";
+const C14_NS = "http://schemas.microsoft.com/office/drawing/2007/8/2/chart";
+/**
+ * PivotChart binding — `<c:pivotSource>` (name + fmtId) at the chartSpace
+ * root so Excel keeps the chart on the pivot cache, `<c:pivotFmts>` inside
+ * `<c:chart>` and the c14 `<c14:pivotOptions>` field-button choices in the
+ * chartSpace `<c:extLst>`. All three only for a chart bound to an exported
+ * pivot; a chart whose pivot is missing exports as a plain chart, which is
+ * what Excel does when a PivotChart loses its pivot.
+ */
+const applyPivotChartBinding = (chartSpace, spec, resolvePivotSourceName) => {
+    const pivotTableId = spec.pivotTableId;
+    if (pivotTableId == null || !resolvePivotSourceName)
+        return;
+    const name = resolvePivotSourceName(pivotTableId);
+    if (!name)
+        return;
+    const root = chartSpace["c:chartSpace"];
+    setChildInOrder(root, "c:pivotSource", {
+        "c:name": name,
+        "c:fmtId": { a$: { val: String(spec.pivotSource?.formatId ?? 0) } },
+    }, ["c:protection", "c:chart"]);
+    const formats = spec.pivotFormats ?? [];
+    if (formats.length) {
+        setChildInOrder(root["c:chart"], "c:pivotFmts", {
+            "c:pivotFmt": formats.map((format) => {
+                const idx = { "c:idx": { a$: { val: String(format.index) } } };
+                // A verbatim body (C-83) carries its own <c:spPr>; the fill-only
+                // form is for formats authored in-app.
+                if (format.body?.length) {
+                    return { ...idx, ...chartXmlElementsToBuilderObject(format.body) };
+                }
+                const hex = toHex(format.color);
+                return {
+                    ...idx,
+                    ...(hex
+                        ? { "c:spPr": { "a:solidFill": { "a:srgbClr": { a$: { val: hex } } } } }
+                        : {}),
+                };
+            }),
+        }, ["c:view3D", "c:floor", "c:sideWall", "c:backWall", "c:plotArea"]);
+    }
+    const buttons = spec.pivotFieldButtons ?? {};
+    const flag = (shown) => ({
+        a$: { val: shown === false ? "0" : "1" },
+    });
+    const existing = root["c:extLst"]?.["c:ext"];
+    const exts = Array.isArray(existing) ? existing : existing ? [existing] : [];
+    root["c:extLst"] = {
+        "c:ext": [
+            ...exts,
+            {
+                a$: { uri: PIVOT_OPTIONS_EXT_URI, "xmlns:c14": C14_NS },
+                "c14:pivotOptions": {
+                    "c14:dropZoneFilter": flag(buttons.reportFilter),
+                    "c14:dropZoneCategories": flag(buttons.axis),
+                    "c14:dropZoneData": flag(buttons.value),
+                    "c14:dropZoneSeries": flag(buttons.legend),
+                    "c14:dropZonesVisible": flag(buttons.visible),
+                },
+            },
+        ],
+    };
+};
+/** Prefixes the chartSpace root declares; any other prefix is declared on the element that uses it. */
+const ROOT_CHART_PREFIXES = new Set(["c", "a", "r"]);
+const CHART_XML_PREFIX_URIS = {
+    mc: "http://schemas.openxmlformats.org/markup-compatibility/2006",
+    c14: "http://schemas.microsoft.com/office/drawing/2007/8/2/chart",
+    c15: "http://schemas.microsoft.com/office/drawing/2012/chart",
+    c16: "http://schemas.microsoft.com/office/drawing/2014/chart",
+    c16r2: "http://schemas.microsoft.com/office/drawing/2015/06/chart",
+    c16r3: "http://schemas.microsoft.com/office/drawing/2017/03/chart",
+    a14: "http://schemas.microsoft.com/office/drawing/2010/main",
+    a16: "http://schemas.microsoft.com/office/drawing/2014/main",
+};
+/**
+ * Verbatim `ChartXmlElement`s → the XMLBuilder object shape (`a$` attributes,
+ * `t$` text), keys in document order; same-named siblings group into an array.
+ * An extension prefix the root does not declare is declared on the first
+ * element that uses it (`declared` tracks the ancestors' declarations).
+ */
+const chartXmlElementsToBuilderObject = (elements, declared = ROOT_CHART_PREFIXES) => {
+    const out = {};
+    for (const element of elements) {
+        const prefix = element.tag.includes(":") ? element.tag.slice(0, element.tag.indexOf(":")) : "";
+        const scope = new Set(declared);
+        const attributes = { ...(element.attributes ?? {}) };
+        if (prefix && !scope.has(prefix) && CHART_XML_PREFIX_URIS[prefix]) {
+            attributes[`xmlns:${prefix}`] = CHART_XML_PREFIX_URIS[prefix];
+            scope.add(prefix);
+        }
+        const node = {};
+        if (Object.keys(attributes).length)
+            node.a$ = attributes;
+        if (element.children?.length) {
+            Object.assign(node, chartXmlElementsToBuilderObject(element.children, scope));
+        }
+        else if (element.text != null) {
+            node.t$ = element.text;
+        }
+        const existing = out[element.tag];
+        if (existing === undefined)
+            out[element.tag] = node;
+        else if (Array.isArray(existing))
+            existing.push(node);
+        else
+            out[element.tag] = [existing, node];
+    }
+    return out;
+};
+/** `emptyCells` → `<c:dispBlanksAs val>`. */
+const DISP_BLANKS_AS = {
+    gaps: "gap",
+    zero: "zero",
+    connect: "span",
+};
+/**
+ * Set `key` on `node` keeping the schema order: an existing key is
+ * overwritten in place, a new one is inserted ahead of the first of
+ * `beforeKeys` that is present (else appended).
+ */
+const setChildInOrder = (node, key, value, beforeKeys) => {
+    if (key in node) {
+        node[key] = value;
+        return;
+    }
+    const entries = Object.entries(node);
+    const at = entries.findIndex(([k]) => beforeKeys.includes(k));
+    if (at === -1) {
+        node[key] = value;
+        return;
+    }
+    entries.splice(at, 0, [key, value]);
+    for (const k of Object.keys(node))
+        delete node[k];
+    for (const [k, v] of entries)
+        node[k] = v;
+};
+/**
+ * Excel's "Hidden and Empty Cells" dialog: `<c:dispBlanksAs>` (gap /
+ * zero / span) and the 2017 `<c16r3:dispNaAsBlank>` extension for "Show
+ * #N/A as an empty cell". Both only when authored, so a file imported
+ * without them round-trips unchanged.
+ */
+const applyEmptyCellsOptions = (chartNode, emptyCells, showNaAsEmpty) => {
+    const dispBlanksAs = emptyCells ? DISP_BLANKS_AS[emptyCells] : undefined;
+    if (dispBlanksAs) {
+        setChildInOrder(chartNode, "c:dispBlanksAs", { a$: { val: dispBlanksAs } }, ["c:showDLblsOverMax", "c:extLst"]);
+    }
+    if (typeof showNaAsEmpty === "boolean") {
+        const existing = chartNode["c:extLst"]?.["c:ext"];
+        const exts = Array.isArray(existing) ? existing : existing ? [existing] : [];
+        chartNode["c:extLst"] = {
+            "c:ext": [
+                ...exts,
+                {
+                    a$: {
+                        uri: "{56B9EC1D-385E-4148-901F-78D8002777C0}",
+                        "xmlns:c16r3": "http://schemas.microsoft.com/office/drawing/2017/03/chart",
+                    },
+                    "c16r3:dataDisplayOptions16": {
+                        "c16r3:dispNaAsBlank": { a$: { val: showNaAsEmpty ? "1" : "0" } },
+                    },
+                },
+            ],
+        };
+    }
+};
 const applyLegend = (chartNode, legend) => {
     if (!legend)
         return;
@@ -1838,16 +2336,19 @@ const applyDataLabels = (plotArea, dataLabels) => {
         return;
     // Find the chart-type container inside <c:plotArea>. We attach <c:dLbls>
     // to whichever exists.
-    const containerKey = [
+    // Chart-level labels apply to every chart group — a combo chart has
+    // one per series type.
+    const containers = [
         "c:barChart",
         "c:lineChart",
         "c:pieChart",
         "c:doughnutChart",
         "c:areaChart",
-    ].find((k) => plotArea[k]);
-    if (!containerKey)
+    ]
+        .flatMap((k) => (Array.isArray(plotArea[k]) ? plotArea[k] : [plotArea[k]]))
+        .filter(Boolean);
+    if (!containers.length)
         return;
-    const container = plotArea[containerKey];
     const posCode = dataLabels.position && DLBL_POS[dataLabels.position];
     const dLbls = {};
     if (posCode)
@@ -1885,7 +2386,9 @@ const applyDataLabels = (plotArea, dataLabels) => {
         a$: { val: dataLabels.showPercent ? "1" : "0" },
     };
     dLbls["c:showBubbleSize"] = { a$: { val: "0" } };
-    container["c:dLbls"] = dLbls;
+    for (const container of containers) {
+        container["c:dLbls"] = cloneTemplate(dLbls);
+    }
 };
 const applyAxisOptions = (plotArea, options, kind) => {
     if (!options)
@@ -1919,6 +2422,13 @@ const applyAxisOptions = (plotArea, options, kind) => {
     if (options.showMajorGridlines === false && node["c:majorGridlines"]) {
         delete node["c:majorGridlines"];
     }
+    // <c:numFmt sourceLinked="0"> — an explicit tick-label format. Without
+    // one the axis stays "Linked to source" (the template's General/1).
+    if (options.numberFormatPattern) {
+        node["c:numFmt"] = {
+            a$: { formatCode: options.numberFormatPattern, sourceLinked: "0" },
+        };
+    }
     // <c:txPr> — axis tick-label color/font. Without this, exported
     // axes would render with the default theme color instead of the
     // authored one (BEP.xlsx axis colors #14325A / #F0621C).
@@ -1926,6 +2436,112 @@ const applyAxisOptions = (plotArea, options, kind) => {
     if (txPr)
         node["c:txPr"] = txPr;
 };
+/**
+ * Exploded pie / doughnut — `<c:explosion val="…"/>` on every slice series.
+ * CT_PieSer order: idx, order, tx, spPr, explosion, dPt, dLbls, cat, val.
+ */
+const PIE_SER_KEYS_BEFORE_EXPLOSION = new Set([
+    "c:idx",
+    "c:order",
+    "c:tx",
+    "c:spPr",
+]);
+const applyExplosion = (plotArea, explosion) => {
+    if (typeof explosion !== "number" || !(explosion > 0))
+        return;
+    const group = plotArea?.["c:pieChart"] ?? plotArea?.["c:doughnutChart"];
+    if (!group)
+        return;
+    const sers = Array.isArray(group["c:ser"])
+        ? group["c:ser"]
+        : group["c:ser"]
+            ? [group["c:ser"]]
+            : [];
+    const explosionNode = { a$: { val: String(Math.round(explosion)) } };
+    const rebuiltSers = sers.map((ser) => {
+        const rebuilt = {};
+        let placed = false;
+        for (const [key, value] of Object.entries(ser)) {
+            if (key === "c:explosion")
+                continue;
+            if (!placed && !PIE_SER_KEYS_BEFORE_EXPLOSION.has(key)) {
+                rebuilt["c:explosion"] = explosionNode;
+                placed = true;
+            }
+            rebuilt[key] = value;
+        }
+        if (!placed)
+            rebuilt["c:explosion"] = explosionNode;
+        return rebuilt;
+    });
+    group["c:ser"] = Array.isArray(group["c:ser"]) ? rebuiltSers : rebuiltSers[0];
+};
+const isCircularChartType = (chartType) => chartType === "pie" || chartType === "doughnut";
+/** How many points a series' first source range holds (a column or a row of cells). */
+const sourcePointCount = (source) => {
+    if (!source)
+        return 0;
+    const rows = source.endRowIndex - source.startRowIndex + 1;
+    const cols = source.endColumnIndex - source.startColumnIndex + 1;
+    return Math.max(0, rows > 1 ? rows : cols);
+};
+/**
+ * Per-slice colours of a pie / doughnut — the renderer paints each slice
+ * from `dataPointColors` when authored, else from the palette cycle
+ * (`spec.palette`, else the theme accents Excel's `<c:varyColors>` also
+ * cycles). Excel keeps a slice's own colour only as a `<c:dPt>`, so every
+ * slice series gets one per point: authored overrides first, else the
+ * palette colour of each slice index (nothing when the theme cycle is
+ * in effect — `<c:varyColors val="1"/>` reproduces it). Replaces the
+ * template's placeholder `<c:dPt>` and keeps CT_PieSer order (dPt after
+ * spPr / explosion, before dLbls / cat / val).
+ */
+const PIE_SER_KEYS_BEFORE_DPT = new Set([
+    "c:idx",
+    "c:order",
+    "c:tx",
+    "c:spPr",
+    "c:explosion",
+]);
+const applySliceColors = (plotArea, spec) => {
+    if (!isCircularChartType(spec?.chartType))
+        return;
+    const group = plotArea?.["c:pieChart"] ?? plotArea?.["c:doughnutChart"];
+    if (!group)
+        return;
+    const sers = Array.isArray(group["c:ser"])
+        ? group["c:ser"]
+        : group["c:ser"]
+            ? [group["c:ser"]]
+            : [];
+    const palette = spec?.palette;
+    const series = (spec?.series ?? []);
+    const rebuiltSers = sers.map((ser, index) => {
+        const entry = series[index];
+        const authored = entry?.dataPointColors;
+        const pointColors = authored?.length
+            ? authored
+            : palette?.length
+                ? Array.from({ length: sourcePointCount(entry?.sources?.[0]) }, (_, idx) => ({ idx, color: palette[idx % palette.length] }))
+                : undefined;
+        const dPtNodes = buildDataPointNodes(pointColors);
+        const rebuilt = {};
+        let placed = false;
+        for (const [key, value] of Object.entries(ser)) {
+            if (key === "c:dPt")
+                continue;
+            if (dPtNodes && !placed && !PIE_SER_KEYS_BEFORE_DPT.has(key)) {
+                rebuilt["c:dPt"] = dPtNodes;
+                placed = true;
+            }
+            rebuilt[key] = value;
+        }
+        if (dPtNodes && !placed)
+            rebuilt["c:dPt"] = dPtNodes;
+        return rebuilt;
+    });
+    group["c:ser"] = Array.isArray(group["c:ser"]) ? rebuiltSers : rebuiltSers[0];
+};
 const applyDoughnutHole = (plotArea, holeSize) => {
     if (typeof holeSize !== "number")
         return;