@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/esm/modules/word/advanced/ole-objects.js

@@ -0,0 +1,271 @@
+/**
+ * DOCX Module - OLE Embedded Objects
+ *
+ * Provides support for reading and round-tripping OLE (Object Linking and Embedding)
+ * objects within DOCX files. OLE objects allow embedding other documents (Excel
+ * spreadsheets, PowerPoint presentations, PDFs, etc.) within a Word document.
+ *
+ * OLE objects in OOXML are stored as:
+ * - Binary data in word/embeddings/*.bin (OLE2 compound document)
+ * - Referenced via r:id in w:object/o:OLEObject elements
+ * - May have a preview image (EMF/WMF) in word/media/
+ *
+ * This module focuses on preservation (round-trip) and metadata extraction,
+ * not full OLE compound document manipulation.
+ */
+import { getFileName } from "../core/opc-paths.js";
+// =============================================================================
+// OLE Object Extraction
+// =============================================================================
+/**
+ * Extract metadata about OLE embedded objects from a parsed DOCX document.
+ * OLE objects are preserved in opaqueParts during reading; this function
+ * inspects them to extract meaningful metadata.
+ *
+ * @param doc - The parsed DOCX document.
+ * @returns Extraction result with OLE object metadata.
+ */
+export function extractOleObjects(doc) {
+    const objects = [];
+    const summary = {};
+    // Scan opaque parts for OLE embeddings
+    if (doc.opaqueParts) {
+        for (const part of doc.opaqueParts) {
+            if (isOleEmbedding(part.path)) {
+                const obj = parseOlePartMetadata(part);
+                if (obj) {
+                    objects.push(obj);
+                    summary[obj.progId] = (summary[obj.progId] ?? 0) + 1;
+                }
+            }
+        }
+    }
+    // Also scan body for OpaqueDrawing elements that may contain OLE references
+    for (const element of doc.body) {
+        if (element.type === "opaqueDrawing") {
+            const oleFromDrawing = extractOleFromRawXml(element.rawXml);
+            if (oleFromDrawing) {
+                // Check if we already have this object from opaque parts
+                const exists = objects.some(o => o.rId === oleFromDrawing.rId);
+                if (!exists) {
+                    objects.push(oleFromDrawing);
+                    summary[oleFromDrawing.progId] = (summary[oleFromDrawing.progId] ?? 0) + 1;
+                }
+            }
+        }
+    }
+    return { objects, summary };
+}
+/**
+ * Check if a document contains any OLE embedded objects.
+ */
+export function hasOleObjects(doc) {
+    if (doc.opaqueParts) {
+        for (const part of doc.opaqueParts) {
+            if (isOleEmbedding(part.path)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Get the binary data of a specific OLE object by its relationship ID.
+ * Returns undefined if not found.
+ */
+export function getOleObjectData(doc, rId) {
+    if (!doc.opaqueParts) {
+        return undefined;
+    }
+    for (const part of doc.opaqueParts) {
+        if (isOleEmbedding(part.path)) {
+            // Check relationships for matching rId
+            if (part.relationships) {
+                for (const rel of part.relationships) {
+                    if (rel.id === rId) {
+                        return part.data;
+                    }
+                }
+            }
+            // Also check if the file path matches the expected pattern for this
+            // rId. We anchor on a non-digit boundary so `rId4` does not also
+            // match `oleObject40`, `oleObject41`, … Without the boundary, the
+            // first such adjacent file silently leaks back as if it were the
+            // requested OLE object.
+            const expectedStem = rId.replace("rId", "oleObject");
+            const oleStemRe = new RegExp(`(^|/)${escapeRegex(expectedStem)}(?:\\.[^./]+)?$`);
+            if (oleStemRe.test(part.path)) {
+                return part.data;
+            }
+        }
+    }
+    // Unknown rId — do NOT fall back to "first embedded blob" (that historically
+    // returned an arbitrary OLE object and silently leaked the wrong data).
+    return undefined;
+}
+/**
+ * Create an OLE embedding plus, optionally, its preview image.
+ *
+ * Returns an {@link OleEmbeddingResult} with one or two `OpaquePart`s plus
+ * suggested relationship IDs. Each call gets a unique counter-based file
+ * name so calling this helper repeatedly does not produce path
+ * collisions; pass `options.fileName` to force a specific name.
+ *
+ * The previous signature returned only one `OpaquePart` and silently
+ * dropped `options.previewImage` / `options.previewContentType`. That has
+ * been removed — the new shape forces callers to wire up preview parts
+ * properly when they want one.
+ *
+ * @param data - The binary data of the OLE object (OLE2 compound document).
+ * @param progId - The OLE ProgId (e.g. "Excel.Sheet.12").
+ * @param options - Additional options.
+ */
+export function createOleEmbedding(data, progId, options) {
+    const oleSeq = nextOleSequence();
+    const fileName = options?.fileName ?? `oleObject${oleSeq}.bin`;
+    const olePart = {
+        path: `word/embeddings/${fileName}`,
+        data,
+        contentType: "application/vnd.openxmlformats-officedocument.oleObject",
+        relationships: undefined
+    };
+    const oleRId = `rIdOle${oleSeq}`;
+    // progId is metadata for downstream consumers — not stored on
+    // OpaquePart but accepted in the signature so callers can pass it
+    // alongside without a separate channel. We don't need it here.
+    void progId;
+    if (!options?.previewImage) {
+        return { olePart, oleRId };
+    }
+    if (!options.previewContentType) {
+        throw new Error("createOleEmbedding: options.previewImage requires options.previewContentType");
+    }
+    const previewExt = previewExtFromContentType(options.previewContentType);
+    const previewSeq = nextPreviewSequence();
+    const previewFileName = options.previewFileName ?? `oleImage${previewSeq}.${previewExt}`;
+    const previewPart = {
+        path: `word/media/${previewFileName}`,
+        data: options.previewImage,
+        contentType: options.previewContentType,
+        relationships: undefined
+    };
+    const previewRId = `rIdOleImg${previewSeq}`;
+    return { olePart, oleRId, previewPart, previewRId };
+}
+/** Module-level counters used to allocate unique file names per call. */
+let _oleSeq = 0;
+let _previewSeq = 0;
+function nextOleSequence() {
+    _oleSeq++;
+    return _oleSeq;
+}
+function nextPreviewSequence() {
+    _previewSeq++;
+    return _previewSeq;
+}
+function previewExtFromContentType(ct) {
+    const map = {
+        "image/png": "png",
+        "image/jpeg": "jpg",
+        "image/gif": "gif",
+        "image/x-emf": "emf",
+        "image/emf": "emf",
+        "image/x-wmf": "wmf",
+        "image/wmf": "wmf",
+        "image/bmp": "bmp",
+        "image/svg+xml": "svg"
+    };
+    return map[ct.toLowerCase()] ?? "bin";
+}
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+function isOleEmbedding(path) {
+    return path.startsWith("word/embeddings/") || (path.endsWith(".bin") && path.includes("embed"));
+}
+function parseOlePartMetadata(part) {
+    // Extract what we can from the path and content type
+    const fileName = getFileName(part.path);
+    // Try to detect progId from file extension or OLE magic
+    let progId = "Package"; // Default
+    if (fileName.includes("oleObject")) {
+        progId = detectProgIdFromData(part.data);
+    }
+    return {
+        rId: "",
+        progId,
+        objectType: "embedded",
+        displayAs: "icon",
+        fileName,
+        data: part.data
+    };
+}
+function detectProgIdFromData(data) {
+    // OLE2 compound document magic: D0 CF 11 E0 A1 B1 1A E1
+    if (data.length >= 8 &&
+        data[0] === 0xd0 &&
+        data[1] === 0xcf &&
+        data[2] === 0x11 &&
+        data[3] === 0xe0) {
+        // It's an OLE2 compound document — try to detect type
+        // Look for common signatures within the embedded data
+        const str = tryDecodeAscii(data.slice(0, 2048));
+        if (str.includes("Excel") || str.includes("Workbook") || str.includes("Sheet")) {
+            return "Excel.Sheet.12";
+        }
+        if (str.includes("PowerPoint") || str.includes("Presentation")) {
+            return "PowerPoint.Show.12";
+        }
+        if (str.includes("Visio")) {
+            return "Visio.Drawing.15";
+        }
+        return "Package";
+    }
+    // PDF signature
+    if (data.length >= 4 &&
+        data[0] === 0x25 &&
+        data[1] === 0x50 &&
+        data[2] === 0x44 &&
+        data[3] === 0x46) {
+        return "AcroExch.Document";
+    }
+    return "Package";
+}
+function tryDecodeAscii(data) {
+    let str = "";
+    for (let i = 0; i < data.length; i++) {
+        const b = data[i];
+        if (b >= 0x20 && b < 0x7f) {
+            str += String.fromCharCode(b);
+        }
+    }
+    return str;
+}
+function extractOleFromRawXml(rawXml) {
+    // Parse OLE object info from raw XML using regex (lightweight)
+    const progIdMatch = rawXml.match(/ProgID="([^"]+)"/i) ?? rawXml.match(/progId="([^"]+)"/i);
+    const rIdMatch = rawXml.match(/r:id="([^"]+)"/i);
+    const typeMatch = rawXml.match(/Type="([^"]+)"/i);
+    if (!progIdMatch) {
+        return null;
+    }
+    const progId = progIdMatch[1];
+    const rId = rIdMatch ? rIdMatch[1] : "";
+    const objectType = typeMatch && typeMatch[1].toLowerCase().includes("link") ? "linked" : "embedded";
+    // Extract dimensions
+    const widthMatch = rawXml.match(/(?:cx|width)="(\d+)"/i);
+    const heightMatch = rawXml.match(/(?:cy|height)="(\d+)"/i);
+    return {
+        rId,
+        progId,
+        objectType,
+        displayAs: rawXml.includes('DrawAspect="Icon"') ? "icon" : "content",
+        width: widthMatch ? parseInt(widthMatch[1], 10) : undefined,
+        height: heightMatch ? parseInt(heightMatch[1], 10) : undefined,
+        rawXml
+    };
+}
+/** Escape regex meta-characters in a literal string for use inside RegExp. */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/esm/modules/word/advanced/style-map.js

@@ -0,0 +1,322 @@
+/**
+ * DOCX Module - Style Mapping DSL
+ *
+ * A domain-specific language for customizing how DOCX elements are
+ * mapped to HTML output during conversion. Inspired by mammoth.js's
+ * style mapping approach but designed for this project's architecture.
+ *
+ * The DSL allows users to define rules that control the HTML output
+ * for specific Word styles, without modifying the core renderer.
+ *
+ * Syntax examples:
+ * ```
+ * p[style-name='Heading 1'] => h1.custom-heading
+ * p[style-name='Quote'] => blockquote.pull-quote
+ * r[style-name='Emphasis'] => em.highlight
+ * p[style-name='Code'] => pre > code
+ * table[style-name='GridTable'] => table.data-table
+ * ```
+ */
+// =============================================================================
+// Default Mappings
+// =============================================================================
+/** Default style mappings (standard Word styles → semantic HTML). */
+export const DEFAULT_STYLE_MAP = {
+    rules: [
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Heading 1" }],
+            target: { tagName: "h1" },
+            priority: 10
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Heading 2" }],
+            target: { tagName: "h2" },
+            priority: 10
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Heading 3" }],
+            target: { tagName: "h3" },
+            priority: 10
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Heading 4" }],
+            target: { tagName: "h4" },
+            priority: 10
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Heading 5" }],
+            target: { tagName: "h5" },
+            priority: 10
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Heading 6" }],
+            target: { tagName: "h6" },
+            priority: 10
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Title" }],
+            target: { tagName: "h1", className: "document-title" },
+            priority: 10
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Subtitle" }],
+            target: { tagName: "h2", className: "document-subtitle" },
+            priority: 10
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Quote" }],
+            target: { tagName: "blockquote" },
+            priority: 5
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "Intense Quote" }],
+            target: { tagName: "blockquote", className: "intense" },
+            priority: 5
+        },
+        {
+            source: "p",
+            conditions: [{ attribute: "style-name", value: "List Paragraph" }],
+            target: { tagName: "p", className: "list-paragraph" },
+            priority: 3
+        },
+        {
+            source: "r",
+            conditions: [{ attribute: "style-name", value: "Strong" }],
+            target: { tagName: "strong" },
+            priority: 5
+        },
+        {
+            source: "r",
+            conditions: [{ attribute: "style-name", value: "Emphasis" }],
+            target: { tagName: "em" },
+            priority: 5
+        },
+        {
+            source: "r",
+            conditions: [{ attribute: "style-name", value: "Hyperlink" }],
+            target: { tagName: "a" },
+            priority: 5
+        },
+        {
+            source: "r",
+            conditions: [{ attribute: "style-name", value: "Code" }],
+            target: { tagName: "code" },
+            priority: 5
+        },
+        { source: "b", conditions: [], target: { tagName: "strong" }, priority: 1 },
+        { source: "i", conditions: [], target: { tagName: "em" }, priority: 1 },
+        { source: "u", conditions: [], target: { tagName: "u" }, priority: 1 },
+        { source: "strike", conditions: [], target: { tagName: "s" }, priority: 1 }
+    ]
+};
+// =============================================================================
+// DSL Parser
+// =============================================================================
+/**
+ * Parse a style mapping DSL string into a StyleMap.
+ *
+ * @param dsl - The DSL string (one rule per line).
+ * @param options - Parser options.
+ * @returns A compiled StyleMap.
+ *
+ * @example
+ * ```ts
+ * const map = parseStyleMap(`
+ *   p[style-name='Heading 1'] => h1.title
+ *   p[style-name='Code Block'] => pre > code
+ *   r[style-name='Emphasis'] => em.custom-em
+ * `);
+ * ```
+ */
+export function parseStyleMap(dsl, options) {
+    const rules = [];
+    // Include defaults if requested
+    if (options?.includeDefaults !== false && options?.base) {
+        rules.push(...options.base.rules);
+    }
+    else if (options?.includeDefaults !== false && !options?.base) {
+        rules.push(...DEFAULT_STYLE_MAP.rules);
+    }
+    const lines = dsl
+        .split("\n")
+        .map(l => l.trim())
+        .filter(l => l && !l.startsWith("//") && !l.startsWith("#"));
+    for (const line of lines) {
+        const rule = parseRule(line);
+        if (rule) {
+            rules.push(rule);
+        }
+    }
+    // Sort by priority (highest first)
+    rules.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    return { rules };
+}
+/**
+ * Create a style map programmatically (without DSL parsing).
+ */
+export function createStyleMap(rules) {
+    const sorted = [...rules].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    return { rules: sorted };
+}
+/**
+ * Merge multiple style maps together.
+ * Later maps take precedence (higher priority) over earlier ones.
+ */
+export function mergeStyleMaps(...maps) {
+    const allRules = [];
+    for (let i = 0; i < maps.length; i++) {
+        // Add base priority offset based on position
+        for (const rule of maps[i].rules) {
+            allRules.push({
+                ...rule,
+                priority: (rule.priority ?? 0) + i * 100
+            });
+        }
+    }
+    allRules.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    return { rules: allRules };
+}
+/**
+ * Match a source element against the style map and return the target.
+ *
+ * @param map - The style map to match against.
+ * @param source - Source element type.
+ * @param attributes - Attributes of the source element.
+ * @returns The matching target, or undefined if no match.
+ */
+export function matchStyleMap(map, source, attributes) {
+    for (const rule of map.rules) {
+        if (rule.source !== source) {
+            continue;
+        }
+        const allMatch = rule.conditions.every(cond => {
+            const value = attributes[cond.attribute];
+            if (value === undefined) {
+                return false;
+            }
+            if (cond.regex) {
+                // The pattern source comes from a style-map DSL that may be
+                // attacker-controlled. We can't introspect a regex for
+                // catastrophic-backtracking risk, but we can:
+                //   1) reject the rule outright when the pattern is malformed
+                //      (the previous code threw, which broke the whole map);
+                //   2) cap the input string we feed to .test() so a quadratic
+                //      pattern can't run forever even if one slips through.
+                let re;
+                try {
+                    re = new RegExp(cond.value);
+                }
+                catch {
+                    return false;
+                }
+                const STYLE_MAP_REGEX_INPUT_CAP = 4096;
+                const limited = value.length > STYLE_MAP_REGEX_INPUT_CAP
+                    ? value.slice(0, STYLE_MAP_REGEX_INPUT_CAP)
+                    : value;
+                return re.test(limited);
+            }
+            return value === cond.value;
+        });
+        if (allMatch) {
+            return rule.target;
+        }
+    }
+    return undefined;
+}
+// =============================================================================
+// Internal: Rule Parser
+// =============================================================================
+function parseRule(line) {
+    // Format: source[conditions] => target
+    const arrowIdx = line.indexOf("=>");
+    if (arrowIdx < 0) {
+        return null;
+    }
+    const sourcePart = line.substring(0, arrowIdx).trim();
+    const targetPart = line.substring(arrowIdx + 2).trim();
+    // Parse source
+    const sourceMatch = sourcePart.match(/^(p|r|table|image|b|i|u|strike)(.*)$/);
+    if (!sourceMatch) {
+        return null;
+    }
+    const sourceType = sourceMatch[1];
+    const conditionsStr = sourceMatch[2];
+    // Parse conditions: [attr='value'][attr2='value2']
+    const conditions = [];
+    const condRegex = /\[([^=]+)='([^']+)'\]/g;
+    let condMatch;
+    while ((condMatch = condRegex.exec(conditionsStr)) !== null) {
+        conditions.push({
+            attribute: condMatch[1],
+            value: condMatch[2]
+        });
+    }
+    // Also support regex conditions: [attr~='pattern']
+    const regexCondRegex = /\[([^~]+)~='([^']+)'\]/g;
+    while ((condMatch = regexCondRegex.exec(conditionsStr)) !== null) {
+        conditions.push({
+            attribute: condMatch[1],
+            value: condMatch[2],
+            regex: true
+        });
+    }
+    // Parse target
+    const target = parseTarget(targetPart);
+    if (!target) {
+        return null;
+    }
+    return {
+        source: sourceType,
+        conditions,
+        target,
+        priority: conditions.length > 0 ? 5 : 1
+    };
+}
+function parseTarget(targetStr) {
+    // Format: tagName.className > childTag.childClass
+    const parts = targetStr.split(">").map(s => s.trim());
+    const parseSingle = (s) => {
+        // tag.class1.class2[attr=value]
+        const tagMatch = s.match(/^([a-zA-Z][a-zA-Z0-9]*)((?:\.[a-zA-Z_-][a-zA-Z0-9_-]*)*)?(\[.*\])?$/);
+        if (!tagMatch) {
+            return null;
+        }
+        const tagName = tagMatch[1];
+        const className = tagMatch[2] ? tagMatch[2].substring(1).replace(/\./g, " ") : undefined;
+        // Parse attributes [key=value]
+        let attributes;
+        if (tagMatch[3]) {
+            attributes = {};
+            const attrRegex = /\[([^=]+)=([^\]]+)\]/g;
+            let attrMatch;
+            while ((attrMatch = attrRegex.exec(tagMatch[3])) !== null) {
+                attributes[attrMatch[1]] = attrMatch[2].replace(/^['"]|['"]$/g, "");
+            }
+        }
+        return { tagName, className: className || undefined, attributes };
+    };
+    if (parts.length === 0) {
+        return null;
+    }
+    const first = parseSingle(parts[0]);
+    if (!first) {
+        return null;
+    }
+    if (parts.length > 1) {
+        const child = parseSingle(parts[1]);
+        if (child) {
+            return { ...first, child };
+        }
+    }
+    return first;
+}