@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/browser/modules/excel/xlsx/xform/sheet/chartsheet-xform.js

@@ -0,0 +1,441 @@
+/**
+ * ChartsheetXform — parse and render OOXML chartsheet XML.
+ *
+ * A chartsheet is a simple sheet type that contains only a chart.
+ * Structure (ECMA-376 `CT_Chartsheet`):
+ * ```xml
+ * <chartsheet xmlns="...">
+ *   <sheetPr/>?
+ *   <sheetViews><sheetView .../></sheetViews>
+ *   <sheetProtection/>?
+ *   <customSheetViews/>?
+ *   <pageMargins .../>?
+ *   <pageSetup .../>?        CT_CsPageSetup — NOT CT_PageSetup
+ *   <headerFooter/>?
+ *   <drawing r:id="rId1"/>
+ *   <legacyDrawing/>?  legacyDrawingHF?  drawingHF?  picture?  webPublishItems?  extLst?
+ * </chartsheet>
+ * ```
+ *
+ * Note that chartsheets do NOT support `printOptions`, `pageBreaks`,
+ * `rowBreaks`, or `colBreaks` — those are worksheet-only elements
+ * per ECMA-376 `CT_Chartsheet`. Likewise `<c:pageSetup>` on a
+ * chartsheet is `CT_CsPageSetup`, which has a reduced attribute set
+ * compared to the worksheet's `CT_PageSetup` (no `scale`,
+ * `fitToWidth`, `fitToHeight`, `pageOrder`, `cellComments`, or
+ * `errors`).
+ */
+import { BaseXform } from "../base-xform.js";
+import { parseXsdBoolean, parseXsdInt } from "../xsd-values.js";
+import { xmlEncode as escapeXml, xmlEncodeAttr } from "../../../../xml/encode.js";
+const CHARTSHEET_ATTRIBUTES = {
+    xmlns: "http://schemas.openxmlformats.org/spreadsheetml/2006/main",
+    "xmlns:r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+};
+class ChartsheetXform extends BaseXform {
+    constructor() {
+        super(...arguments);
+        this.inSheetView = false;
+        this.captureDepth = 0;
+        this.captureParts = [];
+        this.skipNextCaptureClose = false;
+        this.sheetDepth = 0;
+    }
+    get tag() {
+        return "chartsheet";
+    }
+    render(xmlStream, model) {
+        const m = model ?? this.model;
+        if (!m) {
+            return;
+        }
+        xmlStream.openNode("chartsheet", CHARTSHEET_ATTRIBUTES);
+        // `CT_Chartsheet` schema sequence:
+        //   sheetPr?, sheetViews, sheetProtection?, customSheetViews?,
+        //   pageMargins?, pageSetup?, headerFooter?,
+        //   drawing, legacyDrawing?, legacyDrawingHF?, drawingHF?,
+        //   picture?, webPublishItems?, extLst?
+        //
+        // Elements we don't structurally model (most of the tail) are
+        // captured as raw XML via `rawChildren` and re-emitted at the
+        // correct sequence position so round-tripping a chartsheet with
+        // `sheetProtection` / `headerFooter` / `legacyDrawing` doesn't
+        // drop them.
+        //
+        // Notably absent: `printOptions`, `pageBreaks`, `rowBreaks`,
+        // `colBreaks` — all worksheet-only per ECMA-376 `CT_Chartsheet`.
+        // Legacy workbooks that stored them in chartsheets are silently
+        // stripped; Excel itself also ignores them at load time.
+        const raw = m.rawChildren ?? {};
+        const writeRaw = (name) => {
+            const xml = raw[name];
+            if (xml) {
+                xmlStream.writeRaw(xml);
+            }
+        };
+        writeRaw("sheetPr");
+        // sheetViews
+        xmlStream.openNode("sheetViews");
+        // Preserve the author's `workbookViewId` (0-based index into the
+        // workbook's `<bookViews>` list). Default is 0 per schema; writing
+        // 0 explicitly is harmless and matches the wire shape Excel emits.
+        const svAttrs = {
+            workbookViewId: String(m.workbookViewId ?? 0)
+        };
+        if (m.tabSelected) {
+            svAttrs.tabSelected = "1";
+        }
+        if (m.zoomScale !== undefined) {
+            svAttrs.zoomScale = String(m.zoomScale);
+        }
+        if (m.zoomToFit) {
+            svAttrs.zoomToFit = "1";
+        }
+        xmlStream.leafNode("sheetView", svAttrs);
+        xmlStream.closeNode();
+        writeRaw("sheetProtection");
+        writeRaw("customSheetViews");
+        // pageMargins
+        if (m.pageMargins) {
+            const pm = m.pageMargins;
+            xmlStream.leafNode("pageMargins", {
+                left: pm.left !== undefined ? String(pm.left) : pm.l !== undefined ? String(pm.l) : "0.7",
+                right: pm.right !== undefined ? String(pm.right) : pm.r !== undefined ? String(pm.r) : "0.7",
+                top: pm.top !== undefined ? String(pm.top) : pm.t !== undefined ? String(pm.t) : "0.75",
+                bottom: pm.bottom !== undefined ? String(pm.bottom) : pm.b !== undefined ? String(pm.b) : "0.75",
+                header: pm.header !== undefined ? String(pm.header) : "0.3",
+                footer: pm.footer !== undefined ? String(pm.footer) : "0.3"
+            });
+        }
+        // pageSetup — note this is `CT_CsPageSetup`, NOT the worksheet's
+        // `CT_PageSetup`. The attribute set is narrower: no `scale`,
+        // `fitToWidth`, `fitToHeight`, `pageOrder`, `cellComments`, or
+        // `errors`. `definedAttrs` emits only fields with defined values,
+        // and the `ChartsheetModel["pageSetup"]` type constrains the
+        // permitted field set at compile time.
+        if (m.pageSetup) {
+            // `rId` rides on this element as `r:id` (namespaced). Project
+            // the model's camel-case `rId` onto the wire name and pass the
+            // rest through `definedAttrs`. Previously the parser dropped
+            // `r:id` entirely and the writer never emitted it, so printer-
+            // settings rels preserved in the chartsheet .rels went
+            // unreferenced inside the XML.
+            const { rId, ...pageSetupAttrs } = m.pageSetup;
+            const attrs = definedAttrs(pageSetupAttrs);
+            if (rId !== undefined) {
+                attrs["r:id"] = rId;
+            }
+            xmlStream.leafNode("pageSetup", attrs);
+        }
+        writeRaw("headerFooter");
+        // drawing
+        if (m.drawing) {
+            xmlStream.leafNode("drawing", { "r:id": m.drawing.rId });
+        }
+        writeRaw("legacyDrawing");
+        writeRaw("legacyDrawingHF");
+        writeRaw("drawingHF");
+        writeRaw("picture");
+        writeRaw("webPublishItems");
+        writeRaw("extLst");
+        xmlStream.closeNode();
+    }
+    parseOpen(node) {
+        var _a;
+        const { name } = node;
+        const attrs = node.attributes || {};
+        const isSelfClosing = !!node.isSelfClosing;
+        // If we're already inside a raw-captured element, serialise every
+        // child / text node into the capture buffer regardless of name —
+        // we don't want to structurally interpret children of, say,
+        // `<sheetProtection>`. Honour `isSelfClosing` so the captured
+        // bytes match the original encoding (self-closing `<foo/>` stays
+        // `<foo/>`, not `<foo></foo>`).
+        if (this.captureRoot) {
+            if (isSelfClosing) {
+                // Self-closing within a capture: append the `<foo/>` bytes
+                // verbatim and instruct `parseClose` to skip the synthetic
+                // close SAX will fire next. Depth stays where it was — a
+                // self-close neither enters nor leaves a level.
+                this.captureParts.push(selfCloseTag(node));
+                this.skipNextCaptureClose = true;
+            }
+            else {
+                this.captureDepth++;
+                this.captureParts.push(openTag(node));
+            }
+            return true;
+        }
+        // Track depth from the `<chartsheet>` root so the raw-capture
+        // dispatch only fires for direct children. Without this guard a
+        // nested `<extLst>` (or any other RAW_CAPTURE_TAG name reused
+        // inside a container we don't structurally model) would be
+        // promoted to a sibling of `<chartsheet>` — clobbering whichever
+        // capture was meant to contain it.
+        if (name === "chartsheet") {
+            this.sheetDepth = 1;
+            this.model = {
+                sheetNo: 0,
+                name: "",
+                id: 0
+            };
+            return true;
+        }
+        this.sheetDepth += 1;
+        // Start a fresh capture for any DIRECT chartsheet child that we
+        // don't structurally model. `sheetDepth === 2` means we're one
+        // level below the `<chartsheet>` root.
+        if (this.sheetDepth === 2 && RAW_CAPTURE_TAGS.has(name)) {
+            if (isSelfClosing) {
+                // Empty placeholder (e.g. `<extLst/>`) — store its bytes
+                // verbatim and don't enter the multi-event capture loop.
+                // The matching `parseClose` must also decrement
+                // `sheetDepth`, so we flag to skip stateful close work.
+                ((_a = this.model).rawChildren ?? (_a.rawChildren = {}))[name] = selfCloseTag(node);
+                // No capture state to clear; `parseClose` handles the
+                // close via its fall-through and decrements `sheetDepth`.
+                return true;
+            }
+            this.captureRoot = name;
+            this.captureDepth = 1;
+            this.captureParts = [openTag(node)];
+            return true;
+        }
+        switch (name) {
+            case "sheetView":
+                this.inSheetView = true;
+                if (this.model) {
+                    // Use the shared `xsd:boolean` parser — previously this
+                    // switch only accepted `"1"` and silently mapped `"true"`
+                    // (the other spec-legal form, emitted by many third-party
+                    // writers) to `false`, so chartsheets authored elsewhere
+                    // lost their `tabSelected` / `zoomToFit` state on round-trip.
+                    const parsedTabSelected = parseXsdBoolean(attrs.tabSelected);
+                    if (parsedTabSelected !== undefined) {
+                        this.model.tabSelected = parsedTabSelected;
+                    }
+                    const parsedZoom = parseXsdInt(attrs.zoomScale);
+                    if (parsedZoom !== undefined) {
+                        this.model.zoomScale = parsedZoom;
+                    }
+                    // Round-trip `workbookViewId` — default 0 is only omitted
+                    // when the attribute was absent on the wire; preserve an
+                    // explicit 0 if the author wrote it, else leave undefined
+                    // so `render` falls back to its `?? 0` default.
+                    const parsedViewId = parseXsdInt(attrs.workbookViewId);
+                    if (parsedViewId !== undefined) {
+                        this.model.workbookViewId = parsedViewId;
+                    }
+                    const parsedZoomToFit = parseXsdBoolean(attrs.zoomToFit);
+                    if (parsedZoomToFit !== undefined) {
+                        this.model.zoomToFit = parsedZoomToFit;
+                    }
+                }
+                break;
+            case "pageMargins":
+                if (this.model) {
+                    this.model.pageMargins = {
+                        l: parseMargin(attrs.left),
+                        r: parseMargin(attrs.right),
+                        t: parseMargin(attrs.top),
+                        b: parseMargin(attrs.bottom),
+                        left: parseMargin(attrs.left),
+                        right: parseMargin(attrs.right),
+                        top: parseMargin(attrs.top),
+                        bottom: parseMargin(attrs.bottom),
+                        header: parseMargin(attrs.header),
+                        footer: parseMargin(attrs.footer)
+                    };
+                }
+                break;
+            case "printOptions":
+                // Worksheet-only element per ECMA-376 `CT_Chartsheet`.
+                // Silently skip — the containing file is malformed but Excel
+                // itself ignores the element at load, so preserving it in
+                // `rawChildren` would re-emit invalid XML on save.
+                break;
+            case "rowBreaks":
+            case "colBreaks":
+            case "pageBreaks":
+                // Same as `printOptions`: worksheet-only. Drop on load.
+                break;
+            case "pageSetup":
+                if (this.model) {
+                    // `CT_CsPageSetup` — the chartsheet variant. Only the
+                    // attributes listed in ECMA-376 18.3.1.68 are captured;
+                    // worksheet-only attributes (`scale`, `fitToWidth`,
+                    // `fitToHeight`, `pageOrder`, `cellComments`, `errors`)
+                    // are silently discarded so re-serialised XML matches
+                    // `CT_CsPageSetup`.
+                    this.model.pageSetup = {
+                        paperSize: parseNumber(attrs.paperSize),
+                        firstPageNumber: parseNumber(attrs.firstPageNumber),
+                        orientation: attrs.orientation,
+                        usePrinterDefaults: parseBool(attrs.usePrinterDefaults),
+                        blackAndWhite: parseBool(attrs.blackAndWhite),
+                        draft: parseBool(attrs.draft),
+                        useFirstPageNumber: parseBool(attrs.useFirstPageNumber),
+                        horizontalDpi: parseNumber(attrs.horizontalDpi),
+                        verticalDpi: parseNumber(attrs.verticalDpi),
+                        copies: parseNumber(attrs.copies),
+                        paperHeight: attrs.paperHeight,
+                        paperWidth: attrs.paperWidth,
+                        // Capture the printer-settings rel id so the writer can
+                        // emit `r:id="…"` back on round-trip. Without this the
+                        // pre-existing `printerSettings` rel target in the
+                        // chartsheet .rels file was preserved (via
+                        // `relationships`) but the XML lost its reference to it —
+                        // a dangling rel in the saved package.
+                        rId: attrs["r:id"]
+                    };
+                }
+                break;
+            case "drawing":
+                if (this.model && attrs["r:id"]) {
+                    this.model.drawing = { rId: attrs["r:id"] };
+                }
+                break;
+            default:
+                break;
+        }
+        // Self-closing leaf at direct-child level: SAX fires a closetag
+        // next which would decrement `sheetDepth` — so we do nothing
+        // extra here. The increment above already covered the "open"
+        // half of the event; the close will balance it.
+        if (isSelfClosing) {
+            // Balance the increment we just did so `parseClose` sees the
+            // expected post-state (the SAX emitter will still fire a
+            // `closetag` but our `parseClose` is a no-op for these names).
+            // Equivalent: leave `sheetDepth` incremented and let the
+            // subsequent `closetag` decrement it. We choose the latter for
+            // consistency with non-self-closing paths.
+        }
+        return true;
+    }
+    parseText(text) {
+        // Pass text content through to the raw-capture buffer when we're
+        // recording an unmodeled element. Top-level chartsheet children
+        // have no meaningful text content (everything is element-based),
+        // so we ignore text outside capture mode.
+        if (this.captureRoot && text) {
+            this.captureParts.push(escapeXml(text));
+        }
+    }
+    parseClose(name) {
+        var _a;
+        // Close-tag inside an active capture — pop depth and decide
+        // whether the capture ends here.
+        if (this.captureRoot) {
+            if (this.skipNextCaptureClose) {
+                // This close is the synthetic half of a self-closing tag we
+                // already wrote as `<foo/>`. Swallow it without touching
+                // `captureDepth`.
+                this.skipNextCaptureClose = false;
+                return true;
+            }
+            this.captureDepth--;
+            this.captureParts.push(`</${name}>`);
+            if (this.captureDepth === 0) {
+                // Capture complete — store the serialised XML and reset state.
+                if (this.model) {
+                    ((_a = this.model).rawChildren ?? (_a.rawChildren = {}))[this.captureRoot] = this.captureParts.join("");
+                }
+                this.captureRoot = undefined;
+                this.captureParts = [];
+                this.sheetDepth -= 1;
+            }
+            return true;
+        }
+        this.sheetDepth -= 1;
+        switch (name) {
+            case "chartsheet":
+                return false;
+            case "sheetView":
+                this.inSheetView = false;
+                return true;
+            default:
+                return true;
+        }
+    }
+}
+/**
+ * Chartsheet children we don't structurally model but preserve as raw
+ * XML bytes for round-trip. Adding a new structured path for one of
+ * these elements means (a) remove it from this set and (b) add the
+ * matching `parseOpen` case + `render` emission.
+ *
+ * Note: `rowBreaks`, `colBreaks`, `pageBreaks`, and `printOptions`
+ * are NOT in this set — they are worksheet-only elements per
+ * ECMA-376 `CT_Chartsheet`. A legacy file that has them is silently
+ * dropped on load to produce schema-valid output.
+ */
+const RAW_CAPTURE_TAGS = new Set([
+    "sheetPr",
+    "sheetProtection",
+    "customSheetViews",
+    "headerFooter",
+    "legacyDrawing",
+    "legacyDrawingHF",
+    "drawingHF",
+    "picture",
+    "webPublishItems",
+    "extLst"
+]);
+/**
+ * Build the opening `<tag attr="…" …>` string for a SAX event. Shared
+ * with the chart-space xform's `RawXmlCapture` but inlined here to
+ * keep the chartsheet module self-contained (chart-space depends on
+ * this module's exports, so we can't reach into it without a cycle).
+ */
+function openTag(node) {
+    let s = `<${node.name}`;
+    if (node.attributes) {
+        for (const [k, v] of Object.entries(node.attributes)) {
+            s += ` ${k}="${xmlEncodeAttr(String(v))}"`;
+        }
+    }
+    return `${s}>`;
+}
+/**
+ * Build a self-closing `<tag attr="…"/>` string. Used when the SAX
+ * parser reports `isSelfClosing === true` so the captured bytes match
+ * the original form — emitting `<tag></tag>` instead breaks
+ * byte-for-byte round-trip and can confuse diff tools comparing the
+ * reserialised package against the original.
+ */
+function selfCloseTag(node) {
+    let s = `<${node.name}`;
+    if (node.attributes) {
+        for (const [k, v] of Object.entries(node.attributes)) {
+            s += ` ${k}="${xmlEncodeAttr(String(v))}"`;
+        }
+    }
+    return `${s}/>`;
+}
+function definedAttrs(model) {
+    const attrs = {};
+    for (const [key, value] of Object.entries(model)) {
+        if (value !== undefined) {
+            attrs[key] = typeof value === "boolean" ? (value ? "1" : "0") : String(value);
+        }
+    }
+    return attrs;
+}
+function parseBool(value) {
+    return value === undefined ? undefined : value === "1" || value === "true";
+}
+function parseMargin(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const n = parseFloat(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+function parseNumber(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+export { ChartsheetXform };

package/dist/browser/modules/excel/xlsx/xform/sheet/ext-lst-xform.d.ts

@@ -5,6 +5,7 @@ declare class ExtLstXform extends CompositeXform {
     };
     model: any;
     private ext;
+    private sparklineExt;
     constructor();
     get tag(): string;
     prepare(model: any, _options?: any): void;

package/dist/browser/modules/excel/xlsx/xform/sheet/ext-lst-xform.js

@@ -1,3 +1,4 @@
+import { renderSparklineGroups, parseSparklineGroups } from "../../../sparkline/index.js";
 import { CompositeXform } from "../composite-xform.js";
 import { ConditionalFormattingsExtXform } from "./cf-ext/conditional-formattings-ext-xform.js";
 class ExtXform extends CompositeXform {
@@ -32,9 +33,52 @@ class ExtXform extends CompositeXform {
         this.model[name] = parser.model;
     }
 }
+/**
+ * Lightweight xform for the sparkline extension block.
+ * Renders/captures `<ext uri="{05C60535-...}">` containing x14:sparklineGroups.
+ */
+class SparklineExtXform {
+    constructor() {
+        this._parsedModel = null;
+    }
+    get tag() {
+        return "ext";
+    }
+    hasContent(sparklineGroups) {
+        return Array.isArray(sparklineGroups) && sparklineGroups.length > 0;
+    }
+    render(xmlStream, sparklineGroups) {
+        if (!this.hasContent(sparklineGroups)) {
+            return;
+        }
+        // The canonical Microsoft-registered extension uri for
+        // `x14:sparklineGroups` is
+        //   {05C60535-1F16-4fd2-B633-F4F36F0B64E0}
+        // as emitted by Excel 2010 through Excel 365. Earlier
+        // revisions of this file used the WRONG uri
+        // `{05C60535-1F16-4fd2-B633-F4F36F0041E1}` (a typo that
+        // looked plausible but doesn't match any registered
+        // extension). Excel's MC processor — which is designed to
+        // silently skip unknown extension uris — dropped the whole
+        // `<ext>` element on load, erasing every sparkline the
+        // workbook defined. Verified against a Microsoft Excel 2021
+        // sparkline reference (`tmp/ccccc.xlsx`); switching to the
+        // correct uri restored sparkline rendering.
+        xmlStream.openNode("ext", {
+            uri: "{05C60535-1F16-4fd2-B633-F4F36F0B64E0}",
+            "xmlns:x14": "http://schemas.microsoft.com/office/spreadsheetml/2009/9/main"
+        });
+        xmlStream.writeRaw(renderSparklineGroups(sparklineGroups));
+        xmlStream.closeNode();
+    }
+    parse(xml) {
+        return parseSparklineGroups(xml);
+    }
+}
 class ExtLstXform extends CompositeXform {
     constructor() {
         super();
+        this.sparklineExt = new SparklineExtXform();
         this.map = {
             ext: (this.ext = new ExtXform())
         };
@@ -46,14 +90,19 @@ class ExtLstXform extends CompositeXform {
         this.ext.prepare(model);
     }
     hasContent(model) {
-        return this.ext.hasContent(model);
+        return this.ext.hasContent(model) || this.sparklineExt.hasContent(model?.sparklineGroups);
     }
     render(xmlStream, model) {
         if (!this.hasContent(model)) {
             return;
         }
         xmlStream.openNode("extLst");
-        this.ext.render(xmlStream, model);
+        if (this.ext.hasContent(model)) {
+            this.ext.render(xmlStream, model);
+        }
+        if (this.sparklineExt.hasContent(model?.sparklineGroups)) {
+            this.sparklineExt.render(xmlStream, model.sparklineGroups);
+        }
         xmlStream.closeNode();
     }
     createNewModel() {