@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/advanced/ole-objects.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 type { DocxDocument, OpaquePart } from "../types.js";
+/** OLE object type classification. */
+export type OleObjectType = "embedded" | "linked";
+/** OLE object display style. */
+export type OleDisplayAs = "icon" | "content";
+/** Metadata about an OLE embedded object. */
+export interface OleObject {
+    /** Unique relationship ID for the OLE binary. */
+    readonly rId: string;
+    /** OLE ProgId (e.g. "Excel.Sheet.12", "PowerPoint.Slide.12", "Package"). */
+    readonly progId: string;
+    /** Whether the object is embedded or linked. */
+    readonly objectType: OleObjectType;
+    /** Display mode. */
+    readonly displayAs: OleDisplayAs;
+    /** Relationship ID for the preview image (EMF/WMF). */
+    readonly imageRId?: string;
+    /** Shape ID for the hosting VML shape. */
+    readonly shapeId?: string;
+    /** Object width in EMU. */
+    readonly width?: number;
+    /** Object height in EMU. */
+    readonly height?: number;
+    /** File name of the embedded data within the archive. */
+    readonly fileName?: string;
+    /** The raw binary data of the OLE object. */
+    readonly data?: Uint8Array;
+    /** Link target (for linked objects). */
+    readonly linkTarget?: string;
+    /** Raw XML of the w:object element for round-trip preservation. */
+    readonly rawXml?: string;
+}
+/** Result of extracting OLE objects from a document. */
+export interface OleExtractionResult {
+    /** All OLE objects found in the document. */
+    readonly objects: readonly OleObject[];
+    /** Mapping of progId to count. */
+    readonly summary: Readonly<Record<string, number>>;
+}
+/**
+ * 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 declare function extractOleObjects(doc: DocxDocument): OleExtractionResult;
+/**
+ * Check if a document contains any OLE embedded objects.
+ */
+export declare function hasOleObjects(doc: DocxDocument): boolean;
+/**
+ * Get the binary data of a specific OLE object by its relationship ID.
+ * Returns undefined if not found.
+ */
+export declare function getOleObjectData(doc: DocxDocument, rId: string): Uint8Array | undefined;
+/**
+ * Result of `createOleEmbedding`. Contains the OLE binary part and,
+ * when a preview image was supplied, an additional media part for it
+ * plus the relationship rIds the caller should reference from the body
+ * model.
+ */
+export interface OleEmbeddingResult {
+    /** OLE binary opaque part (always present). */
+    readonly olePart: OpaquePart;
+    /** Suggested rId to use for the OLE binary in the document model. */
+    readonly oleRId: string;
+    /** Preview image media part (only when `options.previewImage` was supplied). */
+    readonly previewPart?: OpaquePart;
+    /** Suggested rId for the preview image. */
+    readonly previewRId?: string;
+}
+/**
+ * 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 declare function createOleEmbedding(data: Uint8Array, progId: string, options?: {
+    /** Override file name. Defaults to `oleObject<N>.bin` with a process-unique counter. */
+    fileName?: string;
+    /** Optional preview image bytes (typically EMF or PNG). */
+    previewImage?: Uint8Array;
+    /** Content type for the preview image. Required when `previewImage` is set. */
+    previewContentType?: string;
+    /** Override preview file name. Defaults to `image<N>.<ext>` from previewContentType. */
+    previewFileName?: string;
+}): OleEmbeddingResult;

package/dist/browser/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/browser/modules/word/advanced/style-map.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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
+ * ```
+ */
+/** Target element type in the mapping rule. */
+export type MappingSourceType = "p" | "r" | "table" | "image" | "b" | "i" | "u" | "strike";
+/** A condition for matching source elements. */
+export interface MappingCondition {
+    /** Attribute to match on. */
+    readonly attribute: "style-name" | "style-id" | "outline-level" | "numbering-level" | "is-bold" | "is-italic";
+    /** Value to match (exact or regex). */
+    readonly value: string;
+    /** Use regex matching. */
+    readonly regex?: boolean;
+}
+/** Target HTML element specification. */
+export interface MappingTarget {
+    /** HTML tag name. */
+    readonly tagName: string;
+    /** CSS class(es) to add. */
+    readonly className?: string;
+    /** Additional HTML attributes. */
+    readonly attributes?: Readonly<Record<string, string>>;
+    /** Nested element (for `pre > code` style mappings). */
+    readonly child?: MappingTarget;
+    /** Whether to preserve separator. */
+    readonly separator?: string;
+    /** Whether this is a "fresh" mapping (wrap each paragraph separately). */
+    readonly fresh?: boolean;
+}
+/** A single style mapping rule. */
+export interface StyleMappingRule {
+    /** Source element type. */
+    readonly source: MappingSourceType;
+    /** Conditions that must all be satisfied. */
+    readonly conditions: readonly MappingCondition[];
+    /** Target HTML output. */
+    readonly target: MappingTarget;
+    /** Priority (higher = checked first). Default: 0. */
+    readonly priority?: number;
+}
+/** A compiled set of style mapping rules. */
+export interface StyleMap {
+    /** All rules, sorted by priority (highest first). */
+    readonly rules: readonly StyleMappingRule[];
+}
+/** Options for the style mapping parser. */
+export interface StyleMapOptions {
+    /** Base rules to include (before user rules). */
+    readonly base?: StyleMap;
+    /** Whether to include default mappings (Heading → h1-h6, etc.). */
+    readonly includeDefaults?: boolean;
+}
+/** Default style mappings (standard Word styles → semantic HTML). */
+export declare const DEFAULT_STYLE_MAP: StyleMap;
+/**
+ * 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 declare function parseStyleMap(dsl: string, options?: StyleMapOptions): StyleMap;
+/**
+ * Create a style map programmatically (without DSL parsing).
+ */
+export declare function createStyleMap(rules: readonly StyleMappingRule[]): StyleMap;
+/**
+ * Merge multiple style maps together.
+ * Later maps take precedence (higher priority) over earlier ones.
+ */
+export declare function mergeStyleMaps(...maps: readonly StyleMap[]): StyleMap;
+/**
+ * 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 declare function matchStyleMap(map: StyleMap, source: MappingSourceType, attributes: Readonly<Record<string, string>>): MappingTarget | undefined;