@rowsncolumns/toolkit 24.4.1

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

@@ -0,0 +1,905 @@
+import { uuid } from "@rowsncolumns/utils";
+import { get } from "lodash-es";
+/**
+ * Create a data URL from binary data and MIME type
+ * @param data Binary data of the image
+ * @param mimeType MIME type of the image
+ * @returns Data URL string
+ */
+function createDataUrl(data, mimeType) {
+    // Convert ArrayBuffer to Base64 string
+    const base64 = arrayBufferToBase64(data);
+    return `data:${mimeType};base64,${base64}`;
+}
+/**
+ * Convert an ArrayBuffer to a Base64 string
+ * @param buffer ArrayBuffer to convert
+ * @returns Base64 string
+ */
+function arrayBufferToBase64(buffer) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    // Use Buffer in Node.js, btoa in browser
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("base64");
+    }
+    let binary = "";
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+// Conversion constant: 1 pixel is approximately 9525 EMUs (at 96 DPI)
+const EMU_PER_PIXEL = 9525;
+const DEFAULT_CELL_IMAGE_MAX_SIZE_PX = 60;
+const CELL_IMAGE_OFFSET_THRESHOLD_PX = 1;
+/**
+ * Convert EMUs to pixels
+ * @param emuValue Value in English Metric Units
+ * @returns Value in pixels (at 96 DPI)
+ */
+function emuToPixels(emuValue) {
+    return Math.round(emuValue / EMU_PER_PIXEL);
+}
+/**
+ * Process different types of image anchors
+ * @param anchors The anchor elements from the drawing
+ * @param anchorType The type of anchor
+ * @param drawingPath The path to the drawing file
+ * @param sheetName The name of the worksheet
+ * @param zipParser The zip parser instance
+ * @param xmlParser The XML parser instance
+ * @returns An array of image objects with their properties and binary data
+ */
+export async function processAnchors(anchors, anchorType, drawingPath, sheetId, zipParser, xmlParser) {
+    const images = [];
+    if (!anchors)
+        return images;
+    // Normalize to array
+    const anchorArray = Array.isArray(anchors) ? anchors : [anchors];
+    for (const anchor of anchorArray) {
+        let isInsideCell = false;
+        // Get position information based on anchor type
+        let position = {
+            sheetId,
+            // sheet: sheetName,
+            // anchorType: anchorType, // Store the anchor type to differentiate positioning
+        };
+        if (anchorType === "twoCellAnchors") {
+            // Two cell anchor defines a rectangle with from and to cells
+            // Handle different namespace patterns
+            // Adjust row and column indices to start from 1 (Excel-like) instead of 0 (zero-based)
+            // Store both the original (0-based) and adjusted (1-based) indices
+            const fromColBase0 = parseInt(get(anchor, "xdr:from.xdr:col.t$") ||
+                get(anchor, "from.col.t$") ||
+                get(anchor, "xdr:from.xdr:col") ||
+                get(anchor, "from.col") ||
+                "0");
+            const fromRowBase0 = parseInt(get(anchor, "xdr:from.xdr:row.t$") ||
+                get(anchor, "from.row.t$") ||
+                get(anchor, "xdr:from.xdr:row") ||
+                get(anchor, "from.row") ||
+                "0");
+            const toColBase0 = parseInt(get(anchor, "xdr:to.xdr:col.t$") ||
+                get(anchor, "to.col.t$") ||
+                get(anchor, "xdr:to.xdr:col") ||
+                get(anchor, "to.col") ||
+                "0");
+            const toRowBase0 = parseInt(get(anchor, "xdr:to.xdr:row.t$") ||
+                get(anchor, "to.row.t$") ||
+                get(anchor, "xdr:to.xdr:row") ||
+                get(anchor, "to.row") ||
+                "0");
+            // Convert to 1-based indices (Excel-like)
+            const fromCol = fromColBase0 + 1;
+            const fromRow = fromRowBase0 + 1;
+            const toCol = toColBase0 + 1;
+            const toRow = toRowBase0 + 1;
+            // Get offset information if available (convert to pixels)
+            const fromColOffEmu = parseInt(get(anchor, "xdr:from.xdr:colOff.t$") ||
+                get(anchor, "from.colOff.t$") ||
+                get(anchor, "xdr:from.xdr:colOff") ||
+                get(anchor, "from.colOff") ||
+                "0");
+            const fromRowOffEmu = parseInt(get(anchor, "xdr:from.xdr:rowOff.t$") ||
+                get(anchor, "from.rowOff.t$") ||
+                get(anchor, "xdr:from.xdr:rowOff") ||
+                get(anchor, "from.rowOff") ||
+                "0");
+            const toColOffEmu = parseInt(get(anchor, "xdr:to.xdr:colOff.t$") ||
+                get(anchor, "to.colOff.t$") ||
+                get(anchor, "xdr:to.xdr:colOff") ||
+                get(anchor, "to.colOff") ||
+                "0");
+            const toRowOffEmu = parseInt(get(anchor, "xdr:to.xdr:rowOff.t$") ||
+                get(anchor, "to.rowOff.t$") ||
+                get(anchor, "xdr:to.xdr:rowOff") ||
+                get(anchor, "to.rowOff") ||
+                "0");
+            // Convert EMUs to pixels
+            const fromColOff = emuToPixels(fromColOffEmu);
+            const fromRowOff = emuToPixels(fromRowOffEmu);
+            const toColOff = emuToPixels(toColOffEmu);
+            const toRowOff = emuToPixels(toRowOffEmu);
+            // Get extent (size) information (in EMUs) from the correct path
+            const cxEmu = parseInt(get(anchor, "xdr:pic.xdr:spPr.a:xfrm.a:ext.a$.cx") ||
+                get(anchor, "pic.spPr.xfrm.ext.a$.cx") ||
+                "0");
+            const cyEmu = parseInt(get(anchor, "xdr:pic.xdr:spPr.a:xfrm.a:ext.a$.cy") ||
+                get(anchor, "pic.spPr.xfrm.ext.a$.cy") ||
+                "0");
+            // Convert EMUs to pixels
+            const width = emuToPixels(cxEmu);
+            const height = emuToPixels(cyEmu);
+            // Check for editAs attribute which indicates if image is locked to cells
+            const editAs = get(anchor, "a$.editAs") || "";
+            isInsideCell = determineIfTwoCellInsideCell(editAs, fromColBase0, fromRowBase0, toColBase0, toRowBase0);
+            position = {
+                ...position,
+                overlayPosition: {
+                    anchorCell: {
+                        rowIndex: fromRow,
+                        columnIndex: fromCol,
+                    },
+                    heightPixels: height,
+                    widthPixels: width,
+                    offsetXPixels: fromColOff,
+                    offsetYPixels: fromRowOff,
+                },
+            };
+        }
+        else if (anchorType === "oneCellAnchor") {
+            // One cell anchor defines a point with just from cell and extents
+            // Handle different namespace patterns
+            // Adjust row and column indices to start from 1 (Excel-like) instead of 0 (zero-based)
+            const fromColBase0 = parseInt(get(anchor, "xdr:from.xdr:col.t$") ||
+                get(anchor, "from.col.t$") ||
+                get(anchor, "xdr:from.xdr:col") ||
+                get(anchor, "from.col") ||
+                "0");
+            const fromRowBase0 = parseInt(get(anchor, "xdr:from.xdr:row.t$") ||
+                get(anchor, "from.row.t$") ||
+                get(anchor, "xdr:from.xdr:row") ||
+                get(anchor, "from.row") ||
+                "0");
+            // Convert to 1-based indices (Excel-like)
+            const fromCol = fromColBase0 + 1;
+            const fromRow = fromRowBase0 + 1;
+            // Get offset information (in EMUs)
+            const fromColOffEmu = parseInt(get(anchor, "xdr:from.xdr:colOff.t$") ||
+                get(anchor, "from.colOff.t$") ||
+                get(anchor, "xdr:from.xdr:colOff") ||
+                get(anchor, "from.colOff") ||
+                "0");
+            const fromRowOffEmu = parseInt(get(anchor, "xdr:from.xdr:rowOff.t$") ||
+                get(anchor, "from.rowOff.t$") ||
+                get(anchor, "xdr:from.xdr:rowOff") ||
+                get(anchor, "from.rowOff") ||
+                "0");
+            // Convert EMUs to pixels
+            const fromColOff = emuToPixels(fromColOffEmu);
+            const fromRowOff = emuToPixels(fromRowOffEmu);
+            // Get extent (size) information (in EMUs)
+            const cxEmu = parseInt(get(anchor, "xdr:ext.a$.cx") || get(anchor, "ext.a$.cx") || "0");
+            const cyEmu = parseInt(get(anchor, "xdr:ext.a$.cy") || get(anchor, "ext.a$.cy") || "0");
+            // Convert EMUs to pixels
+            const width = emuToPixels(cxEmu);
+            const height = emuToPixels(cyEmu);
+            // Add info about locking with sheet which helps determine positioning
+            const fLocksWithSheet = get(anchor, "xdr:clientData.a$.fLocksWithSheet") ||
+                get(anchor, "clientData.a$.fLocksWithSheet") ||
+                "0";
+            isInsideCell = determineIfOneCellInsideCell(fromColOffEmu, fromRowOffEmu, fLocksWithSheet, cxEmu, cyEmu);
+            position = {
+                ...position,
+                overlayPosition: {
+                    anchorCell: {
+                        rowIndex: fromRow,
+                        columnIndex: fromCol,
+                    },
+                    heightPixels: height,
+                    widthPixels: width,
+                    offsetXPixels: fromColOff,
+                    offsetYPixels: fromRowOff,
+                },
+            };
+            // position = {
+            //   ...position,
+            //   fromCol,
+            //   fromRow,
+            //   fromColOff,
+            //   fromRowOff,
+            //   width,
+            //   height,
+            //   // Store original indices in case they're needed
+            //   _fromColBase0: fromColBase0,
+            //   _fromRowBase0: fromRowBase0,
+            //   // Store original EMU values for reference if needed
+            //   _fromColOffEmu: fromColOffEmu,
+            //   _fromRowOffEmu: fromRowOffEmu,
+            //   _widthEmu: cxEmu,
+            //   _heightEmu: cyEmu,
+            //   fLocksWithSheet: fLocksWithSheet === "1",
+            //   // For oneCellAnchor, determine based on offsets and locking
+            //   isInsideCell: determineIfOneCellInsideCell(
+            //     fromColOffEmu,
+            //     fromRowOffEmu,
+            //     fLocksWithSheet,
+            //     cxEmu,
+            //     cyEmu
+            //   ),
+            // };
+        }
+        else if (anchorType === "absoluteAnchors") {
+            // Absolute anchor doesn't have cell reference, only absolute position (in EMUs)
+            const posXEmu = parseInt(get(anchor, "xdr:pos.a$.x") || get(anchor, "pos.a$.x") || "0") || 0;
+            const posYEmu = parseInt(get(anchor, "xdr:pos.a$.y") || get(anchor, "pos.a$.y") || "0") || 0;
+            // Convert EMUs to pixels
+            const posX = emuToPixels(posXEmu);
+            const posY = emuToPixels(posYEmu);
+            // Get extent (size) information (in EMUs)
+            const cxEmu = parseInt(get(anchor, "xdr:ext.a$.cx") || get(anchor, "ext.a$.cx") || "0") || 0;
+            const cyEmu = parseInt(get(anchor, "xdr:ext.a$.cy") || get(anchor, "ext.a$.cy") || "0") || 0;
+            // Convert EMUs to pixels
+            const width = emuToPixels(cxEmu);
+            const height = emuToPixels(cyEmu);
+            position = {
+                ...position,
+                overlayPosition: {
+                    anchorCell: {
+                        rowIndex: 1,
+                        columnIndex: 1,
+                    },
+                    heightPixels: height,
+                    widthPixels: width,
+                    offsetXPixels: posX,
+                    offsetYPixels: posY,
+                },
+            };
+        }
+        // Find the picture element with different possible namespaces
+        const picture = get(anchor, "xdr:pic") || get(anchor, "pic");
+        // Find shape (textbox or drawing shape) element
+        const shape = get(anchor, "xdr:sp") || get(anchor, "sp");
+        // Drawing shape (Insert → Shapes): parsed into an `EmbedShapeSpec` so the
+        // geometry/fill/outline render. A shape is only routed here when it is
+        // visibly a *shape* — a non-rect preset geometry, an explicit fill, or an
+        // `<xdr:style>` theme-style block. Plain text boxes (`txBox="1"`, or a bare
+        // unstyled rect) keep the textbox path below, so they don't inherit the
+        // shape renderer's default accent styling.
+        if (shape && isDrawingShape(shape)) {
+            const shapeSpec = parseShapeSpec(shape);
+            const cxEmu = parseInt(get(shape, "xdr:spPr.a:xfrm.a:ext.a$.cx") ||
+                get(shape, "spPr.xfrm.ext.a$.cx") ||
+                "0");
+            const cyEmu = parseInt(get(shape, "xdr:spPr.a:xfrm.a:ext.a$.cy") ||
+                get(shape, "spPr.xfrm.ext.a$.cy") ||
+                "0");
+            if (cxEmu > 0 && cyEmu > 0 && position.overlayPosition) {
+                position.overlayPosition.widthPixels = emuToPixels(cxEmu);
+                position.overlayPosition.heightPixels = emuToPixels(cyEmu);
+            }
+            // Shape rotation lives on the embed (like images), in degrees.
+            const rotUnits = parseInt(get(shape, "xdr:spPr.a:xfrm.a$.rot") ||
+                get(shape, "spPr.xfrm.a$.rot") ||
+                "0");
+            images.push({
+                isInsideCell,
+                embedId: uuid(),
+                spec: shapeSpec,
+                position,
+                rotation: rotUnits ? rotUnits / 60000 : undefined,
+                draggable: true,
+            });
+            continue;
+        }
+        // Process textbox if shape has text body
+        if (shape) {
+            const txBody = get(shape, "xdr:txBody") || get(shape, "txBody");
+            if (txBody) {
+                // Extract textbox properties
+                const textBoxName = get(shape, "xdr:nvSpPr.xdr:cNvPr.a$.name") ||
+                    get(shape, "nvSpPr.cNvPr.a$.name") ||
+                    "TextBox";
+                const textBoxId = get(shape, "xdr:nvSpPr.xdr:cNvPr.a$.id") ||
+                    get(shape, "nvSpPr.cNvPr.a$.id") ||
+                    "";
+                // Extract explicit width/height from shape properties (similar to images)
+                const cxEmu = parseInt(get(shape, "xdr:spPr.a:xfrm.a:ext.a$.cx") ||
+                    get(shape, "spPr.xfrm.ext.a$.cx") ||
+                    "0");
+                const cyEmu = parseInt(get(shape, "xdr:spPr.a:xfrm.a:ext.a$.cy") ||
+                    get(shape, "spPr.xfrm.ext.a$.cy") ||
+                    "0");
+                // Convert EMUs to pixels and override position dimensions if available
+                if (cxEmu > 0 && cyEmu > 0) {
+                    const width = emuToPixels(cxEmu);
+                    const height = emuToPixels(cyEmu);
+                    if (position.overlayPosition) {
+                        position.overlayPosition.widthPixels = width;
+                        position.overlayPosition.heightPixels = height;
+                    }
+                }
+                // Parse text content and formatting
+                const textBoxSpec = parseTextBoxContent(txBody, shape);
+                images.push({
+                    isInsideCell,
+                    embedId: uuid(),
+                    spec: textBoxSpec,
+                    position,
+                    draggable: true,
+                });
+                continue;
+            }
+        }
+        if (!picture)
+            continue;
+        // Get the embedded picture relationship ID with different possible paths
+        const blipRId = get(picture, "xdr:blipFill.a:blip.a$.embed") ||
+            get(picture, "xdr:blipFill.a:blip.a$.r:embed") ||
+            get(picture, "blipFill.a:blip.a$.embed") ||
+            get(picture, "blipFill.a:blip.a$.r:embed") ||
+            get(picture, "blipFill.blip.a$.embed") ||
+            get(picture, "blipFill.blip.a$.r:embed");
+        if (!blipRId)
+            continue;
+        // Get the name of the image if available - handle different path patterns
+        const imageName = get(picture, "xdr:nvPicPr.xdr:cNvPr.a$.name") ||
+            get(picture, "nvPicPr.cNvPr.a$.name") ||
+            "Image";
+        // Get the image ID - handle different path patterns
+        const imageId = get(picture, "xdr:nvPicPr.xdr:cNvPr.a$.id") ||
+            get(picture, "nvPicPr.cNvPr.a$.id") ||
+            "";
+        // Get title if available
+        const imageTitle = get(picture, "xdr:nvPicPr.xdr:cNvPr.a$.title") ||
+            get(picture, "nvPicPr.cNvPr.a$.title") ||
+            "";
+        // 3. Get the image file from the drawing relationships
+        const drawingDir = drawingPath.substring(0, drawingPath.lastIndexOf("/"));
+        const drawingFilename = drawingPath.split("/").pop();
+        const drawingRelsPath = `${drawingDir}/_rels/${drawingFilename}.rels`;
+        const drawingRelsContent = await zipParser.getText(drawingRelsPath);
+        if (!drawingRelsContent)
+            continue;
+        // Parse drawing relationships
+        const drawingRels = xmlParser.parse(drawingRelsContent);
+        const imageRelations = get(drawingRels, "Relationships.Relationship");
+        if (!imageRelations)
+            continue;
+        // Find the specific image relationship
+        const imageRel = Array.isArray(imageRelations)
+            ? imageRelations.find((rel) => rel.a$.Id === blipRId)
+            : imageRelations.a$.Id === blipRId
+                ? imageRelations
+                : null;
+        if (!imageRel)
+            continue;
+        // Get the target path of the image
+        const imageTarget = imageRel.a$.Target;
+        let imagePath;
+        // Handle different path formats
+        if (imageTarget.startsWith("/")) {
+            // Absolute path from the root of the zip
+            imagePath = imageTarget.substring(1);
+        }
+        else if (imageTarget.startsWith("../")) {
+            // Relative path going up directories
+            // Since drawingDir is something like 'xl/drawings',
+            // and '../media/image1.png' means 'xl/media/image1.png'
+            const baseDir = drawingDir.split("/").slice(0, -1).join("/");
+            imagePath = `${baseDir}/${imageTarget.replace("../", "")}`;
+        }
+        else {
+            // Relative path in the same directory
+            imagePath = `${drawingDir}/${imageTarget}`;
+        }
+        // 4. Get the actual image data
+        const imageData = await zipParser.getBinary(imagePath);
+        if (!imageData)
+            continue;
+        // Determine image type from the path
+        const imageExt = imagePath.split(".").pop()?.toLowerCase() || "";
+        const imageType = `image/${imageExt === "jpg" ? "jpeg" : imageExt}`;
+        // Add the image to our collection
+        images.push({
+            isInsideCell,
+            embedId: uuid(),
+            spec: {
+                id: imageId,
+                imageUrl: createDataUrl(imageData, imageType),
+                type: "image",
+                description: imageName,
+            },
+            position,
+            draggable: true,
+            lockAspectRatio: true,
+        });
+    }
+    return images;
+}
+/**
+ * Parse color from DrawingML color element
+ * Supports both RGB (srgbClr) and theme colors (schemeClr)
+ */
+function parseDrawingColor(colorElement) {
+    if (!colorElement)
+        return undefined;
+    // RGB color
+    const srgbClr = get(colorElement, "a:srgbClr.a$.val");
+    if (srgbClr) {
+        return `#${srgbClr}`;
+    }
+    // Theme color - map to approximate RGB values
+    const schemeClr = get(colorElement, "a:schemeClr.a$.val");
+    if (schemeClr) {
+        // Basic theme color mapping (Office theme defaults)
+        const themeColorMap = {
+            accent1: "#4472C4",
+            accent2: "#ED7D31",
+            accent3: "#A5A5A5",
+            accent4: "#FFC000",
+            accent5: "#5B9BD5",
+            accent6: "#70AD47",
+            dk1: "#000000",
+            lt1: "#FFFFFF",
+            dk2: "#44546A",
+            lt2: "#E7E6E6",
+            hlink: "#0563C1",
+            folHlink: "#954F72",
+        };
+        return themeColorMap[schemeClr] || "#000000";
+    }
+    return undefined;
+}
+const toArray = (value) => Array.isArray(value) ? value : value ? [value] : [];
+/** DrawingML scheme-color names → the spreadsheet theme's ColorIndex slots. */
+const SCHEME_TO_THEME_INDEX = {
+    bg1: 0,
+    lt1: 0,
+    tx1: 1,
+    dk1: 1,
+    bg2: 2,
+    lt2: 2,
+    tx2: 3,
+    dk2: 3,
+    accent1: 4,
+    accent2: 5,
+    accent3: 6,
+    accent4: 7,
+    accent5: 8,
+    accent6: 9,
+    hlink: 10,
+};
+/** OOXML preset names → the renderer's preset union where they differ. */
+const PRESET_RENAMES = {
+    rtTriangle: "rightTriangle",
+    snip1Rect: "snipSingleCornerRect",
+};
+/**
+ * Parse a DrawingML color element into a `Color` — a live theme reference
+ * (`{ theme, tint }`) for `<a:schemeClr>` (so the shape follows document theme
+ * changes, unlike {@link parseDrawingColor}'s baked-in hex), or a hex string
+ * for `<a:srgbClr>`. Luminance/tint modifiers map onto the theme tint:
+ * `lumOff`/`tint` lighten (accent1 "lighter 40%" = lumMod 60000 + lumOff 40000
+ * → tint 0.4), `shade`/`lumMod`-only darken.
+ */
+function parseDrawingColorValue(colorElement) {
+    if (!colorElement)
+        return undefined;
+    const srgbClr = get(colorElement, "a:srgbClr.a$.val");
+    if (srgbClr)
+        return `#${srgbClr}`;
+    const schemeClr = get(colorElement, "a:schemeClr");
+    const schemeVal = get(schemeClr, "a$.val");
+    if (schemeVal) {
+        const theme = SCHEME_TO_THEME_INDEX[schemeVal];
+        if (theme === undefined) {
+            // Unmapped scheme name (e.g. folHlink): fall back to the baked hex.
+            return parseDrawingColor(colorElement);
+        }
+        const lumOff = parseInt(get(schemeClr, "a:lumOff.a$.val") || "0");
+        const tintVal = parseInt(get(schemeClr, "a:tint.a$.val") || "0");
+        const shade = parseInt(get(schemeClr, "a:shade.a$.val") || "0");
+        const lumMod = parseInt(get(schemeClr, "a:lumMod.a$.val") || "0");
+        let tint;
+        if (lumOff > 0)
+            tint = lumOff / 100000;
+        else if (tintVal > 0)
+            tint = tintVal / 100000;
+        else if (shade > 0)
+            tint = -(1 - shade / 100000);
+        else if (lumMod > 0 && lumMod < 100000)
+            tint = -(1 - lumMod / 100000);
+        return tint !== undefined ? { theme, tint } : { theme };
+    }
+    return undefined;
+}
+/** `<a:alpha val>` (1/100000) under a color element → 0–1 opacity, if reduced. */
+function parseColorOpacity(colorElement) {
+    const alpha = parseInt(get(colorElement, "a:srgbClr.a:alpha.a$.val") ||
+        get(colorElement, "a:schemeClr.a:alpha.a$.val") ||
+        "0");
+    return alpha > 0 && alpha < 100000 ? alpha / 100000 : undefined;
+}
+/** `<a:prstGeom>` → geometry preset + `<a:avLst>` adjust guides. */
+function parseShapeGeometry(spPr) {
+    const prstGeom = get(spPr, "a:prstGeom");
+    const prst = get(prstGeom, "a$.prst");
+    if (!prst)
+        return undefined;
+    let adjustments;
+    for (const gd of toArray(get(prstGeom, "a:avLst.a:gd"))) {
+        const name = get(gd, "a$.name");
+        const fmla = get(gd, "a$.fmla") || "";
+        const match = /^val\s+(-?\d+)$/.exec(fmla);
+        if (name && match) {
+            (adjustments ??= {})[name] = parseInt(match[1]);
+        }
+    }
+    return { preset: PRESET_RENAMES[prst] ?? prst, adjustments };
+}
+/** Empty elements (`<a:noFill/>`) parse to `""` — presence must not be truthiness. */
+const hasElement = (obj, path) => get(obj, path) !== undefined;
+/** Explicit `<a:noFill>`/`<a:solidFill>`/`<a:gradFill>` on `spPr` (style refs are separate). */
+function parseShapeFill(spPr) {
+    if (hasElement(spPr, "a:noFill"))
+        return { kind: "none" };
+    const solidFill = get(spPr, "a:solidFill");
+    if (solidFill) {
+        const color = parseDrawingColorValue(solidFill);
+        if (color) {
+            return { kind: "solid", color, opacity: parseColorOpacity(solidFill) };
+        }
+    }
+    const gradFill = get(spPr, "a:gradFill");
+    if (gradFill) {
+        const stops = toArray(get(gradFill, "a:gsLst.a:gs"))
+            .map((gs) => ({
+            position: parseInt(get(gs, "a$.pos") || "0") / 100000,
+            color: parseDrawingColorValue(gs) ?? "#FFFFFF",
+            opacity: parseColorOpacity(gs),
+        }))
+            .sort((a, b) => a.position - b.position);
+        if (stops.length) {
+            const ang = parseInt(get(gradFill, "a:lin.a$.ang") || "0");
+            return {
+                kind: "gradient",
+                stops,
+                angle: ang ? ang / 60000 : 90,
+                shading: get(gradFill, "a:path") ? "radial" : "linear",
+            };
+        }
+    }
+    return undefined;
+}
+const DASH_RENAMES = {
+    solid: "solid",
+    dot: "dot",
+    sysDot: "dot",
+    dash: "dash",
+    sysDash: "dash",
+    dashDot: "dashDot",
+    sysDashDot: "dashDot",
+    lgDash: "longDash",
+    lgDashDot: "longDashDot",
+    lgDashDotDot: "longDashDotDot",
+};
+/** `<a:ln>` → outline; `<a:noFill>` inside it means explicitly strokeless (width 0). */
+function parseShapeOutline(spPr) {
+    const ln = get(spPr, "a:ln");
+    if (ln === undefined)
+        return undefined;
+    if (hasElement(ln, "a:noFill"))
+        return { width: 0 };
+    const solidFill = get(ln, "a:solidFill");
+    const color = parseDrawingColorValue(solidFill);
+    const wEmu = parseInt(get(ln, "a$.w") || "0");
+    const dashVal = get(ln, "a:prstDash.a$.val");
+    if (!color && !wEmu && !dashVal)
+        return undefined;
+    return {
+        color,
+        width: wEmu ? emuToPixels(wEmu) : undefined,
+        dash: dashVal ? DASH_RENAMES[dashVal] : undefined,
+        opacity: solidFill ? parseColorOpacity(solidFill) : undefined,
+    };
+}
+/** `<a:effectLst><a:outerShdw>` → drop shadow (distance+direction → x/y offsets). */
+function parseShapeShadow(spPr) {
+    const shdw = get(spPr, "a:effectLst.a:outerShdw");
+    if (!shdw)
+        return undefined;
+    const distPx = emuToPixels(parseInt(get(shdw, "a$.dist") || "0"));
+    const dirRad = (parseInt(get(shdw, "a$.dir") || "0") / 60000) * (Math.PI / 180);
+    const blurRad = parseInt(get(shdw, "a$.blurRad") || "0");
+    return {
+        color: parseDrawingColorValue(shdw),
+        opacity: parseColorOpacity(shdw),
+        blurRadius: blurRad ? emuToPixels(blurRad) : undefined,
+        offsetXPixels: distPx ? Math.round(Math.cos(dirRad) * distPx) : undefined,
+        offsetYPixels: distPx ? Math.round(Math.sin(dirRad) * distPx) : undefined,
+    };
+}
+/** `<xdr:style>` fill/line/effect/font references into the theme format scheme. */
+function parseShapeStyleRefs(shape) {
+    const style = get(shape, "xdr:style") || get(shape, "style");
+    if (!style)
+        return undefined;
+    const parseRef = (name) => {
+        const ref = get(style, name);
+        if (!ref)
+            return undefined;
+        const index = parseInt(get(ref, "a$.idx") || "0");
+        const color = parseDrawingColorValue(ref);
+        return color ? { index, color } : undefined;
+    };
+    const refs = {
+        fill: parseRef("a:fillRef"),
+        line: parseRef("a:lnRef"),
+        effect: parseRef("a:effectRef"),
+    };
+    const fontRef = get(style, "a:fontRef");
+    if (fontRef) {
+        const scheme = get(fontRef, "a$.idx");
+        if (scheme === "major" || scheme === "minor") {
+            refs.font = { scheme, color: parseDrawingColorValue(fontRef) };
+        }
+    }
+    return refs.fill || refs.line || refs.effect || refs.font ? refs : undefined;
+}
+/**
+ * Whether an `<xdr:sp>` should import as a drawing shape (`EmbedShapeSpec`)
+ * rather than a textbox. Text boxes are excluded explicitly (`txBox="1"`), and
+ * a rect with no `<xdr:style>` block stays a textbox too — routing those to
+ * the shape renderer would repaint plain text notes with the default accent
+ * shape style.
+ */
+export function isDrawingShape(shape) {
+    const txBox = get(shape, "xdr:nvSpPr.xdr:cNvSpPr.a$.txBox") ||
+        get(shape, "nvSpPr.cNvSpPr.a$.txBox");
+    if (txBox === "1" || txBox === true)
+        return false;
+    const spPr = get(shape, "xdr:spPr") || get(shape, "spPr");
+    const preset = get(spPr, "a:prstGeom.a$.prst");
+    if (preset && preset !== "rect")
+        return true;
+    return hasElement(shape, "xdr:style") || hasElement(shape, "style");
+}
+/** Parse an `<xdr:sp>` drawing shape into an {@link EmbedShapeSpec}. */
+export function parseShapeSpec(shape) {
+    const spPr = get(shape, "xdr:spPr") || get(shape, "spPr");
+    const name = get(shape, "xdr:nvSpPr.xdr:cNvPr.a$.name") ||
+        get(shape, "nvSpPr.cNvPr.a$.name");
+    // Shape text rides the textbox content model; box-level background/borders
+    // are shape fill/outline concerns, so only the text fields carry over. An
+    // empty text body (Excel writes one on every shape) is omitted entirely.
+    let textBody;
+    const txBody = get(shape, "xdr:txBody") || get(shape, "txBody");
+    if (txBody) {
+        const tb = parseTextBoxContent(txBody, shape);
+        const hasText = Boolean(tb.text?.trim()) ||
+            Boolean(tb.richText?.some((run) => run.text.trim()));
+        if (hasText) {
+            textBody = {
+                text: tb.text,
+                richText: tb.richText,
+                textFormat: tb.textFormat,
+                verticalAlignment: tb.verticalAlignment,
+                horizontalAlignment: tb.horizontalAlignment,
+                wrapStrategy: tb.wrapStrategy,
+                textRotation: tb.textRotation,
+                padding: tb.padding,
+            };
+        }
+    }
+    const xfrm = get(spPr, "a:xfrm");
+    const flipH = get(xfrm, "a$.flipH");
+    const flipV = get(xfrm, "a$.flipV");
+    return {
+        type: "shape",
+        name,
+        geometry: parseShapeGeometry(spPr) ?? { preset: "rect" },
+        fill: parseShapeFill(spPr),
+        outline: parseShapeOutline(spPr),
+        shadow: parseShapeShadow(spPr),
+        styleRefs: parseShapeStyleRefs(shape),
+        textBody,
+        flipHorizontal: flipH === "1" || flipH === true ? true : undefined,
+        flipVertical: flipV === "1" || flipV === true ? true : undefined,
+    };
+}
+/**
+ * Parse textbox content from DrawingML text body
+ * @param txBody The text body element from DrawingML
+ * @param shape The shape element containing formatting properties
+ * @returns EmbedTextBoxSpec object
+ */
+function parseTextBoxContent(txBody, shape) {
+    const richText = [];
+    let plainText = "";
+    // Get paragraphs
+    const paragraphs = get(txBody, "a:p") || [];
+    const paragraphArray = Array.isArray(paragraphs) ? paragraphs : [paragraphs];
+    for (const paragraph of paragraphArray) {
+        // Extract paragraph properties for indentation and bullets
+        const pPr = get(paragraph, "a:pPr") || {};
+        const indentEmu = parseInt(get(pPr, "a$.marL") || get(pPr, "a$.indent") || "0");
+        // Convert EMUs to approximate character spaces (roughly 90000 EMUs ≈ 1 character space)
+        const indentSpaces = Math.round(indentEmu / 90000);
+        // Check for bullets
+        let bulletChar = "";
+        const buChar = get(pPr, "a:buChar.a$.char");
+        const buAutoNum = get(pPr, "a:buAutoNum");
+        const buNone = get(pPr, "a:buNone");
+        if (!buNone) {
+            if (buChar) {
+                // Custom bullet character (e.g., "•", "-", etc.)
+                bulletChar = buChar + " ";
+            }
+            else if (buAutoNum) {
+                // Auto-numbered bullets (would need context to track numbering)
+                bulletChar = "• ";
+            }
+        }
+        // Get text runs
+        const runs = get(paragraph, "a:r") || [];
+        const runArray = Array.isArray(runs) ? runs : runs ? [runs] : [];
+        // Add indentation and bullet to the first run of the paragraph
+        let isFirstRun = true;
+        for (const run of runArray) {
+            let text = get(run, "a:t.t$") || get(run, "a:t") || "";
+            // Handle tab characters
+            const tabElements = get(run, "a:tab");
+            if (tabElements) {
+                const tabCount = Array.isArray(tabElements) ? tabElements.length : 1;
+                text = "\t".repeat(tabCount) + text;
+            }
+            // Add indentation and bullet to the first run
+            if (isFirstRun) {
+                if (indentSpaces > 0) {
+                    const indent = " ".repeat(indentSpaces);
+                    text = indent + text;
+                }
+                if (bulletChar) {
+                    text = bulletChar + text;
+                }
+                isFirstRun = false;
+            }
+            plainText += text;
+            // Parse run properties
+            const rPr = get(run, "a:rPr") || {};
+            const format = {};
+            // Font size (in points * 100, e.g., 1100 = 11pt)
+            const sz = parseInt(get(rPr, "a$.sz") || "0");
+            if (sz > 0) {
+                format.fontSize = sz / 100;
+            }
+            // Bold
+            const bold = get(rPr, "a$.b");
+            if (bold === "1" || bold === true) {
+                format.bold = true;
+            }
+            // Italic
+            const italic = get(rPr, "a$.i");
+            if (italic === "1" || italic === true) {
+                format.italic = true;
+            }
+            // Underline
+            const underline = get(rPr, "a$.u");
+            if (underline && underline !== "none") {
+                format.underline = true;
+            }
+            // Strikethrough
+            const strike = get(rPr, "a$.strike");
+            if (strike && strike !== "noStrike") {
+                format.strikethrough = true;
+            }
+            // Font family
+            const fontFamily = get(rPr, "a:latin.a$.typeface");
+            if (fontFamily) {
+                format.fontFamily = fontFamily;
+            }
+            // Text color (supports RGB and theme colors)
+            const solidFill = get(rPr, "a:solidFill");
+            const color = parseDrawingColor(solidFill);
+            if (color) {
+                format.color = color;
+            }
+            richText.push({
+                text,
+                format: Object.keys(format).length > 0 ? format : undefined,
+            });
+        }
+        // Add paragraph break (newline) between paragraphs
+        if (paragraphArray.indexOf(paragraph) < paragraphArray.length - 1) {
+            plainText += "\n";
+            richText.push({ text: "\n" });
+        }
+    }
+    // Get shape properties for background, borders, etc.
+    const spPr = get(shape, "xdr:spPr") || get(shape, "spPr");
+    const spec = {
+        type: "textbox",
+        text: plainText,
+        richText: richText.length > 0 ? richText : undefined,
+    };
+    // Parse background color (supports RGB and theme colors)
+    const solidFill = get(spPr, "a:solidFill");
+    const bgColor = parseDrawingColor(solidFill);
+    if (bgColor) {
+        spec.backgroundColor = bgColor;
+    }
+    // Parse text alignment and other properties from body properties
+    const bodyPr = get(txBody, "a:bodyPr") || {};
+    const anchor = get(bodyPr, "a$.anchor");
+    if (anchor) {
+        // Map DrawingML anchor to our vertical alignment
+        const anchorMap = {
+            t: "top",
+            ctr: "middle",
+            b: "bottom",
+        };
+        spec.verticalAlignment = anchorMap[anchor];
+    }
+    // Parse wrap strategy
+    const wrap = get(bodyPr, "a$.wrap");
+    if (wrap) {
+        const wrapMap = {
+            square: "wrap",
+            none: "overflow",
+        };
+        spec.wrapStrategy = wrapMap[wrap];
+    }
+    // Parse padding (insets) - convert from EMUs to pixels
+    const lIns = parseInt(get(bodyPr, "a$.lIns") || "0");
+    const rIns = parseInt(get(bodyPr, "a$.rIns") || "0");
+    const tIns = parseInt(get(bodyPr, "a$.tIns") || "0");
+    const bIns = parseInt(get(bodyPr, "a$.bIns") || "0");
+    // Use average of insets as padding (or could store separately if needed)
+    const avgPadding = (lIns + rIns + tIns + bIns) / 4;
+    if (avgPadding > 0) {
+        spec.padding = emuToPixels(avgPadding);
+    }
+    return spec;
+}
+/**
+ * Determine if a two-cell anchored image is inside a cell
+ * @param editAs The editAs attribute value
+ * @param fromCol From column
+ * @param fromRow From row
+ * @param toCol To column
+ * @param toRow To row
+ * @returns Boolean indicating if image is inside a cell
+ */
+function determineIfTwoCellInsideCell(editAs, fromCol, fromRow, toCol, toRow) {
+    // Two-cell anchors represent floating images in Excel. We only mark them as
+    // "cell" content when the rectangle is constrained to a single cell.
+    return fromCol === toCol && fromRow === toRow;
+}
+/**
+ * Determine if a oneCellAnchor image is inside a cell
+ * Using EMU values for accurate assessment
+ * @param fromColOff Column offset in EMUs
+ * @param fromRowOff Row offset in EMUs
+ * @param fLocksWithSheet Whether image locks with sheet
+ * @param cx Image width in EMUs
+ * @param cy Image height in EMUs
+ * @returns Boolean indicating if the image is inside a cell
+ */
+export function determineIfOneCellInsideCell(fromColOff, fromRowOff, fLocksWithSheet, cx, cy) {
+    const widthPixels = emuToPixels(Math.max(0, cx));
+    const heightPixels = emuToPixels(Math.max(0, cy));
+    const exceedsCellSize = (!!widthPixels && widthPixels > DEFAULT_CELL_IMAGE_MAX_SIZE_PX) ||
+        (!!heightPixels && heightPixels > DEFAULT_CELL_IMAGE_MAX_SIZE_PX);
+    if (exceedsCellSize) {
+        return false;
+    }
+    if (fLocksWithSheet === "1") {
+        return true;
+    }
+    const offsetXPixels = Math.abs(emuToPixels(fromColOff));
+    const offsetYPixels = Math.abs(emuToPixels(fromRowOff));
+    return (offsetXPixels <= CELL_IMAGE_OFFSET_THRESHOLD_PX &&
+        offsetYPixels <= CELL_IMAGE_OFFSET_THRESHOLD_PX);
+}