@rowsncolumns/toolkit 24.4.2 → 24.4.4

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

@@ -1 +1 @@
-{"version":3,"file":"drawing.d.ts","sourceRoot":"","sources":["../../../../../excel-parser/plugins/xlsx/drawing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EAEd,cAAc,EAWf,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAoDrE,MAAM,MAAM,0BAA0B,GAAG,cAAc,GAAG;IACxD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,GAAG,EACZ,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,kBAAkB,EAC7B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,0BAA0B,EAAE,CAAC,CA6dvC;AA6OD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CASlD;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,cAAc,CA8CzD;AA8MD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAqBT"}
+{"version":3,"file":"drawing.d.ts","sourceRoot":"","sources":["../../../../../excel-parser/plugins/xlsx/drawing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EAEd,cAAc,EACd,cAAc,EAYf,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAoDrE,MAAM,MAAM,0BAA0B,GAAG,cAAc,GAAG;IACxD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,4EAA4E;AAC5E,QAAA,MAAM,sBAAsB;;;;CAIlB,CAAC;AAEX,KAAK,iBAAiB,GAAG,MAAM,OAAO,sBAAsB,CAAC;AAK7D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,GAAG,EACZ,UAAU,EAAE,MAAM,GACjB,KAAK,CAAC;IACP,IAAI,EAAE,CAAC,OAAO,sBAAsB,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACzD,IAAI,EAAE,GAAG,CAAC;CACX,CAAC,CAkCD;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,GAAG,EACZ,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,kBAAkB,EAC7B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,0BAA0B,EAAE,CAAC,CA8dvC;AASD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,GAAG,GACX,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,GAAG,cAAc,CAAC,CAuC3E;AA6OD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CASlD;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,cAAc,CA8CzD;AA8MD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAqBT"}

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

@@ -42,6 +42,95 @@ var CELL_IMAGE_OFFSET_THRESHOLD_PX = 1;
 function emuToPixels(emuValue) {
     return Math.round(emuValue / EMU_PER_PIXEL);
 }
+/** `processAnchors` anchor-type tags, keyed by the drawing element name. */
+var ANCHOR_KIND_BY_ELEMENT = {
+    oneCellAnchor: "oneCellAnchor",
+    twoCellAnchor: "twoCellAnchors",
+    absoluteAnchor: "absoluteAnchors",
+};
+var ANCHOR_ELEMENT_REGEX = /<(?:[A-Za-z_][\w.-]*:)?(oneCellAnchor|twoCellAnchor|absoluteAnchor)(?=[\s/>])/g;
+/**
+ * The `<xdr:wsDr>` anchors in document order — Excel's z-order (first is
+ * the back-most object). The unordered parse keeps document order within one
+ * element name but groups the three anchor kinds apart, so the kind sequence
+ * is read off the raw part and the parsed nodes are dealt out in that order.
+ * Anchors the scan does not account for (namespace quirks) trail in their
+ * parsed order, so nothing is ever dropped.
+ */
+export function anchorsInDocumentOrder(drawing, drawingXml) {
+    var e_1, _a, e_2, _b, e_3, _c, e_4, _d;
+    var nodesByElement = {
+        oneCellAnchor: [],
+        twoCellAnchor: [],
+        absoluteAnchor: [],
+    };
+    try {
+        for (var _e = __values(Object.keys(nodesByElement)), _f = _e.next(); !_f.done; _f = _e.next()) {
+            var element = _f.value;
+            var parsed = get(drawing, "xdr:wsDr.xdr:".concat(element)) || get(drawing, "wsDr.".concat(element));
+            if (!parsed)
+                continue;
+            nodesByElement[element] = Array.isArray(parsed) ? parsed : [parsed];
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_f && !_f.done && (_a = _e.return)) _a.call(_e);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    var cursor = {
+        oneCellAnchor: 0,
+        twoCellAnchor: 0,
+        absoluteAnchor: 0,
+    };
+    var ordered = [];
+    try {
+        for (var _g = __values(drawingXml.matchAll(ANCHOR_ELEMENT_REGEX)), _h = _g.next(); !_h.done; _h = _g.next()) {
+            var match = _h.value;
+            var element = match[1];
+            var node = nodesByElement[element][cursor[element]];
+            if (node === undefined)
+                continue;
+            cursor[element] += 1;
+            ordered.push({ kind: ANCHOR_KIND_BY_ELEMENT[element], node: node });
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_h && !_h.done && (_b = _g.return)) _b.call(_g);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    try {
+        for (var _j = __values(Object.keys(nodesByElement)), _k = _j.next(); !_k.done; _k = _j.next()) {
+            var element = _k.value;
+            try {
+                for (var _l = (e_4 = void 0, __values(nodesByElement[element].slice(cursor[element]))), _m = _l.next(); !_m.done; _m = _l.next()) {
+                    var node = _m.value;
+                    ordered.push({ kind: ANCHOR_KIND_BY_ELEMENT[element], node: node });
+                }
+            }
+            catch (e_4_1) { e_4 = { error: e_4_1 }; }
+            finally {
+                try {
+                    if (_m && !_m.done && (_d = _l.return)) _d.call(_l);
+                }
+                finally { if (e_4) throw e_4.error; }
+            }
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_k && !_k.done && (_c = _j.return)) _c.call(_j);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    return ordered;
+}
 /**
  * Process different types of image anchors
  * @param anchors The anchor elements from the drawing
@@ -54,8 +143,8 @@ function emuToPixels(emuValue) {
  */
 export function processAnchors(anchors, anchorType, drawingPath, sheetId, zipParser, xmlParser) {
     return __awaiter(this, void 0, void 0, function () {
-        var images, anchorArray, _loop_1, anchorArray_1, anchorArray_1_1, anchor, e_1_1;
-        var e_1, _a;
+        var images, anchorArray, _loop_1, anchorArray_1, anchorArray_1_1, anchor, e_5_1;
+        var e_5, _a;
         var _b;
         return __generator(this, function (_c) {
             switch (_c.label) {
@@ -368,12 +457,7 @@ export function processAnchors(anchors, anchorType, drawingPath, sheetId, zipPar
                                     images.push({
                                         isInsideCell: isInsideCell,
                                         embedId: uuid(),
-                                        spec: {
-                                            id: imageId,
-                                            imageUrl: createDataUrl(imageData, imageType),
-                                            type: "image",
-                                            description: imageName,
-                                        },
+                                        spec: __assign({ id: imageId, imageUrl: createDataUrl(imageData, imageType), type: "image", description: imageName }, parsePictureAdjustments(picture)),
                                         position: position,
                                         draggable: true,
                                         lockAspectRatio: true,
@@ -399,20 +483,71 @@ export function processAnchors(anchors, anchorType, drawingPath, sheetId, zipPar
                     return [3 /*break*/, 2];
                 case 5: return [3 /*break*/, 8];
                 case 6:
-                    e_1_1 = _c.sent();
-                    e_1 = { error: e_1_1 };
+                    e_5_1 = _c.sent();
+                    e_5 = { error: e_5_1 };
                     return [3 /*break*/, 8];
                 case 7:
                     try {
                         if (anchorArray_1_1 && !anchorArray_1_1.done && (_a = anchorArray_1.return)) _a.call(anchorArray_1);
                     }
-                    finally { if (e_1) throw e_1.error; }
+                    finally { if (e_5) throw e_5.error; }
                     return [7 /*endfinally*/];
                 case 8: return [2 /*return*/, images];
             }
         });
     });
 }
+/** DrawingML per-mille-percent (100000 = 100%) → fraction, or undefined. */
+var pctToFraction = function (value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    var n = Number(value);
+    return Number.isFinite(n) ? n / 100000 : undefined;
+};
+/**
+ * Picture-format adjustments off an `<xdr:pic>`: `<a:blipFill><a:srcRect>`
+ * (crop), `<a:blip><a:lum bright contrast>` (brightness / contrast) and
+ * `<a:blip><a:alphaModFix amt>` (opacity → `transparency`). Only present
+ * values are returned so an untouched picture stays a bare image spec.
+ */
+export function parsePictureAdjustments(picture) {
+    var _a, _b, _c, _d, _e, _f;
+    var blipFill = (_b = (_a = get(picture, "xdr:blipFill")) !== null && _a !== void 0 ? _a : get(picture, "blipFill")) !== null && _b !== void 0 ? _b : undefined;
+    var blip = (_c = get(blipFill, "a:blip")) !== null && _c !== void 0 ? _c : get(blipFill, "blip");
+    var out = {};
+    var srcRect = (_d = get(blipFill, "a:srcRect.a$")) !== null && _d !== void 0 ? _d : get(blipFill, "srcRect.a$");
+    if (srcRect) {
+        var crop = {};
+        var left = pctToFraction(srcRect.l);
+        var top_1 = pctToFraction(srcRect.t);
+        var right = pctToFraction(srcRect.r);
+        var bottom = pctToFraction(srcRect.b);
+        if (left)
+            crop.left = left;
+        if (top_1)
+            crop.top = top_1;
+        if (right)
+            crop.right = right;
+        if (bottom)
+            crop.bottom = bottom;
+        if (Object.keys(crop).length)
+            out.crop = crop;
+    }
+    var lum = (_e = get(blip, "a:lum.a$")) !== null && _e !== void 0 ? _e : get(blip, "lum.a$");
+    if (lum) {
+        var brightness = pctToFraction(lum.bright);
+        var contrast = pctToFraction(lum.contrast);
+        if (brightness)
+            out.brightness = brightness;
+        if (contrast)
+            out.contrast = contrast;
+    }
+    var alpha = pctToFraction((_f = get(blip, "a:alphaModFix.a$.amt")) !== null && _f !== void 0 ? _f : get(blip, "alphaModFix.a$.amt"));
+    if (alpha !== undefined && alpha < 1) {
+        out.transparency = Math.round((1 - alpha) * 100000) / 100000;
+    }
+    return out;
+}
 /**
  * Parse color from DrawingML color element
  * Supports both RGB (srgbClr) and theme colors (schemeClr)
@@ -521,7 +656,7 @@ function parseColorOpacity(colorElement) {
 }
 /** `<a:prstGeom>` → geometry preset + `<a:avLst>` adjust guides. */
 function parseShapeGeometry(spPr) {
-    var e_2, _a;
+    var e_6, _a;
     var _b;
     var prstGeom = get(spPr, "a:prstGeom");
     var prst = get(prstGeom, "a$.prst");
@@ -539,12 +674,12 @@ function parseShapeGeometry(spPr) {
             }
         }
     }
-    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    catch (e_6_1) { e_6 = { error: e_6_1 }; }
     finally {
         try {
             if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
         }
-        finally { if (e_2) throw e_2.error; }
+        finally { if (e_6) throw e_6.error; }
     }
     return { preset: (_b = PRESET_RENAMES[prst]) !== null && _b !== void 0 ? _b : prst, adjustments: adjustments };
 }
@@ -731,7 +866,7 @@ export function parseShapeSpec(shape) {
  * @returns EmbedTextBoxSpec object
  */
 function parseTextBoxContent(txBody, shape) {
-    var e_3, _a, e_4, _b;
+    var e_7, _a, e_8, _b;
     var richText = [];
     var plainText = "";
     // Get paragraphs
@@ -766,7 +901,7 @@ function parseTextBoxContent(txBody, shape) {
             // Add indentation and bullet to the first run of the paragraph
             var isFirstRun = true;
             try {
-                for (var runArray_1 = (e_4 = void 0, __values(runArray)), runArray_1_1 = runArray_1.next(); !runArray_1_1.done; runArray_1_1 = runArray_1.next()) {
+                for (var runArray_1 = (e_8 = void 0, __values(runArray)), runArray_1_1 = runArray_1.next(); !runArray_1_1.done; runArray_1_1 = runArray_1.next()) {
                     var run = runArray_1_1.value;
                     var text = get(run, "a:t.t$") || get(run, "a:t") || "";
                     // Handle tab characters
@@ -832,12 +967,12 @@ function parseTextBoxContent(txBody, shape) {
                     });
                 }
             }
-            catch (e_4_1) { e_4 = { error: e_4_1 }; }
+            catch (e_8_1) { e_8 = { error: e_8_1 }; }
             finally {
                 try {
                     if (runArray_1_1 && !runArray_1_1.done && (_b = runArray_1.return)) _b.call(runArray_1);
                 }
-                finally { if (e_4) throw e_4.error; }
+                finally { if (e_8) throw e_8.error; }
             }
             // Add paragraph break (newline) between paragraphs
             if (paragraphArray.indexOf(paragraph) < paragraphArray.length - 1) {
@@ -846,12 +981,12 @@ function parseTextBoxContent(txBody, shape) {
             }
         }
     }
-    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    catch (e_7_1) { e_7 = { error: e_7_1 }; }
     finally {
         try {
             if (paragraphArray_1_1 && !paragraphArray_1_1.done && (_a = paragraphArray_1.return)) _a.call(paragraphArray_1);
         }
-        finally { if (e_3) throw e_3.error; }
+        finally { if (e_7) throw e_7.error; }
     }
     // Get shape properties for background, borders, etc.
     var spPr = get(shape, "xdr:spPr") || get(shape, "spPr");

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;
+};