@rowsncolumns/toolkit 24.4.3 → 24.4.4

package/dist/cjs/excel-parser/plugins/xlsx/chartex.js

@@ -0,0 +1,244 @@
+import { __assign, __awaiter, __generator, __read, __spreadArray, __values } from "tslib";
+import { generateSelectionsFromFormula, uuid } from "@rowsncolumns/utils";
+import { get } from "lodash-es";
+import { extractChartPosition, } from "./charts";
+/**
+ * Excel 2016+ "chartex" charts (`xl/charts/chartEx{N}.xml`, namespace
+ * `http://schemas.microsoft.com/office/drawing/2014/chartex`): treemap,
+ * sunburst, histogram / pareto, box & whisker, waterfall, funnel. They are
+ * anchored through an `mc:AlternateContent` whose `Choice` graphic frame
+ * carries `<cx:chart r:id>` instead of `<c:chart>`, and their data lives in
+ * `<cx:chartData><cx:data>` dimensions (`strDim type="cat"` for the
+ * hierarchy, `numDim type="size"|"val"` for the numbers) referenced by the
+ * series through `<cx:dataId>`.
+ *
+ * The exporter counterpart is `exporter/xlsx/chartex-builder.ts`.
+ */
+export var CHART_EX_REL_TYPE = "http://schemas.microsoft.com/office/2014/relationships/chartEx";
+export var CHART_EX_GRAPHIC_URI = "http://schemas.microsoft.com/office/drawing/2014/chartex";
+var asArray = function (value) {
+    return value == null ? [] : Array.isArray(value) ? value : [value];
+};
+/** Read a child by local name, tolerating any namespace prefix. */
+var child = function (node, localName) {
+    var e_1, _a;
+    if (!node || typeof node !== "object")
+        return undefined;
+    if (node[localName] !== undefined)
+        return node[localName];
+    try {
+        for (var _b = __values(Object.keys(node)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var key = _c.value;
+            var colon = key.indexOf(":");
+            if (colon >= 0 && key.slice(colon + 1) === localName)
+                return node[key];
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return undefined;
+};
+var textOf = function (node) {
+    if (node == null)
+        return undefined;
+    if (typeof node === "object") {
+        var inner = node.t$;
+        return inner == null ? undefined : String(inner);
+    }
+    return String(node);
+};
+/**
+ * `<cx:chart r:id>` inside an anchor's `mc:AlternateContent` choice (Excel
+ * also writes a plain `xdr:graphicFrame` for some producers — both forms are
+ * checked). Returns the `cx:chart` node or undefined for non-chartex anchors.
+ */
+export function getChartExReferenceFromAnchor(anchor) {
+    var e_2, _a, e_3, _b, e_4, _c;
+    var frames = [];
+    try {
+        for (var _d = __values(asArray(child(anchor, "AlternateContent"))), _e = _d.next(); !_e.done; _e = _d.next()) {
+            var alternate = _e.value;
+            try {
+                for (var _f = (e_3 = void 0, __values(asArray(child(alternate, "Choice")))), _g = _f.next(); !_g.done; _g = _f.next()) {
+                    var choice = _g.value;
+                    frames.push.apply(frames, __spreadArray([], __read(asArray(child(choice, "graphicFrame"))), false));
+                }
+            }
+            catch (e_3_1) { e_3 = { error: e_3_1 }; }
+            finally {
+                try {
+                    if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+                }
+                finally { if (e_3) throw e_3.error; }
+            }
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    frames.push.apply(frames, __spreadArray([], __read(asArray(child(anchor, "graphicFrame"))), false));
+    try {
+        for (var frames_1 = __values(frames), frames_1_1 = frames_1.next(); !frames_1_1.done; frames_1_1 = frames_1.next()) {
+            var frame = frames_1_1.value;
+            var graphicData = child(child(frame, "graphic"), "graphicData");
+            if (!graphicData)
+                continue;
+            var uri = get(graphicData, "a$.uri");
+            var cxChart = child(graphicData, "chart");
+            if (uri === CHART_EX_GRAPHIC_URI && cxChart)
+                return cxChart;
+            // A `cx:`-prefixed chart element without the uri attribute (defensive).
+            if (cxChart && Object.keys(graphicData).some(function (k) { return k.startsWith("cx:"); })) {
+                return cxChart;
+            }
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (frames_1_1 && !frames_1_1.done && (_c = frames_1.return)) _c.call(frames_1);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+    return undefined;
+}
+/** `layoutId` → engine chart type. Unknown layouts are not imported. */
+var CHART_TYPE_BY_LAYOUT = {
+    treemap: "treemap",
+    sunburst: "sunburst",
+    waterfall: "waterfall",
+    funnel: "funnel",
+    boxWhisker: "boxplot",
+    // `clusteredColumn` is a histogram / pareto only when it carries `<cx:binning>`.
+};
+var sourcesFromRef = function (ref, hostSheetId, resolveSheetId) {
+    if (!ref)
+        return [];
+    var selections = generateSelectionsFromFormula("=".concat(ref));
+    return selections.map(function (sel) {
+        var _a;
+        return (__assign(__assign({}, sel.range), { sheetId: (_a = (sel.sheetName ? resolveSheetId === null || resolveSheetId === void 0 ? void 0 : resolveSheetId(sel.sheetName) : undefined)) !== null && _a !== void 0 ? _a : hostSheetId }));
+    });
+};
+var chartData = function (sources) {
+    return ({ sources: sources });
+};
+/**
+ * Split a multi-column hierarchy range (Excel lays the treemap hierarchy out
+ * as columns, top level first, leaf last) into `parentLabels` (one entry per
+ * parent column) and `labels` (the leaf column).
+ */
+export var splitHierarchyRange = function (range) {
+    var parentLabels = [];
+    for (var c = range.startColumnIndex; c < range.endColumnIndex; c++) {
+        parentLabels.push(__assign(__assign({}, range), { startColumnIndex: c, endColumnIndex: c }));
+    }
+    return {
+        parentLabels: parentLabels,
+        labels: __assign(__assign({}, range), { startColumnIndex: range.endColumnIndex, endColumnIndex: range.endColumnIndex }),
+    };
+};
+var dimensionRef = function (data, dimTag, type) {
+    var _a, _b;
+    var dims = asArray(child(data, dimTag)).filter(function (dim) { return get(dim, "a$.type") === type; });
+    var dim = (_a = dims[0]) !== null && _a !== void 0 ? _a : (dimTag === "numDim" ? asArray(child(data, dimTag))[0] : undefined);
+    var f = child(dim, "f");
+    return ((_b = textOf(Array.isArray(f) ? f[0] : f)) === null || _b === void 0 ? void 0 : _b.trim()) || undefined;
+};
+/** Parse a `cx:chartSpace` DOM into an `EmbeddedChart` spec (null when unsupported). */
+export function parseChartExSpec(chartSpaceDom, sheetId, resolveSheetId) {
+    var _a, _b, _c, _d, _e;
+    var chartSpace = (_a = child(chartSpaceDom, "chartSpace")) !== null && _a !== void 0 ? _a : chartSpaceDom;
+    var chart = child(chartSpace, "chart");
+    if (!chart)
+        return null;
+    var region = child(child(chart, "plotArea"), "plotAreaRegion");
+    var series = asArray(child(region, "series"))[0];
+    if (!series)
+        return null;
+    var layoutId = String((_b = get(series, "a$.layoutId")) !== null && _b !== void 0 ? _b : "");
+    // Excel nests `<cx:binning>` in `<cx:layoutPr>`; tolerate it directly on the series too.
+    var binning = (_c = child(child(series, "layoutPr"), "binning")) !== null && _c !== void 0 ? _c : child(series, "binning");
+    var chartType = layoutId === "clusteredColumn" && binning
+        ? "histogram"
+        : CHART_TYPE_BY_LAYOUT[layoutId];
+    if (!chartType)
+        return null;
+    var dataId = String((_d = get(child(series, "dataId"), "a$.val")) !== null && _d !== void 0 ? _d : "0");
+    var data = (_e = asArray(child(child(chartSpace, "chartData"), "data")).find(function (d) { return String(get(d, "a$.id")) === dataId; })) !== null && _e !== void 0 ? _e : asArray(child(child(chartSpace, "chartData"), "data"))[0];
+    if (!data)
+        return null;
+    var title = textOf(child(child(child(child(chart, "title"), "tx"), "txData"), "v"));
+    var catRef = dimensionRef(data, "strDim", "cat");
+    var catSources = sourcesFromRef(catRef, sheetId, resolveSheetId);
+    if (chartType === "treemap" || chartType === "sunburst") {
+        var sizeRef = dimensionRef(data, "numDim", "size");
+        var sizeSources = sourcesFromRef(sizeRef, sheetId, resolveSheetId);
+        if (!catSources.length || !sizeSources.length)
+            return null;
+        var hierarchy = splitHierarchyRange(catSources[0]);
+        return __assign(__assign({ chartType: chartType }, (title ? { title: title } : {})), { labels: [chartData([hierarchy.labels])], parentLabels: hierarchy.parentLabels.map(function (range) { return chartData([range]); }), sizeData: [chartData(sizeSources)] });
+    }
+    var valRef = dimensionRef(data, "numDim", "val");
+    var valSources = sourcesFromRef(valRef, sheetId, resolveSheetId);
+    if (!valSources.length)
+        return null;
+    var spec = __assign(__assign(__assign({ chartType: chartType }, (title ? { title: title } : {})), { series: [chartData(valSources)] }), (catSources.length ? { domains: [chartData(catSources)] } : {}));
+    if (chartType === "histogram") {
+        var binCount = Number(get(child(binning, "binCount"), "a$.val"));
+        if (Number.isFinite(binCount) && binCount > 0)
+            spec.binCount = binCount;
+    }
+    return spec;
+}
+/** Resolve + parse one chartex part referenced from a drawing anchor. */
+export function processChartEx(chartTarget, drawingPath, anchor, sheetId, zipParser, xmlParser, sheetDimensions, resolveSheetId) {
+    return __awaiter(this, void 0, void 0, function () {
+        var chartPath, drawingDir, content, _a, spec, position;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    chartPath = chartTarget;
+                    drawingDir = drawingPath.substring(0, drawingPath.lastIndexOf("/"));
+                    if (chartPath.startsWith("/")) {
+                        chartPath = chartPath.slice(1);
+                    }
+                    else if (chartPath.startsWith("../")) {
+                        chartPath = "xl/".concat(chartPath.replace("../", ""));
+                    }
+                    else if (!chartPath.startsWith("xl/")) {
+                        chartPath = "".concat(drawingDir, "/").concat(chartPath);
+                    }
+                    _b.label = 1;
+                case 1:
+                    _b.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, zipParser.getText(chartPath)];
+                case 2:
+                    content = _b.sent();
+                    return [3 /*break*/, 4];
+                case 3:
+                    _a = _b.sent();
+                    return [2 /*return*/, null];
+                case 4:
+                    if (!content)
+                        return [2 /*return*/, null];
+                    spec = parseChartExSpec(xmlParser.parse(content), sheetId, resolveSheetId);
+                    if (!spec)
+                        return [2 /*return*/, null];
+                    position = extractChartPosition(anchor, sheetId, sheetDimensions);
+                    if (!position)
+                        return [2 /*return*/, null];
+                    return [2 /*return*/, { chartId: uuid(), spec: spec, position: position }];
+            }
+        });
+    });
+}

package/dist/cjs/excel-parser/plugins/xlsx/form-controls.d.ts

@@ -0,0 +1,70 @@
+import type { EmbeddedObject } from "@rowsncolumns/spreadsheet";
+export declare const CTRL_PROP_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp";
+export declare const VML_DRAWING_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing";
+type CellAnchor = {
+    col: number;
+    colOff: number;
+    row: number;
+    rowOff: number;
+};
+/**
+ * `<controlPr><anchor><from>…</from><to>…</to></anchor>` → the engine's
+ * pixel overlay position (1-based anchor cell, EMU offsets → px, size from
+ * the cell span at the grid defaults — the same approximation the drawing
+ * importer uses for `twoCellAnchor`s).
+ */
+export declare const controlAnchorToOverlayPosition: (from: CellAnchor, to: CellAnchor | undefined) => {
+    anchorCell: {
+        rowIndex: number;
+        columnIndex: number;
+    };
+    offsetXPixels?: number;
+    offsetYPixels?: number;
+    widthPixels?: number;
+    heightPixels?: number;
+};
+/**
+ * Parse an `xl/ctrlProps/ctrlPropN.xml` part: `objectType`, every other
+ * `formControlPr` attribute verbatim, and the literal `itemLst` items.
+ */
+export declare const parseFormControlPr: (ctrlPropDom: any) => {
+    objectType: string;
+    properties: Record<string, string>;
+    listItems?: string[];
+} | undefined;
+/**
+ * Captions live only in the legacy VML part: `<v:shape id="_x0000_s1025">
+ * … <v:textbox><div>Check Box 1</div></v:textbox>`. Returns shapeId → text.
+ * VML is scanned textually — Excel's VML is not reliably well-formed XML.
+ */
+export declare const parseVmlControlCaptions: (vml: string | undefined) => Map<number, string>;
+export type RawWorksheetControl = {
+    shapeId?: number;
+    name?: string;
+    relId?: string;
+    controlProperties: Record<string, string>;
+    moveWithCells?: boolean;
+    sizeWithCells?: boolean;
+    from?: CellAnchor;
+    to?: CellAnchor;
+};
+/**
+ * `<controls>` from a worksheet DOM, whether wrapped in
+ * `<mc:AlternateContent><mc:Choice Requires="x14">` (Excel) or bare.
+ */
+export declare const readWorksheetControls: (sheetDom: any) => RawWorksheetControl[];
+/**
+ * Assemble the sheet's form controls. `loadCtrlProp` resolves a control's
+ * `r:id` to its parsed `ctrlProp` DOM (undefined when the part is missing —
+ * the control is then skipped, Excel would repair it the same way).
+ */
+export declare const buildFormControlEmbeds: ({ controls, sheetId, ctrlProps, captions, }: {
+    controls: RawWorksheetControl[];
+    sheetId: number;
+    ctrlProps: Map<string, ReturnType<typeof parseFormControlPr>>;
+    captions: Map<number, string>;
+}) => EmbeddedObject[];
+/** The `r:id` of a worksheet's `<legacyDrawing>` (VML part), if any. */
+export declare const readLegacyDrawingRelId: (sheetDom: any) => string | undefined;
+export {};
+//# sourceMappingURL=form-controls.d.ts.map

package/dist/cjs/excel-parser/plugins/xlsx/form-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-controls.d.ts","sourceRoot":"","sources":["../../../../../excel-parser/plugins/xlsx/form-controls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,cAAc,EACf,MAAM,2BAA2B,CAAC;AAgBnC,eAAO,MAAM,kBAAkB,iFACiD,CAAC;AACjF,eAAO,MAAM,oBAAoB,mFACiD,CAAC;AA6CnF,KAAK,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAe/E;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GACzC,MAAM,UAAU,EAChB,IAAI,UAAU,GAAG,SAAS;gBAKZ;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;oBACrC,MAAM;oBACN,MAAM;kBACR,MAAM;mBACL,MAAM;CAiBxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,aAAa,GAAG,KACf;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,GAAG,SAkBH,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,KAAK,MAAM,GAAG,SAAS,KACtB,GAAG,CAAC,MAAM,EAAE,MAAM,CAwBpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,GAAG,KAAG,mBAAmB,EA+BxE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,6CAKpC;IACD,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC;IAC9D,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B,KAAG,cAAc,EA+BjB,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,GAAI,UAAU,GAAG,KAAG,MAAM,GAAG,SAK/D,CAAC"}

package/dist/cjs/excel-parser/plugins/xlsx/form-controls.js

@@ -0,0 +1,295 @@
+import { __assign, __read, __rest, __spreadArray, __values } from "tslib";
+/**
+ * Excel form controls (`<controls>` in the worksheet + `xl/ctrlProps/*` +
+ * the legacy VML shape). Parsed into `EmbeddedObject`s with an
+ * {@link EmbedFormControlSpec} so the exporter can write the same three
+ * parts back (`exporter/xlsx/form-controls-builder.ts`). The grid does not
+ * run the control; the spec is a faithful, opaque carrier of what Excel
+ * stored.
+ */
+var EMU_PER_PIXEL = 9525;
+/** Grid defaults used to size a control from its cell-span anchor. */
+var DEFAULT_COLUMN_WIDTH_PX = 100;
+var DEFAULT_ROW_HEIGHT_PX = 20;
+export var CTRL_PROP_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp";
+export var VML_DRAWING_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing";
+var asArray = function (value) {
+    return value == null ? [] : Array.isArray(value) ? value : [value];
+};
+/** Read a child by local name, tolerating any namespace prefix. */
+var childByLocalName = function (node, localName) {
+    var e_1, _a;
+    if (!node || typeof node !== "object")
+        return undefined;
+    if (node[localName] !== undefined)
+        return node[localName];
+    try {
+        for (var _b = __values(Object.keys(node)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var key = _c.value;
+            var colon = key.indexOf(":");
+            if (colon >= 0 && key.slice(colon + 1) === localName) {
+                return node[key];
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return undefined;
+};
+/** Text of a leaf element (`t$` when it carries attributes, else the value). */
+var textOf = function (node) {
+    if (node == null)
+        return undefined;
+    if (typeof node === "object") {
+        var inner = node.t$;
+        return inner == null ? undefined : String(inner);
+    }
+    return String(node);
+};
+var numberOf = function (node) {
+    var text = textOf(node);
+    var value = text == null ? Number.NaN : Number(text);
+    return Number.isFinite(value) ? value : 0;
+};
+var attrs = function (node) {
+    var e_2, _a;
+    var raw = node === null || node === void 0 ? void 0 : node.a$;
+    var out = {};
+    if (!raw || typeof raw !== "object")
+        return out;
+    try {
+        for (var _b = __values(Object.entries(raw)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var _d = __read(_c.value, 2), key = _d[0], value = _d[1];
+            if (value == null)
+                continue;
+            out[key] = String(value);
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return out;
+};
+var readCellAnchor = function (node) {
+    if (!node)
+        return undefined;
+    var col = childByLocalName(node, "col");
+    var row = childByLocalName(node, "row");
+    if (col === undefined || row === undefined)
+        return undefined;
+    return {
+        col: numberOf(col),
+        colOff: numberOf(childByLocalName(node, "colOff")),
+        row: numberOf(row),
+        rowOff: numberOf(childByLocalName(node, "rowOff")),
+    };
+};
+/**
+ * `<controlPr><anchor><from>…</from><to>…</to></anchor>` → the engine's
+ * pixel overlay position (1-based anchor cell, EMU offsets → px, size from
+ * the cell span at the grid defaults — the same approximation the drawing
+ * importer uses for `twoCellAnchor`s).
+ */
+export var controlAnchorToOverlayPosition = function (from, to) {
+    var offsetXPixels = Math.round(from.colOff / EMU_PER_PIXEL);
+    var offsetYPixels = Math.round(from.rowOff / EMU_PER_PIXEL);
+    var overlay = {
+        anchorCell: { rowIndex: from.row + 1, columnIndex: from.col + 1 },
+    };
+    if (offsetXPixels)
+        overlay.offsetXPixels = offsetXPixels;
+    if (offsetYPixels)
+        overlay.offsetYPixels = offsetYPixels;
+    if (to) {
+        var width = (to.col - from.col) * DEFAULT_COLUMN_WIDTH_PX +
+            (to.colOff - from.colOff) / EMU_PER_PIXEL;
+        var height = (to.row - from.row) * DEFAULT_ROW_HEIGHT_PX +
+            (to.rowOff - from.rowOff) / EMU_PER_PIXEL;
+        if (width > 0)
+            overlay.widthPixels = Math.round(width);
+        if (height > 0)
+            overlay.heightPixels = Math.round(height);
+    }
+    return overlay;
+};
+/**
+ * Parse an `xl/ctrlProps/ctrlPropN.xml` part: `objectType`, every other
+ * `formControlPr` attribute verbatim, and the literal `itemLst` items.
+ */
+export var parseFormControlPr = function (ctrlPropDom) {
+    var e_3, _a;
+    var root = childByLocalName(ctrlPropDom, "formControlPr");
+    if (!root)
+        return undefined;
+    var _b = attrs(root), objectType = _b.objectType, properties = __rest(_b, ["objectType"]);
+    if (!objectType)
+        return undefined;
+    try {
+        // Namespace declarations ride along as attributes in fast-xml-parser.
+        for (var _c = __values(Object.keys(properties)), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var key = _d.value;
+            if (key === "xmlns" || key.startsWith("xmlns:"))
+                delete properties[key];
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    var itemLst = childByLocalName(root, "itemLst");
+    var listItems = asArray(childByLocalName(itemLst, "item"))
+        .map(function (item) { return attrs(item).val; })
+        .filter(function (val) { return typeof val === "string"; });
+    return __assign({ objectType: objectType, properties: properties }, (listItems.length ? { listItems: listItems } : {}));
+};
+/**
+ * Captions live only in the legacy VML part: `<v:shape id="_x0000_s1025">
+ * … <v:textbox><div>Check Box 1</div></v:textbox>`. Returns shapeId → text.
+ * VML is scanned textually — Excel's VML is not reliably well-formed XML.
+ */
+export var parseVmlControlCaptions = function (vml) {
+    var captions = new Map();
+    if (!vml)
+        return captions;
+    var shapeRe = /<v:shape\b([^>]*)>([\s\S]*?)<\/v:shape>/g;
+    var match;
+    while ((match = shapeRe.exec(vml))) {
+        var idMatch = /\bid="_x0000_s(\d+)"/.exec(match[1]);
+        if (!idMatch)
+            continue;
+        var body = match[2];
+        if (!/<x:ClientData\b/.test(body))
+            continue;
+        var textbox = /<v:textbox\b[^>]*>([\s\S]*?)<\/v:textbox>/.exec(body);
+        if (!textbox)
+            continue;
+        var text = textbox[1]
+            .replace(/<br\s*\/?>/gi, "\n")
+            .replace(/<[^>]+>/g, "")
+            .replace(/&amp;/g, "&")
+            .replace(/&lt;/g, "<")
+            .replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"')
+            .replace(/&#(\d+);/g, function (_, code) { return String.fromCodePoint(Number(code)); })
+            .trim();
+        if (text)
+            captions.set(Number(idMatch[1]), text);
+    }
+    return captions;
+};
+/**
+ * `<controls>` from a worksheet DOM, whether wrapped in
+ * `<mc:AlternateContent><mc:Choice Requires="x14">` (Excel) or bare.
+ */
+export var readWorksheetControls = function (sheetDom) {
+    var e_4, _a, e_5, _b;
+    var _c;
+    var worksheet = (_c = childByLocalName(sheetDom, "worksheet")) !== null && _c !== void 0 ? _c : sheetDom;
+    var controls = childByLocalName(worksheet, "controls");
+    if (!controls)
+        return [];
+    var controlNodes = __spreadArray([], __read(asArray(childByLocalName(controls, "control"))), false);
+    try {
+        for (var _d = __values(asArray(childByLocalName(controls, "AlternateContent"))), _e = _d.next(); !_e.done; _e = _d.next()) {
+            var alternate = _e.value;
+            try {
+                for (var _f = (e_5 = void 0, __values(asArray(childByLocalName(alternate, "Choice")))), _g = _f.next(); !_g.done; _g = _f.next()) {
+                    var choice = _g.value;
+                    controlNodes.push.apply(controlNodes, __spreadArray([], __read(asArray(childByLocalName(choice, "control"))), false));
+                }
+            }
+            catch (e_5_1) { e_5 = { error: e_5_1 }; }
+            finally {
+                try {
+                    if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+                }
+                finally { if (e_5) throw e_5.error; }
+            }
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+    return controlNodes.map(function (node) {
+        var _a, _b;
+        var a = attrs(node);
+        var controlPr = childByLocalName(node, "controlPr");
+        var anchor = childByLocalName(controlPr, "anchor");
+        var anchorAttrs = attrs(anchor);
+        var shapeId = Number(a.shapeId);
+        return __assign(__assign(__assign(__assign(__assign(__assign(__assign({}, (Number.isFinite(shapeId) && a.shapeId ? { shapeId: shapeId } : {})), (a.name ? { name: a.name } : {})), (((_a = a["r:id"]) !== null && _a !== void 0 ? _a : a.id) ? { relId: (_b = a["r:id"]) !== null && _b !== void 0 ? _b : a.id } : {})), { controlProperties: attrs(controlPr) }), (anchorAttrs.moveWithCells !== undefined
+            ? { moveWithCells: anchorAttrs.moveWithCells === "1" || anchorAttrs.moveWithCells === "true" }
+            : {})), (anchorAttrs.sizeWithCells !== undefined
+            ? { sizeWithCells: anchorAttrs.sizeWithCells === "1" || anchorAttrs.sizeWithCells === "true" }
+            : {})), { from: readCellAnchor(childByLocalName(anchor, "from")), to: readCellAnchor(childByLocalName(anchor, "to")) });
+    });
+};
+/**
+ * Assemble the sheet's form controls. `loadCtrlProp` resolves a control's
+ * `r:id` to its parsed `ctrlProp` DOM (undefined when the part is missing —
+ * the control is then skipped, Excel would repair it the same way).
+ */
+export var buildFormControlEmbeds = function (_a) {
+    var controls = _a.controls, sheetId = _a.sheetId, ctrlProps = _a.ctrlProps, captions = _a.captions;
+    var embeds = [];
+    controls.forEach(function (control, index) {
+        var _a;
+        var parsed = control.relId ? ctrlProps.get(control.relId) : undefined;
+        if (!parsed || !control.from)
+            return;
+        var spec = {
+            type: "formControl",
+            objectType: parsed.objectType,
+            properties: parsed.properties,
+        };
+        if (control.name)
+            spec.name = control.name;
+        if (control.shapeId !== undefined)
+            spec.shapeId = control.shapeId;
+        var caption = control.shapeId !== undefined ? captions.get(control.shapeId) : undefined;
+        if (caption)
+            spec.text = caption;
+        if (parsed.listItems)
+            spec.listItems = parsed.listItems;
+        if (Object.keys(control.controlProperties).length) {
+            spec.controlProperties = control.controlProperties;
+        }
+        if (control.moveWithCells !== undefined)
+            spec.moveWithCells = control.moveWithCells;
+        if (control.sizeWithCells !== undefined)
+            spec.sizeWithCells = control.sizeWithCells;
+        embeds.push({
+            embedId: "control-".concat(sheetId, "-").concat((_a = control.shapeId) !== null && _a !== void 0 ? _a : index + 1),
+            spec: spec,
+            position: {
+                sheetId: sheetId,
+                overlayPosition: controlAnchorToOverlayPosition(control.from, control.to),
+            },
+        });
+    });
+    return embeds;
+};
+/** The `r:id` of a worksheet's `<legacyDrawing>` (VML part), if any. */
+export var readLegacyDrawingRelId = function (sheetDom) {
+    var _a, _b;
+    var worksheet = (_a = childByLocalName(sheetDom, "worksheet")) !== null && _a !== void 0 ? _a : sheetDom;
+    var legacy = childByLocalName(worksheet, "legacyDrawing");
+    var a = attrs(legacy);
+    return (_b = a["r:id"]) !== null && _b !== void 0 ? _b : a.id;
+};

package/dist/cjs/excel-parser/plugins/xlsx/index.d.ts

@@ -1,5 +1,5 @@
 import type { CellFormat, ConditionalFormatRule, DataValidationRuleRecord, EmbeddedChart, EmbeddedObject, NamedRange, ProtectedRange, Sheet, Slicer, SpreadsheetTheme, TableView } from "@rowsncolumns/spreadsheet";
-import type { CommentThread, TextFormat, TextFormatRun } from "@rowsncolumns/common-types";
+import type { NamedCellStyle, CommentThread, TextFormat, TextFormatRun } from "@rowsncolumns/common-types";
 import { XMLParser } from "fast-xml-parser";
 import type { IWorkbookPlugin } from "../../interface";
 import type { ExternalLink, ProcessSheetDataForSheetOptions, ProcessSheetDataResult, SheetCatalogEntry, WorkbookProperties } from "../../types";
@@ -252,6 +252,8 @@ export declare class XlsxPlugin extends BaseWorkbookPlugin implements IWorkbookP
     getSheetData(rid: string): Promise<any>;
     getStyles(): any;
     getTheme(): SpreadsheetTheme;
+    /** `<cellStyles>` resolved to cell formats (toolbar "Workbook styles" gallery). */
+    getNamedCellStyles(): NamedCellStyle[];
     /**
      * The workbook default font — styles.xml fonts[0], the font every cell
      * without an explicit font inherits. Exporters pass this through so the
@@ -294,6 +296,12 @@ export declare class XlsxPlugin extends BaseWorkbookPlugin implements IWorkbookP
     releaseSheetCaches(sheetId: number): void;
     private processOneSheet;
     getDrawings(): Promise<EmbeddedObjectWithPosition[]>;
+    /**
+     * 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.
+     */
+    _getFormControls(rid: string, sheetId: number, sheetData: any): Promise<EmbeddedObject[]>;
     getCharts(): Promise<EmbeddedChart[]>;
     /**
      * Phase D1 — extract every pivot table across every worksheet.