@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/browser/modules/excel/xlsx/xform/book/external-link-xform.js

@@ -105,19 +105,21 @@ class ExternalLinkXform extends BaseXform {
             const sheet = cache[name];
             return sheet && Object.keys(sheet).length > 0;
         });
-        if (hasAnyCache) {
-            xmlStream.openNode("sheetDataSet");
-            // Iterate in sheetNames order so sheetId indices are stable.
-            for (let i = 0; i < model.sheetNames.length; i++) {
-                const sheetName = model.sheetNames[i];
-                const cells = cache[sheetName];
-                if (!cells || Object.keys(cells).length === 0) {
-                    continue;
-                }
+        // Excel requires <sheetDataSet> to be present even when empty —
+        // omitting it causes "file cannot be opened" errors. Each declared
+        // sheet must have a corresponding <sheetData sheetId="N"/> entry.
+        xmlStream.openNode("sheetDataSet");
+        for (let i = 0; i < model.sheetNames.length; i++) {
+            const sheetName = model.sheetNames[i];
+            const cells = hasAnyCache ? cache[sheetName] : undefined;
+            if (cells && Object.keys(cells).length > 0) {
                 renderSheetData(xmlStream, i, cells);
             }
-            xmlStream.closeNode();
+            else {
+                xmlStream.leafNode("sheetData", { sheetId: String(i) });
+            }
         }
+        xmlStream.closeNode();
         xmlStream.closeNode(); // </externalBook>
         xmlStream.closeNode(); // </externalLink>
     }

package/dist/browser/modules/excel/xlsx/xform/book/workbook-xform.js

@@ -43,7 +43,44 @@ class WorkbookXform extends BaseXform {
         };
     }
     prepare(model) {
-        model.sheets = model.worksheets;
+        // Build the sheets list preserving the author's chosen sheet order.
+        // Each sheet (worksheet or chartsheet) carries an `orderNo` set
+        // during add / load; we sort the combined list by that field so a
+        // workbook with interleaved `[ws1, cs1, ws2, cs2]` round-trips in
+        // the same order the user authored. The previous implementation
+        // sorted by `sheetNo` — but `sheetNo` is the file-path number
+        // (independent per family), so a workbook where the author added
+        // worksheet A, chartsheet X, worksheet B got reshuffled to
+        // [A(1), X(1), B(2)] → [A, X, B] which is only correct by
+        // accident when worksheet and chartsheet numbering starts at the
+        // same value. `orderNo` is a unified counter and reflects true
+        // insertion / tab order.
+        const worksheets = [...(model.worksheets ?? [])];
+        const chartsheets = [...(model.chartsheets ?? [])];
+        if (chartsheets.length === 0) {
+            model.sheets = worksheets;
+        }
+        else {
+            const combined = [...worksheets, ...chartsheets];
+            const withIndex = combined.map((sheet, originalIndex) => ({ sheet, originalIndex }));
+            withIndex.sort((a, b) => {
+                const aOrder = typeof a.sheet.orderNo === "number"
+                    ? a.sheet.orderNo
+                    : typeof a.sheet.sheetNo === "number"
+                        ? a.sheet.sheetNo
+                        : Infinity;
+                const bOrder = typeof b.sheet.orderNo === "number"
+                    ? b.sheet.orderNo
+                    : typeof b.sheet.sheetNo === "number"
+                        ? b.sheet.sheetNo
+                        : Infinity;
+                if (aOrder !== bOrder) {
+                    return aOrder - bOrder;
+                }
+                return a.originalIndex - b.originalIndex;
+            });
+            model.sheets = withIndex.map(entry => entry.sheet);
+        }
         // collate all the print areas from all of the sheets and add them to the defined names
         const printAreas = [];
         let index = 0; // sheets is sparse array - calc index manually
@@ -102,6 +139,15 @@ class WorkbookXform extends BaseXform {
         this.map.bookViews.render(xmlStream, model.views);
         this.map.sheets.render(xmlStream, model.sheets);
         this.map.definedNames.render(xmlStream, model.definedNames);
+        // <externalReferences> must appear BEFORE <calcPr> per ECMA-376
+        // CT_Workbook sequence: sheets → definedNames → externalReferences →
+        // calcPr → pivotCaches. Violating this order causes Excel to reject
+        // the file as corrupt.
+        const externalLinks = model.externalLinks ?? [];
+        if (externalLinks.length > 0) {
+            const externalReferenceModels = externalLinks.map((link) => ({ rId: link.rId }));
+            this.map.externalReferences.render(xmlStream, externalReferenceModels);
+        }
         this.map.calcPr.render(xmlStream, model.calcProperties);
         // R9-B6: Deduplicate pivot caches by cacheId before rendering.
         // Multiple pivot tables may share the same cache, but workbook.xml should
@@ -116,15 +162,6 @@ class WorkbookXform extends BaseXform {
             return true;
         });
         this.map.pivotCaches.render(xmlStream, uniquePivotCaches);
-        // <externalReferences> order matters: one entry per externalLink in
-        // declaration order, each carrying the r:id that resolves (via
-        // workbook.xml.rels) to `xl/externalLinks/externalLink{N}.xml`. The
-        // index inside this list is exactly the `[N]` used in formula strings.
-        const externalLinks = model.externalLinks ?? [];
-        if (externalLinks.length > 0) {
-            const externalReferenceModels = externalLinks.map((link) => ({ rId: link.rId }));
-            this.map.externalReferences.render(xmlStream, externalReferenceModels);
-        }
         xmlStream.closeNode();
     }
     parseOpen(node) {
@@ -189,29 +226,59 @@ class WorkbookXform extends BaseXform {
             return map;
         }, {});
         // reconcile sheet ids, rIds and names
+        //
+        // `worksheets` is indexed positionally across BOTH sheet kinds
+        // (worksheet and chartsheet). OOXML `definedName/@localSheetId`
+        // is a 0-based index into the workbook-level `<sheets>` element,
+        // which mixes both kinds — so a chartsheet occupying position 1
+        // in `<sheets>` shifts every subsequent worksheet's effective
+        // index by one. Compressing to a worksheets-only array (the
+        // previous implementation) made `localSheetId` resolve to the
+        // wrong worksheet whenever chartsheets were interleaved, so
+        // `_xlnm.Print_Area` / `_xlnm.Print_Titles` landed on an
+        // unrelated sheet.
         const worksheets = [];
+        const chartsheetsList = [];
         let worksheet;
-        let index = 0;
+        let sheetPosition = 0;
         (model.sheets ?? []).forEach((sheet) => {
             const rel = rels[sheet.rId];
             if (!rel) {
+                sheetPosition += 1;
+                return;
+            }
+            const target = `xl/${rel.Target.replace(/^(\s|\/xl\/)+/, "")}`;
+            // Check if this is a chartsheet
+            const chartsheetMatch = /xl\/chartsheets\/sheet(\d+)\.xml/.exec(target);
+            if (chartsheetMatch) {
+                const csNo = parseInt(chartsheetMatch[1], 10);
+                const chartsheet = model.chartsheets?.[csNo];
+                if (chartsheet) {
+                    chartsheet.name = sheet.name;
+                    chartsheet.id = sheet.id;
+                    chartsheet.state = sheet.state;
+                    chartsheet.rId = sheet.rId;
+                    chartsheet.orderNo = sheetPosition;
+                    chartsheetsList.push(chartsheet);
+                }
+                sheetPosition += 1;
                 return;
             }
-            // if rel.Target start with `[space]/xl/` or `/xl/` , then it will be replaced with `''` and spliced behind `xl/`,
-            // otherwise it will be spliced directly behind `xl/`. i.g.
-            worksheet = model.worksheetHash[`xl/${rel.Target.replace(/^(\s|\/xl\/)+/, "")}`];
-            // If there are "chartsheets" in the file, rel.Target will
-            // come out as chartsheets/sheet1.xml or similar here, and
-            // that won't be in model.worksheetHash.
-            // As we don't have the infrastructure to support chartsheets,
-            // we will ignore them for now:
+            worksheet = model.worksheetHash[target];
             if (worksheet) {
                 worksheet.name = sheet.name;
                 worksheet.id = sheet.id;
                 worksheet.state = sheet.state;
-                worksheets[index++] = worksheet;
+                worksheet.orderNo = sheetPosition;
+                // Index by the workbook `<sheets>` position — not the
+                // compressed worksheet counter — so `definedName.localSheetId`
+                // resolves correctly when chartsheets are interleaved.
+                worksheets[sheetPosition] = worksheet;
             }
+            sheetPosition += 1;
         });
+        // Store reconciled chartsheets on the model
+        model.chartsheetsList = chartsheetsList;
         // reconcile print areas
         const definedNames = [];
         if (model.definedNames) {
@@ -263,8 +330,15 @@ class WorkbookXform extends BaseXform {
             });
         }
         model.definedNames = definedNames;
-        // used by sheets to build their image models
-        model.media.forEach((media, i) => {
+        // used by sheets to build their image models.
+        // Matches the `(model.media ?? []).forEach(...)` guard in
+        // `prepare` (line 144): `reconcile` may be called from code paths
+        // where `model.media` was never initialised (e.g. a programmatic
+        // workbook with no images; the xlsx reader populates this array,
+        // but builder-constructed workbooks do not). Without the guard,
+        // the forEach throws `TypeError: Cannot read properties of
+        // undefined (reading 'forEach')` and aborts the load/save cycle.
+        (model.media ?? []).forEach((media, i) => {
             media.index = i;
         });
     }

package/dist/browser/modules/excel/xlsx/xform/chart/chart-space-xform.d.ts

@@ -0,0 +1,353 @@
+/**
+ * ChartSpaceXform — Full OOXML DrawingML Chart parser and renderer.
+ *
+ * Design: single class with state-stack SAX parsing. Shape properties
+ * (c:spPr) and text properties (c:txPr) are captured as raw XML strings
+ * for perfect round-trip fidelity. Structured access is provided for the
+ * most commonly used properties.
+ *
+ * The c: namespace is http://schemas.openxmlformats.org/drawingml/2006/chart
+ * The a: namespace is http://schemas.openxmlformats.org/drawingml/2006/main
+ * The r: namespace is http://schemas.openxmlformats.org/officeDocument/2006/relationships
+ */
+import type { ChartModel } from "../../../chart/types.js";
+import { BaseXform } from "../base-xform.js";
+import type { XmlSink } from "../../../../xml/types.js";
+declare class ChartSpaceXform extends BaseXform<ChartModel> {
+    private stateStack;
+    private rawCapture;
+    private textBuf;
+    private chartModel;
+    private chartData;
+    private plotArea;
+    private currentChartTypeGroup;
+    private currentSeries;
+    private currentAxis;
+    private currentTitle;
+    private currentLegend;
+    private currentDataLabels;
+    private currentDataLabelEntry;
+    private currentMarker;
+    private currentDataPoint;
+    private currentTrendline;
+    private currentErrorBars;
+    private currentNumRef;
+    private currentStrRef;
+    private currentNumLit;
+    private currentStrLit;
+    private currentNumCache;
+    private currentStrCache;
+    private currentLayout;
+    private currentManualLayout;
+    private currentView3D;
+    private currentUpDownBars;
+    private currentLegendEntry;
+    private currentDataTable;
+    private currentDisplayUnits;
+    private currentPivotFormat;
+    private currentTrendlineLbl;
+    private currentPictureOptions;
+    private currentPrintSettings;
+    private currentMultiLvlStrRef;
+    private currentLvl;
+    /** Tracks c:floor / c:sideWall / c:backWall context */
+    private currentFloorWall;
+    /** Tracks c:hiLowLines / c:dropLines / c:serLines context */
+    private currentLineContext;
+    /** Pending spPr captured inside a line context element */
+    private _pendingLineSpPr;
+    private rawXmlTarget;
+    /** Context hint for c:extLst routing */
+    private rawCaptureContext;
+    /** Whether we are currently inside c:plotArea during parsing */
+    private insidePlotArea;
+    private rawSpPrXml;
+    private rawTxPrXml;
+    get tag(): string;
+    reset(): void;
+    render(xmlStream: XmlSink, model?: ChartModel): void;
+    /**
+     * Render the chart-space-level `<c:extLst>` element, merging the raw XML
+     * captured at parse time (`m.extLst`) with any structured pivot chart
+     * metadata (`m.pivotOptions`).
+     *
+     * The two inputs live side by side for good reason:
+     *   - `m.extLst` holds extensions we do not structurally understand
+     *     (c15 filtered series, c16r2 markup, c16r5 axis-title rich text…).
+     *     These are byte-preserved verbatim for round-trip safety.
+     *   - `m.pivotOptions` is the structured view of the MS Office 2010+
+     *     `c14:pivotOptions` extension. The parser extracts it out of the
+     *     raw extLst precisely so editors can read/mutate it programmatically
+     *     without string surgery.
+     *
+     * Merge strategy: if `m.extLst` is present, splice the new c14 ext
+     * element before its closing `</c:extLst>`; otherwise create a fresh
+     * `<c:extLst>` wrapper containing just the c14 ext.
+     */
+    private _renderChartSpaceExtLst;
+    /**
+     * Serialise the Office 2014+ `c16:pivotOptions16` extension
+     * (`c:chartSpace/c:extLst/c:ext[uri={E28EC0CA-…}]`). Only the
+     * `showExpandCollapseFieldButtons` toggle is modelled here — Excel
+     * adds this block alongside {@link _buildC14PivotOptionsExt} to
+     * control the newer expand/collapse field-button affordances.
+     *
+     * Returns `""` when nothing needs to be written so the caller can
+     * omit the extension entirely.
+     */
+    private _buildC16PivotOptions16Ext;
+    /**
+     * Serialise a {@link PivotChartOptions} as the `c:ext` wrapper Excel
+     * expects:
+     *
+     * ```xml
+     * <c:ext uri="{…}" xmlns:c14="http://schemas.microsoft.com/office/drawing/2007/8/2/chart">
+     *   <c14:pivotOptions>
+     *     <c14:dropZoneFilter val="0"/>
+     *     …
+     *   </c14:pivotOptions>
+     * </c:ext>
+     * ```
+     *
+     * The `uri` attribute is the well-known identifier for the c14 pivot
+     * options extension (see MS-XLSX §2.3.11). Excel 2010+ uses this URI as
+     * the key when deciding whether to honour the extension.
+     */
+    private _buildC14PivotOptionsExt;
+    private _renderChart;
+    private _renderView3D;
+    private _renderPlotArea;
+    private _renderChartTypeGroup;
+    private _renderBarChart;
+    /**
+     * Render a 3-D bar chart per `CT_Bar3DChart`. The 3-D schema DROPS
+     * `overlap` and `serLines` (both 2-D-only) and ADDS `gapDepth` and
+     * `shape`. The child order differs from 2-D:
+     *
+     *   barDir, grouping?, varyColors?, ser*, dLbls?, gapWidth?,
+     *   gapDepth?, shape?, axId{3}.
+     *
+     * Previously the builder shared `_renderBarChart` with bar2D, which
+     * emitted `overlap` / `serLines` on bar3D (schema violation) and put
+     * `shape` before `gapDepth` (sequence violation — Excel tolerates it
+     * on read, strict validators reject).
+     */
+    private _renderBar3DChart;
+    private _renderLineChart;
+    /**
+     * Render a 3-D line chart per `CT_Line3DChart`. Schema DROPS
+     * `hiLowLines`, `upDownBars`, `marker`, `smooth` (all 2-D-only) and
+     * ADDS `gapDepth`. Child order:
+     *
+     *   grouping, varyColors?, ser*, dLbls?, dropLines?, gapDepth?,
+     *   axId{3}.
+     *
+     * Previously the builder shared `_renderLineChart` with line2D,
+     * producing `<c:line3DChart>` with illegal children (most Excel-
+     * authored tools would still open the file, but strict validators
+     * reject it; more importantly, Excel's own read path silently
+     * ignored the illegal children, so the line3D chart lost its marker
+     * / smooth / up-down bars on round-trip).
+     */
+    private _renderLine3DChart;
+    private _renderPieChart;
+    /**
+     * Render `CT_DoughnutChart`. Child order matches the schema:
+     *   varyColors?, ser*, dLbls?, firstSliceAng?, holeSize?, extLst?.
+     *
+     * Excel's reader rejects `<c:dLblPos>` inside a doughnut chart's
+     * `<c:dLbls>` (both group-level and per-series). The Excel UI
+     * confirms this — the "Label Position" control is absent from the
+     * Format Data Labels panel for doughnut charts, whereas pie exposes
+     * center / inside end / outside end / best fit. Writing any
+     * `c:dLblPos` value (even `bestFit`) causes Excel to strip the
+     * entire `drawing1.xml` part on open with "Removed Part: Drawing
+     * shape".
+     *
+     * xlsxwriter hides this by forcibly nulling `labels["position"]`
+     * whenever the user-supplied position equals the chart's default
+     * ("best_fit" for pie/doughnut). That only masks the bug when the
+     * caller doesn't override the default; non-default positions still
+     * emit `c:dLblPos` and still break real-world doughnut files.
+     *
+     * The fix is to suppress `c:dLblPos` at serialisation time for
+     * doughnut — both in series `<c:dLbls>` and inside any per-point
+     * `<c:dLbl>` entries. `pie` and `ofPie` continue to emit it (they
+     * share `_renderPieSeries`, hence the explicit flag). The chart
+     * model still carries `position`, so SVG/PDF renderers keep using
+     * it for layout; only the XLSX writer filters it out.
+     */
+    private _renderDoughnutChart;
+    private _renderAreaChart;
+    private _renderScatterChart;
+    private _renderBubbleChart;
+    private _renderRadarChart;
+    private _renderStockChart;
+    private _renderSurfaceChart;
+    private _renderOfPieChart;
+    private _renderSeriesBase;
+    private _renderBarSeries;
+    private _renderLineSeries;
+    private _renderPieSeries;
+    private _renderAreaSeries;
+    private _renderScatterSeries;
+    private _renderBubbleSeries;
+    private _renderRadarSeries;
+    private _renderSurfaceSeries;
+    private _renderSeriesTx;
+    private _renderCatData;
+    private _renderValData;
+    private _renderNumRef;
+    private _renderStrRef;
+    private _renderNumCache;
+    private _renderStrCache;
+    private _renderNumLit;
+    private _renderStrLit;
+    private _renderMultiLvlStrRef;
+    private _renderMarker;
+    private _renderDataPoint;
+    /**
+     * Serialise a single {@link DataLabelEntry} as `<c:dLbl>…</c:dLbl>`.
+     * Shared between the series-level `<c:dLbls><c:dLbl/>` loop and
+     * pivot-format containers that emit a bare `<c:dLbl/>` without the
+     * enclosing `<c:dLbls>` wrapper.
+     */
+    private _renderDataLabelEntry;
+    private _renderDataLabels;
+    /**
+     * Serialise a {@link DataLabelsRange} as the `c:ext` wrapper Excel
+     * 2013+ expects:
+     *
+     * ```xml
+     * <c:ext uri="{CE6537A1-D6FC-4f65-9D91-7224C49458BB}"
+     *        xmlns:c15="http://schemas.microsoft.com/office/drawing/2012/chart">
+     *   <c15:datalabelsRange>
+     *     <c15:f>Sheet1!$A$1:$A$5</c15:f>
+     *     <c15:dlblRangeCache>
+     *       <c15:ptCount val="5"/>
+     *       <c15:pt idx="0"><c15:v>Label 1</c15:v></c15:pt>
+     *       …
+     *     </c15:dlblRangeCache>
+     *   </c15:datalabelsRange>
+     * </c:ext>
+     * ```
+     *
+     * The URI and child-element names are exactly what Excel emits —
+     * verified against a user-authored xlsx via
+     * `tmp/pivot-sample/xl/charts/chart1.xml` (the extension URI also
+     * appears as a placeholder inside `c:pivotFmt/c:dLbl`).
+     */
+    private _buildC15DataLabelsRangeExt;
+    private _renderTrendline;
+    private _renderErrorBars;
+    private _renderPictureOptions;
+    private _renderUpDownBars;
+    private _renderAxis;
+    private _renderTitle;
+    private _renderLegend;
+    private _renderLayout;
+    private _renderDataTable;
+    private _renderRichText;
+    private _renderBodyProperties;
+    private _renderParagraphProperties;
+    private _renderSpacing;
+    private _renderRunProperties;
+    private _renderSpPr;
+    /**
+     * Emit `<a:xfrm>` with optional `@rot` / `@flipH` / `@flipV` attributes
+     * and nested `<a:off>` / `<a:ext>`. Matches what `parseSpPr` captures in
+     * `shape-properties.ts`.
+     */
+    private _renderShapeTransform;
+    /**
+     * Emit `<a:prstGeom prst="…"><a:avLst>…</a:avLst></a:prstGeom>`. The
+     * `a:avLst` wrapper is always written (even when empty) to match Excel's
+     * own output; adjustments are optional inside.
+     */
+    private _renderPresetGeometry;
+    /**
+     * Emit `<a:custGeom>` with its adjustments list and the `<a:pathLst>`
+     * command stream. Commands map 1:1 to the DrawingML path command set
+     * (`moveTo` / `lnTo` / `arcTo` / `cubicBezTo` / `quadBezTo` / `close`);
+     * `arcTo` carries its parameters as attributes instead of control
+     * points, matching the parser.
+     */
+    private _renderCustomGeometry;
+    private _renderCustomGeometryCommand;
+    /**
+     * Render an `<a:blipFill>` element for a picture fill. The element is
+     * `<a:blipFill><a:blip r:embed="rIdN"/>[<a:srcRect …/>]<a:stretch …>
+     * or <a:tile …></a:blipFill>` matching the OOXML shape-fill subschema
+     * (DrawingML §20.1.8.14).
+     *
+     * Callers are responsible for making sure `blip.relationshipId` is
+     * populated — the writer no-ops when it is missing (see the comment
+     * at the call site in `_renderSpPr`).
+     */
+    private _renderBlipFill;
+    private _renderEffectList;
+    private _renderShadowElement;
+    private _renderScene3D;
+    private _renderSp3D;
+    private _renderTxPr;
+    private _renderColor;
+    private _renderPrintSettings;
+    parseOpen(node: any): boolean;
+    parseText(text: string): void;
+    parseClose(name: string): boolean;
+    private _createChartTypeGroup;
+    private _createAxis;
+    private _parseSeriesElement;
+    private _parseAxisElement;
+    private _handleValueClose;
+    private _attachNumRef;
+    private _attachStrRef;
+    private _attachNumLit;
+    private _attachStrLit;
+    private _attachMultiLvlStrRef;
+    private _findDataParent;
+    private _attachRawXml;
+    /**
+     * Parse the MS `c14:pivotOptions` extension out of a captured
+     * chartSpace-level `<c:extLst>` raw XML blob and populate
+     * {@link ChartModel.pivotOptions} with the structured view.
+     *
+     * Returns the raw XML with the matching `<c:ext uri="{781A…}" …/>`
+     * element removed so the writer does not emit it twice when it
+     * reconstructs the extLst from the merged (raw + structured) state.
+     * If the extension is absent, the input is returned unchanged.
+     *
+     * This function uses regex rather than a full XML parse because the
+     * raw blob is already guaranteed well-formed (it was emitted by our
+     * own raw-capture path) and we need to preserve byte exactness of the
+     * surviving `<c:ext>` elements for round-trip of extensions we do not
+     * understand.
+     */
+    private _extractChartSpaceExtLst;
+    /**
+     * Locate and remove a single `<c:ext uri="{…}">…</c:ext>` element
+     * whose `uri` matches `extUri`, passing the captured XML to
+     * `handler`. Returns the source string with the ext removed. When the
+     * ext is absent the input is returned unchanged.
+     */
+    private _extractAndStripPivotExt;
+    /**
+     * Parse and strip the MS `c15:datalabelsRange` extension (Excel 2013+
+     * "Value From Cells") from a captured `<c:dLbls>/<c:extLst>` raw XML
+     * blob, populating the structured {@link DataLabels.dataLabelsRange}
+     * slot on the given DataLabels object.
+     *
+     * Returns the raw XML with the matching ext element removed so the
+     * writer does not emit it twice when it reconstructs the extLst from
+     * the merged (raw + structured) state. If the extension is absent the
+     * input is returned unchanged.
+     */
+    private _extractDataLabelsExtLst;
+    private _setBoolOnLabels;
+    static CHART_SPACE_ATTRIBUTES: {
+        "xmlns:c": string;
+        "xmlns:a": string;
+        "xmlns:r": string;
+    };
+}
+export { ChartSpaceXform };