@rowsncolumns/toolkit 24.4.2 → 24.4.4

package/dist/esm/excel-parser/plugins/xlsx/index.js

@@ -2,9 +2,10 @@ import { addressToCell, addressToSelection, alpha2number, checkIfStringIsReferen
 import { XMLParser } from "fast-xml-parser";
 import { get } from "lodash-es";
 import { Parser as HtmlParser } from "htmlparser2";
-import { createFilterSpecsFromAutoFilter, excelColumnWidthToPixels, findMax, getRangeFromAddressRef, } from "../../helpers";
+import { createFilterSpecsFromAutoFilter, excelColumnWidthToPixels, findMax, getRangeFromAddressRef, parseTableColumnTotals, } from "../../helpers";
 import { defaultSpreadsheetTheme } from "../../theme-default";
 import { Unescape } from "../../utils";
+import { compactPrintSettings, isBuiltinPrintName, isDefaultPageMargins, parsePrintAreaFormula, parsePrintTitlesFormula, PRINT_AREA_NAME, } from "../../../print-settings";
 import { StreamingZipParser } from "../../zip-parser-streaming";
 import { SheetDataValidationStamper } from "../../dv-cell-stamp";
 import { BaseWorkbookPlugin } from "../base/index";
@@ -12,12 +13,14 @@ import { processChart } from "./charts";
 import { customFiltersToCondition, dynamicFilterToCondition, } from "../../../autofilter-condition";
 import { getConditionalFormattingFromSheet } from "./conditional-formatting";
 import { getDataValidationsForSheet as parseDataValidationsFromSheetData } from "./data-validations";
-import { processAnchors } from "./drawing";
+import { anchorsInDocumentOrder, processAnchors, } from "./drawing";
 import { getRelationsById } from "./relationships";
 import { hasPowerQueryParts, } from "../../../power-query";
 import { extractSheetViewProperties } from "./sheet-views";
 import { EMPTY_SHEET_THREADED_COMMENTS, parsePersons, parseThreadedComments, } from "./threaded-comments";
-import { extractColor, fontNodeToTextFormat, getCellDataForStyleIndex, getCellValueAndFormat, } from "./styles";
+import { getChartExReferenceFromAnchor, processChartEx } from "./chartex";
+import { buildFormControlEmbeds, parseFormControlPr, parseVmlControlCaptions, readLegacyDrawingRelId, readWorksheetControls, } from "./form-controls";
+import { extractColor, fontNodeToTextFormat, getCellDataForStyleIndex, getCellValueAndFormat, resolveNamedCellStyles, } from "./styles";
 import { extractThemeColors, extractThemeFonts, generateDarkThemeColors, } from "./theme";
 export const XMLTagProcessor = (name, value) => Unescape(value);
 function getWithFallback(source, paths) {
@@ -739,6 +742,18 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
      * `getDataValidations()` aggregates these per-sheet caches, keeping ids
      * stable across per-sheet and workbook-wide callers.
      */
+    /**
+     * `<protectedRanges>` per sheet, populated while `getSheets` builds each
+     * `Sheet` (the element sits after `<sheetData>` in the worksheet part, so it
+     * rides the same geometry pass). Read back via `getProtectedRanges`.
+     */
+    protectedRangesBySheet = new Map();
+    /**
+     * The builtin `_xlnm.Print_Area` / `_xlnm.Print_Titles` defined names,
+     * hoisted out of `namedRanges` (they are sheet-scoped facets, not user
+     * names) and merged into each sheet's `printSettings` by `getSheets()`.
+     */
+    printNamesBySheetId = new Map();
     dataValidationsBySheetCache = new Map();
     /** Per-sheet memo for conditional formatting, mirroring the DV cache. */
     conditionalFormattingBySheetCache = new Map();
@@ -784,6 +799,26 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
         let paneAttrs;
         let tabColor;
         let autoFilterRef;
+        // `<sheetProtection>` + `<protectedRanges>/<protectedRange>` — the sheet's
+        // protection facets, read here because both sit after `<sheetData>`.
+        let sheetProtection;
+        const protectedRangeEntries = [];
+        // Print facets (`CT_Worksheet` tail: printOptions / pageMargins /
+        // pageSetup / headerFooter / rowBreaks / colBreaks) plus the
+        // `<sheetPr><pageSetUpPr fitToPage>` flag. `_xlnm.Print_Area` /
+        // `_xlnm.Print_Titles` come from the workbook's defined names and are
+        // merged in by `getSheets()`.
+        let pageSetup;
+        let pageMargins;
+        let printOptions;
+        let fitToPage = false;
+        let headerFooter;
+        // The `<oddHeader>`-style element whose text is streaming in.
+        let headerFooterTextTarget;
+        const rowBreaks = [];
+        const columnBreaks = [];
+        // Inside `<rowBreaks>` ("row") / `<colBreaks>` ("column"); routes `<brk>`.
+        let breakAxis;
         const filterColumns = new Map();
         const getOrCreateFilterColumn = (colId) => {
             let entry = filterColumns.get(colId);
@@ -800,10 +835,21 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
         // r-less sheets still report real extents instead of 0.
         let lastScannedRowIndex = 0;
         let scanSeqColIndex = 1;
+        // `<customSheetViews>` (Excel's View → Custom Views) carry their own
+        // pane / selection / autoFilter / print setup / breaks. They describe a
+        // saved view, not the sheet, so the whole subtree is skipped — a custom
+        // view's `<oddHeader>` or `<brk>` must not become the sheet's.
+        let inCustomSheetViews = false;
         const normalizeTag = (name) => name.includes(":") ? name.split(":")[1] : name;
         const parser = new HtmlParser({
             onopentag(tagName, attrs) {
                 const name = normalizeTag(tagName);
+                if (name === "customSheetViews") {
+                    inCustomSheetViews = true;
+                    return;
+                }
+                if (inCustomSheetViews)
+                    return;
                 if (name === "dimension") {
                     const ref = attrs?.ref;
                     if (typeof ref === "string") {
@@ -849,6 +895,50 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
                 if (name === "tabColor") {
                     tabColor = { a$: { ...attrs } };
                 }
+                if (name === "sheetProtection") {
+                    sheetProtection = readSheetProtectionAttrs(attrs);
+                }
+                if (name === "protectedRange") {
+                    const sqref = attrs.sqref;
+                    if (typeof sqref === "string" && sqref) {
+                        protectedRangeEntries.push({
+                            sqref,
+                            name: attrs.name,
+                            securityDescriptor: attrs.securityDescriptor,
+                        });
+                    }
+                }
+                if (name === "pageSetUpPr") {
+                    fitToPage = isXmlTrue(attrs?.fitToPage);
+                }
+                if (name === "pageSetup") {
+                    pageSetup = readPageSetupAttrs(attrs);
+                }
+                if (name === "pageMargins") {
+                    pageMargins = readPageMarginsAttrs(attrs);
+                }
+                if (name === "printOptions") {
+                    printOptions = readPrintOptionsAttrs(attrs);
+                }
+                if (name === "headerFooter") {
+                    headerFooter = readHeaderFooterAttrs(attrs);
+                }
+                if (isHeaderFooterTextKey(name)) {
+                    headerFooterTextTarget = name;
+                    headerFooter ??= {};
+                }
+                if (name === "rowBreaks")
+                    breakAxis = "row";
+                if (name === "colBreaks")
+                    breakAxis = "column";
+                if (name === "brk" && breakAxis) {
+                    // Only manual breaks are user state; Excel drops automatic ones
+                    // (`man` absent) on save as well.
+                    const id = parseInt(attrs?.id ?? "", 10);
+                    if (Number.isFinite(id) && id > 0 && isXmlTrue(attrs?.man)) {
+                        (breakAxis === "row" ? rowBreaks : columnBreaks).push(id);
+                    }
+                }
                 if (name === "sheetView" && !sheetViewAttrs) {
                     sheetViewAttrs = { ...attrs };
                 }
@@ -1037,11 +1127,29 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
                     }
                 }
             },
+            ontext(text) {
+                if (headerFooterTextTarget && headerFooter) {
+                    headerFooter[headerFooterTextTarget] =
+                        `${headerFooter[headerFooterTextTarget] ?? ""}${text}`;
+                }
+            },
             onclosetag(tagName) {
                 const name = normalizeTag(tagName);
+                if (name === "customSheetViews") {
+                    inCustomSheetViews = false;
+                    return;
+                }
+                if (inCustomSheetViews)
+                    return;
                 if (name === "filterColumn") {
                     currentFilterColumn = null;
                 }
+                if (isHeaderFooterTextKey(name)) {
+                    headerFooterTextTarget = undefined;
+                }
+                if (name === "rowBreaks" || name === "colBreaks") {
+                    breakAxis = undefined;
+                }
             },
             onerror(err) {
                 console.error("Streaming sheet metadata parse error", err);
@@ -1114,6 +1222,18 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
             tablePartIds,
             outlineSummaryBelow,
             outlineSummaryRight,
+            sheetProtection,
+            protectedRangeEntries,
+            printSettings: compactPrintSettings({
+                pageSetup: fitToPage ? { ...pageSetup, fitToPage: true } : pageSetup,
+                // Every Excel worksheet carries `<pageMargins>`; only non-default
+                // margins are user state worth modelling.
+                pageMargins: isDefaultPageMargins(pageMargins) ? undefined : pageMargins,
+                printOptions,
+                headerFooter,
+                rowBreaks,
+                columnBreaks,
+            }),
         };
     }
     /**
@@ -1292,6 +1412,7 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
             conditionalFormatting: false,
             dataValidations: false,
             drawing: false,
+            controls: false,
         };
         const sheetPath = this.resolveSheetPath(relation.target);
         const sheetRelPath = sheetPath.replace("worksheets", "worksheets/_rels") + ".rels";
@@ -1345,6 +1466,9 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
                     case "drawing":
                         features.drawing = true;
                         break;
+                    case "controls":
+                        features.controls = true;
+                        break;
                 }
                 if (name !== "hyperlink") {
                     return;
@@ -1816,6 +1940,7 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
         this.sheetMetadataCache.clear();
         this.dataValidationsBySheetCache.clear();
         this.conditionalFormattingBySheetCache.clear();
+        this.protectedRangesBySheet.clear();
         await this.loadWorkbookXml();
         this.relations = await this.getRelations();
         this.workbookStyles = await WorkbookStyles.load(this.zipParser, this.xmlParser);
@@ -1835,6 +1960,7 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
         this.sheetMetadataCache.clear();
         this.dataValidationsBySheetCache.clear();
         this.conditionalFormattingBySheetCache.clear();
+        this.protectedRangesBySheet.clear();
         this.worksheetBySheetId.clear();
     }
     clearSharedFormula() {
@@ -1924,7 +2050,10 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
                             : [];
                     const columns = columnDefsArray.map((colDef) => {
                         const name = colDef.a$.name || "";
-                        const columnObj = { name };
+                        const columnObj = {
+                            name,
+                            ...parseTableColumnTotals(colDef),
+                        };
                         // Check for calculated column
                         // Handle both with and without namespace prefix
                         const calculatedColumnFormula = get(colDef, "calculatedColumnFormula") ||
@@ -2798,6 +2927,19 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
                 for (const anchor of anchors) {
                     const chartRef = getChartReferenceFromAnchor(anchor);
                     if (!chartRef) {
+                        // Excel 2016+ chartex (treemap / sunburst / histogram …) anchors
+                        // carry `<cx:chart r:id>` inside an mc:AlternateContent choice.
+                        const chartExRef = getChartExReferenceFromAnchor(anchor);
+                        const chartExRId = get(chartExRef, "a$.r:id") || get(chartExRef, "a$.id");
+                        const chartExRel = chartExRId
+                            ? drawingRelsArray.find((rel) => get(rel, "a$.Id") === chartExRId ||
+                                get(rel, "a$.id") === chartExRId)
+                            : undefined;
+                        if (chartExRel) {
+                            const chartEx = await processChartEx(chartExRel.a$.Target, drawingPath, anchor, sheetId, this.zipParser, this.xmlParser, sheetDimensions, resolveSheetId);
+                            if (chartEx)
+                                charts.push(chartEx);
+                        }
                         continue;
                     }
                     const chartRId = get(chartRef, "a$.r:id") ||
@@ -2878,28 +3020,17 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
                         ? drawingPath.substring(1)
                         : `xl/${drawingPath}`;
                 }
-                const drawingContent = await this.zipParser.getText(drawingPath);
+                const drawingContent = (await this.zipParser.getText(drawingPath)) ?? "";
                 // Parse drawing XML
-                const drawing = this.xmlParser.parse(drawingContent ?? "");
-                // Extract image anchors - both absolute and cell anchors
-                // Handle different XML namespaces that might be used
-                const twoCellAnchors = get(drawing, "xdr:wsDr.xdr:twoCellAnchor") ||
-                    get(drawing, "wsDr.twoCellAnchor");
-                const oneCellAnchors = get(drawing, "xdr:wsDr.xdr:oneCellAnchor") ||
-                    get(drawing, "wsDr.oneCellAnchor");
-                const absoluteAnchors = get(drawing, "xdr:wsDr.xdr:absoluteAnchor") ||
-                    get(drawing, "wsDr.absoluteAnchor");
-                // One cell
-                for (const image of await processAnchors(oneCellAnchors, "oneCellAnchor", drawingPath, sheetId, this.zipParser, this.xmlParser)) {
-                    images.push(image);
-                }
-                // Two cell
-                for (const image of await processAnchors(twoCellAnchors, "twoCellAnchors", drawingPath, sheetId, this.zipParser, this.xmlParser)) {
-                    images.push(image);
-                }
-                // absoluteAnchors
-                for (const image of await processAnchors(absoluteAnchors, "absoluteAnchors", drawingPath, sheetId, this.zipParser, this.xmlParser)) {
-                    images.push(image);
+                const drawing = this.xmlParser.parse(drawingContent);
+                // Anchor order in the drawing part is Excel's z-order (first = back).
+                // The parse groups anchors by element name, so the document order
+                // across `oneCellAnchor` / `twoCellAnchor` / `absoluteAnchor` is
+                // recovered from the raw part and each anchor processed in that order.
+                for (const anchor of anchorsInDocumentOrder(drawing, drawingContent)) {
+                    for (const image of await processAnchors(anchor.node, anchor.kind, drawingPath, sheetId, this.zipParser, this.xmlParser)) {
+                        images.push(image);
+                    }
                 }
             }
         }
@@ -2924,6 +3055,10 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
     getTheme() {
         return this.theme ?? defaultSpreadsheetTheme;
     }
+    /** `<cellStyles>` resolved to cell formats (toolbar "Workbook styles" gallery). */
+    getNamedCellStyles() {
+        return resolveNamedCellStyles(this.workbookStyles);
+    }
     /**
      * The workbook default font — styles.xml fonts[0], the font every cell
      * without an explicit font inherits. Exporters pass this through so the
@@ -2949,7 +3084,43 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
     _getSheets() {
         return this.workSheets;
     }
+    /**
+     * Resolve a builtin print name to its sheet (`localSheetId` indexes the
+     * `<sheets>` order; a name without scope falls back to the sheet named in
+     * the formula) and record the parsed print area / titles for `getSheets()`.
+     */
+    stashBuiltinPrintName(name, expression, localSheetId, sheetIdBySheetName) {
+        if (!expression || expression.includes("#REF!"))
+            return;
+        const parsed = name === PRINT_AREA_NAME
+            ? parsePrintAreaFormula(expression)
+            : parsePrintTitlesFormula(expression);
+        if (!parsed)
+            return;
+        let sheetId;
+        if (localSheetId !== undefined) {
+            const index = parseInt(localSheetId, 10);
+            const sheetEl = this._getSheets()[index];
+            const id = Number(sheetEl?.a$?.sheetId);
+            if (Number.isFinite(id))
+                sheetId = id;
+        }
+        if (sheetId === undefined && parsed.sheetName) {
+            sheetId = sheetIdBySheetName[parsed.sheetName];
+        }
+        if (sheetId === undefined)
+            return;
+        const entry = this.printNamesBySheetId.get(sheetId) ?? {};
+        if ("ranges" in parsed) {
+            entry.printArea = parsed.ranges;
+        }
+        else {
+            entry.printTitles = parsed.titles;
+        }
+        this.printNamesBySheetId.set(sheetId, entry);
+    }
     _getNamedRanges() {
+        this.printNamesBySheetId.clear();
         const xml = this.workbookXml;
         const sheetIdBySheetName = this._getSheets().reduce((acc, element) => {
             if (element) {
@@ -2971,6 +3142,14 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
                 const name = defined_name.a$?.name;
                 const expression = defined_name.t$ || "";
                 const hidden = defined_name.a$.hidden === "1";
+                // `_xlnm.Print_Area` / `_xlnm.Print_Titles` are sheet-scoped print
+                // facets, not user names: they land on `sheet.printSettings` (see
+                // `getSheets()`), never in `namedRanges` — a global copy would make
+                // Excel repair the file on the next export.
+                if (isBuiltinPrintName(name)) {
+                    this.stashBuiltinPrintName(name, typeof expression === "string" ? expression : "", defined_name.a$?.localSheetId, sheetIdBySheetName);
+                    continue;
+                }
                 // Empty defined names are noise; nothing useful to round-trip.
                 // Hidden defined names ARE preserved — Excel uses them as scratch
                 // names for features like print areas and add-ins, and dropping
@@ -3162,7 +3341,21 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
                 sheet.visibility = visibility;
             }
             const metadata = await this.getSheetMetadata(rid);
-            const { merges, rowEntries, columnMetadata, maxRowIndex, maxColumnIndex, autoFilterRange, filterSpecs, sheetViewData, tabColor, sheetHasFilterMode, zeroHeight, defaultRowHeightPx, defaultColumnWidthPx, tablePartIds, outlineSummaryBelow, outlineSummaryRight, } = metadata;
+            const { merges, rowEntries, columnMetadata, maxRowIndex, maxColumnIndex, autoFilterRange, filterSpecs, sheetViewData, tabColor, sheetHasFilterMode, zeroHeight, defaultRowHeightPx, defaultColumnWidthPx, tablePartIds, outlineSummaryBelow, outlineSummaryRight, sheetProtection, protectedRangeEntries, printSettings, } = metadata;
+            if (sheetProtection) {
+                sheet.sheetProtection = sheetProtection;
+            }
+            {
+                const printNames = this.printNamesBySheetId.get(sheetId);
+                const merged = compactPrintSettings({
+                    ...printSettings,
+                    printArea: printNames?.printArea,
+                    printTitles: printNames?.printTitles,
+                });
+                if (merged)
+                    sheet.printSettings = merged;
+            }
+            this.protectedRangesBySheet.set(sheetId, protectedRangesFromEntries(sheetId, protectedRangeEntries));
             if (defaultRowHeightPx !== undefined) {
                 sheet.defaultRowHeight = defaultRowHeightPx;
             }
@@ -3203,7 +3396,7 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
             // counts
             let columnCount = 0;
             // gridlines / headers / zeros / zoom
-            const { frozenRowCount, frozenColumnCount, paneTopLeftCell, showGridLines, showRowColHeaders, showZeros, zoomScale, } = extractSheetViewProperties(sheetViewData);
+            const { frozenRowCount, frozenColumnCount, paneTopLeftCell, showGridLines, showRowColHeaders, showZeros, zoomScale, rightToLeft, } = extractSheetViewProperties(sheetViewData);
             sheet.frozenRowCount = frozenRowCount;
             sheet.frozenColumnCount = frozenColumnCount;
             if (paneTopLeftCell) {
@@ -3219,6 +3412,8 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
             if (zoomScale !== undefined && zoomScale !== 100) {
                 sheet.zoomScale = zoomScale;
             }
+            if (rightToLeft)
+                sheet.rightToLeft = true;
             // tab color
             if (tabColor) {
                 sheet.tabColor = extractColor(tabColor, this.workbookStyles.indexedColors);
@@ -3833,18 +4028,81 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
         for (const element of workSheets) {
             const sheetId = Number(element.a$.sheetId);
             const rid = element.a$["r:id"];
-            // Drawings are referenced from a worksheet-level <drawing> element;
-            // skip the full-DOM parse when the SAX pass saw none.
+            // Drawings are referenced from a worksheet-level <drawing> element and
+            // form controls from <controls>; skip the full-DOM parse when the SAX
+            // pass saw neither.
             const features = this.sheetFeatures.get(rid);
-            if (features && !features.drawing) {
+            if (features && !features.drawing && !features.controls) {
                 continue;
             }
             const sheet_data = await this.getSheetData(rid);
-            const drawings = await this._getDrawings(rid, sheetId, sheet_data);
-            allDrawings.push(...drawings);
+            if (!features || features.drawing) {
+                const drawings = await this._getDrawings(rid, sheetId, sheet_data);
+                allDrawings.push(...drawings);
+            }
+            if (!features || features.controls) {
+                allDrawings.push(...(await this._getFormControls(rid, sheetId, sheet_data)));
+            }
         }
         return allDrawings;
     }
+    /**
+     * Form controls: `<controls><control r:id>` → `xl/ctrlProps/ctrlPropN.xml`
+     * (+ the caption from the sheet's legacy VML part), as `formControl`
+     * embeds. Nothing is rendered interactively — they round-trip.
+     */
+    async _getFormControls(rid, sheetId, sheetData) {
+        const controls = readWorksheetControls(sheetData);
+        if (!controls.length)
+            return [];
+        const target = this.relations[rid].target;
+        const sheetPath = target.startsWith("/xl")
+            ? target.replace(/^\//gi, "")
+            : `xl/${target}`;
+        const sheetRelPath = sheetPath.replace("worksheets", "worksheets/_rels") + ".rels";
+        const relTargets = new Map();
+        try {
+            const sheetRels = this.xmlParser.parse(await this.zipParser.getText(sheetRelPath));
+            const list = get(sheetRels, "Relationships.Relationship");
+            for (const rel of Array.isArray(list) ? list : list ? [list] : []) {
+                const id = rel?.a$?.Id;
+                const relTarget = rel?.a$?.Target;
+                if (typeof id === "string" && typeof relTarget === "string") {
+                    relTargets.set(id, relTarget);
+                }
+            }
+        }
+        catch {
+            return [];
+        }
+        const ctrlProps = new Map();
+        for (const control of controls) {
+            if (!control.relId || ctrlProps.has(control.relId))
+                continue;
+            const relTarget = relTargets.get(control.relId);
+            if (!relTarget)
+                continue;
+            try {
+                const xml = await this.zipParser.getText(this.resolveRelationshipTarget(sheetPath, relTarget));
+                ctrlProps.set(control.relId, parseFormControlPr(this.xmlPreserveValueParser.parse(xml)));
+            }
+            catch {
+                // Missing ctrlProp part — the control is skipped below.
+            }
+        }
+        let captions = new Map();
+        const legacyRelId = readLegacyDrawingRelId(sheetData);
+        const vmlTarget = legacyRelId ? relTargets.get(legacyRelId) : undefined;
+        if (vmlTarget) {
+            try {
+                captions = parseVmlControlCaptions(await this.zipParser.getText(this.resolveRelationshipTarget(sheetPath, vmlTarget)));
+            }
+            catch {
+                // No VML part — controls import without captions.
+            }
+        }
+        return buildFormControlEmbeds({ controls, sheetId, ctrlProps, captions });
+    }
     async getCharts() {
         const allCharts = [];
         const workSheets = this._getSheets();
@@ -4117,6 +4375,18 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
         const sheet_data = await this.getSheetData(rid);
         return parseDataValidationsFromSheetData(this, sheetId, sheet_data, sheetName);
     }
+    /**
+     * Allow-edit ranges (`<protectedRanges>/<protectedRange>`) in the model the
+     * `protect-range` command writes: `protectedRangeId` = the source `name`,
+     * `range` = the first `sqref` area plus `sheetId`. Available after
+     * `getSheets()`; sheet-level `<sheetProtection>` rides `Sheet.sheetProtection`.
+     */
+    getProtectedRanges(sheetId) {
+        if (sheetId !== undefined) {
+            return this.protectedRangesBySheet.get(sheetId) ?? [];
+        }
+        return Array.from(this.protectedRangesBySheet.values()).flat();
+    }
     getNamedRanges() {
         return this.namedRanges;
     }
@@ -4652,3 +4922,155 @@ export class XlsxPlugin extends BaseWorkbookPlugin {
         return externalLinks;
     }
 }
+/** `CT_SheetProtection` boolean attributes, in OOXML order (camelCase = model key). */
+const SHEET_PROTECTION_FLAGS = [
+    "sheet",
+    "objects",
+    "scenarios",
+    "formatCells",
+    "formatColumns",
+    "formatRows",
+    "insertColumns",
+    "insertRows",
+    "insertHyperlinks",
+    "deleteColumns",
+    "deleteRows",
+    "selectLockedCells",
+    "sort",
+    "autoFilter",
+    "pivotTables",
+    "selectUnlockedCells",
+];
+/**
+ * `<sheetProtection …>` attributes → `Sheet.sheetProtection`. Only attributes
+ * present in the source are set (`"1"|"true"` → true, anything else → false),
+ * so an explicit flag round-trips without inventing schema defaults; the
+ * password hash (legacy `password` or the agile quartet) rides along verbatim.
+ * Mirrors `rnc-import`'s `read_sheet_protection`.
+ */
+const readSheetProtectionAttrs = (attrs) => {
+    const protection = {};
+    for (const flag of SHEET_PROTECTION_FLAGS) {
+        const value = attrs[flag];
+        if (value !== undefined) {
+            protection[flag] = value === "1" || value === "true";
+        }
+    }
+    if (attrs.password)
+        protection.password = attrs.password;
+    if (attrs.algorithmName)
+        protection.algorithmName = attrs.algorithmName;
+    if (attrs.hashValue)
+        protection.hashValue = attrs.hashValue;
+    if (attrs.saltValue)
+        protection.saltValue = attrs.saltValue;
+    if (attrs.spinCount !== undefined) {
+        const spinCount = parseInt(attrs.spinCount, 10);
+        if (Number.isFinite(spinCount))
+            protection.spinCount = spinCount;
+    }
+    return protection;
+};
+/**
+ * `<protectedRange sqref name>` entries → `ProtectedRange[]` for one sheet. The
+ * `name` becomes the `protectedRangeId` so it keys the stored facet and
+ * re-exports under the same name; only the first `sqref` area is modeled
+ * (Excel writes one per element in practice).
+ */
+const protectedRangesFromEntries = (sheetId, entries) => {
+    const ranges = [];
+    for (const entry of entries) {
+        const first = entry.sqref.trim().split(/\s+/)[0];
+        const range = first ? getRangeFromAddressRef(first) : undefined;
+        if (!range)
+            continue;
+        const protectedRange = {
+            range: { sheetId, ...range },
+        };
+        if (entry.name)
+            protectedRange.protectedRangeId = entry.name;
+        if (entry.securityDescriptor) {
+            protectedRange.securityDescriptor = entry.securityDescriptor;
+        }
+        ranges.push(protectedRange);
+    }
+    return ranges;
+};
+const isXmlTrue = (value) => value === "1" || value === "true";
+/** `"1"|"true"|"0"|"false"` → boolean; absent stays undefined. */
+const xmlBoolOpt = (value) => value === undefined ? undefined : isXmlTrue(value);
+const xmlIntOpt = (value) => {
+    if (value === undefined)
+        return undefined;
+    const n = parseInt(value, 10);
+    return Number.isFinite(n) ? n : undefined;
+};
+const xmlFloatOpt = (value) => {
+    if (value === undefined)
+        return undefined;
+    const n = parseFloat(value);
+    return Number.isFinite(n) ? n : undefined;
+};
+const stripUndefined = (value) => {
+    for (const key of Object.keys(value)) {
+        if (value[key] === undefined)
+            delete value[key];
+    }
+    return value;
+};
+/** `<headerFooter>` children whose text is a header/footer code string. */
+const HEADER_FOOTER_TEXT_ELEMENTS = [
+    "oddHeader",
+    "oddFooter",
+    "evenHeader",
+    "evenFooter",
+    "firstHeader",
+    "firstFooter",
+];
+const isHeaderFooterTextKey = (name) => HEADER_FOOTER_TEXT_ELEMENTS.includes(name);
+/**
+ * `<pageSetup …>` → `PageSetup` (present attributes only; `fitToPage` is
+ * filled from `<sheetPr><pageSetUpPr>` by the caller). Mirrors
+ * `rnc-import`'s `read_page_setup`.
+ */
+const readPageSetupAttrs = (attrs) => {
+    const orientation = attrs.orientation;
+    const pageOrder = attrs.pageOrder;
+    return stripUndefined({
+        orientation: orientation === "landscape" || orientation === "portrait"
+            ? orientation
+            : undefined,
+        paperSize: xmlIntOpt(attrs.paperSize),
+        scale: xmlIntOpt(attrs.scale),
+        fitToWidth: xmlIntOpt(attrs.fitToWidth),
+        fitToHeight: xmlIntOpt(attrs.fitToHeight),
+        firstPageNumber: xmlIntOpt(attrs.firstPageNumber),
+        useFirstPageNumber: xmlBoolOpt(attrs.useFirstPageNumber),
+        pageOrder: pageOrder === "overThenDown" || pageOrder === "downThenOver"
+            ? pageOrder
+            : undefined,
+        blackAndWhite: xmlBoolOpt(attrs.blackAndWhite),
+        draft: xmlBoolOpt(attrs.draft),
+    });
+};
+const readPageMarginsAttrs = (attrs) => stripUndefined({
+    left: xmlFloatOpt(attrs.left),
+    right: xmlFloatOpt(attrs.right),
+    top: xmlFloatOpt(attrs.top),
+    bottom: xmlFloatOpt(attrs.bottom),
+    header: xmlFloatOpt(attrs.header),
+    footer: xmlFloatOpt(attrs.footer),
+});
+const readPrintOptionsAttrs = (attrs) => stripUndefined({
+    gridLines: xmlBoolOpt(attrs.gridLines),
+    headings: xmlBoolOpt(attrs.headings),
+    horizontalCentered: xmlBoolOpt(attrs.horizontalCentered),
+    verticalCentered: xmlBoolOpt(attrs.verticalCentered),
+});
+/** `<headerFooter …>` attributes; the child texts stream in via `ontext`. */
+const readHeaderFooterAttrs = (attrs) => stripUndefined({
+    differentOddEven: xmlBoolOpt(attrs.differentOddEven),
+    differentFirst: xmlBoolOpt(attrs.differentFirst),
+    scaleWithDoc: xmlBoolOpt(attrs.scaleWithDoc),
+    alignWithMargins: xmlBoolOpt(attrs.alignWithMargins),
+});

package/dist/esm/excel-parser/plugins/xlsx/pivots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pivots.d.ts","sourceRoot":"","sources":["../../../../../excel-parser/plugins/xlsx/pivots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AASrE,KAAK,aAAa,GAAG;IACnB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AA6OF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS;IACP,SAAS,EAAE,kBAAkB,CAAC;IAC9B,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,mEAAmE;IACnE,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,kDAAkD;IAClD,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,cAAc,EAAE,MAAM,CAAC;CACxB,KACA,OAAO,CAAC,UAAU,EAAE,CAoEtB,CAAC"}
+{"version":3,"file":"pivots.d.ts","sourceRoot":"","sources":["../../../../../excel-parser/plugins/xlsx/pivots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAEV,UAAU,EAGX,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAoErE,KAAK,aAAa,GAAG;IACnB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAkQF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS;IACP,SAAS,EAAE,kBAAkB,CAAC;IAC9B,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,mEAAmE;IACnE,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,kDAAkD;IAClD,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,cAAc,EAAE,MAAM,CAAC;CACxB,KACA,OAAO,CAAC,UAAU,EAAE,CAsEtB,CAAC"}