@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/core/mapper.js

@@ -0,0 +1,427 @@
+/**
+ * DOCX Module - Immutable Document Mapper
+ *
+ * Provides `mapDocument()` and the `DocxTransformer` interface for rebuilding
+ * a document tree with transformations applied to specific node types.
+ *
+ * Unlike the read-only `walkDocument()` (in walker.ts), this mapper produces
+ * a new document without mutating the input.
+ */
+import { isRun } from "./text-utils.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Immutable document tree transformation.
+ * Rebuilds the document tree, allowing callers to replace or filter nodes.
+ * Never mutates the input document.
+ *
+ * @param doc - The document to transform.
+ * @param transformer - Callbacks to transform each node type.
+ * @param options - Controls which document parts to include.
+ * @returns A new DocxDocument with transformations applied.
+ */
+export function mapDocument(doc, transformer, options) {
+    const opts = {
+        includeHeaders: options?.includeHeaders ?? true,
+        includeFooters: options?.includeFooters ?? true,
+        includeFootnotes: options?.includeFootnotes ?? true,
+        includeEndnotes: options?.includeEndnotes ?? true,
+        includeComments: options?.includeComments ?? false
+    };
+    const basePath = {
+        section: 0,
+        depth: 0,
+        inHeader: false,
+        inFooter: false,
+        inFootnote: false,
+        inEndnote: false,
+        inComment: false,
+        index: 0
+    };
+    // Map body
+    const body = mapBlocks(doc.body, transformer, basePath);
+    // Map headers
+    let headers = doc.headers;
+    if (opts.includeHeaders && doc.headers) {
+        const newHeaders = new Map();
+        for (const [key, headerDef] of doc.headers) {
+            const headerPath = { ...basePath, inHeader: true };
+            const mappedChildren = mapBlocks(headerDef.content.children, transformer, headerPath);
+            newHeaders.set(key, {
+                ...headerDef,
+                content: { ...headerDef.content, children: mappedChildren }
+            });
+        }
+        headers = newHeaders;
+    }
+    // Map footers
+    let footers = doc.footers;
+    if (opts.includeFooters && doc.footers) {
+        const newFooters = new Map();
+        for (const [key, footerDef] of doc.footers) {
+            const footerPath = { ...basePath, inFooter: true };
+            const mappedChildren = mapBlocks(footerDef.content.children, transformer, footerPath);
+            newFooters.set(key, {
+                ...footerDef,
+                content: { ...footerDef.content, children: mappedChildren }
+            });
+        }
+        footers = newFooters;
+    }
+    // Map footnotes
+    let footnotes = doc.footnotes;
+    if (opts.includeFootnotes && doc.footnotes) {
+        footnotes = doc.footnotes.map(note => {
+            if (note.id <= 0) {
+                return note;
+            }
+            const notePath = { ...basePath, inFootnote: true };
+            const mappedContent = mapBlocks(note.content, transformer, notePath);
+            return { ...note, content: mappedContent };
+        });
+    }
+    // Map endnotes
+    let endnotes = doc.endnotes;
+    if (opts.includeEndnotes && doc.endnotes) {
+        endnotes = doc.endnotes.map(note => {
+            if (note.id <= 0) {
+                return note;
+            }
+            const notePath = { ...basePath, inEndnote: true };
+            const mappedContent = mapBlocks(note.content, transformer, notePath);
+            return { ...note, content: mappedContent };
+        });
+    }
+    // Map comments
+    let comments = doc.comments;
+    if (opts.includeComments && doc.comments) {
+        comments = doc.comments.map(comment => {
+            const commentPath = { ...basePath, inComment: true };
+            const mappedContent = mapBlocks(comment.content, transformer, commentPath);
+            return { ...comment, content: mappedContent };
+        });
+    }
+    return {
+        ...doc,
+        body,
+        headers,
+        footers,
+        footnotes,
+        endnotes,
+        comments
+    };
+}
+// =============================================================================
+// Internal Mapper Helpers
+// =============================================================================
+function mapBlocks(blocks, transformer, basePath) {
+    const result = [];
+    for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        const currentPath = { ...basePath, index: i };
+        // Call transformBodyContent first (supports null, single, or array return)
+        if (transformer.transformBodyContent) {
+            const transformed = transformer.transformBodyContent(block, currentPath);
+            if (transformed === null) {
+                continue;
+            }
+            if (Array.isArray(transformed)) {
+                // Flat-map: one block becomes multiple blocks
+                for (const item of transformed) {
+                    const mapped = mapBodyContent(item, transformer, currentPath);
+                    if (mapped !== null) {
+                        result.push(mapped);
+                    }
+                }
+                continue;
+            }
+            // Single replacement
+            const mapped = mapBodyContent(transformed, transformer, currentPath);
+            if (mapped !== null) {
+                result.push(mapped);
+            }
+        }
+        else {
+            // No transformBodyContent — just recurse
+            const mapped = mapBodyContent(block, transformer, currentPath);
+            if (mapped !== null) {
+                result.push(mapped);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Maximum nesting depth permitted during transformation. See
+ * `core/walker.ts` for the rationale; mirrored here so map and walk
+ * share the same abuse-resistance posture.
+ */
+const MAX_MAP_DEPTH = 1000;
+function mapBodyContent(block, transformer, path) {
+    if (path.depth > MAX_MAP_DEPTH) {
+        // Drop the offending subtree rather than blow the stack. Returning
+        // null removes the block from its parent collection in mapBlocks.
+        return null;
+    }
+    // Per-type transformer hooks fire only for paragraph / table / sdt.
+    // Other BodyContent variants don't have a dedicated hook — callers that
+    // want to replace them whole-cloth use `transformBodyContent` in
+    // mapBlocks. We still need to recurse into their nested paragraph
+    // structures so transformParagraph / transformRun / transformRunContent
+    // visit text inside text boxes, drawing shape text, and TOC cached
+    // paragraphs. Without that, e.g. replaceText silently misses content in
+    // those structures.
+    switch (block.type) {
+        case "paragraph":
+            return mapParagraph(block, transformer, path);
+        case "table":
+            return mapTable(block, transformer, path);
+        case "sdt":
+            return mapSdt(block, transformer, path);
+        case "textBox": {
+            const tb = block;
+            if (!tb.content || tb.content.length === 0) {
+                return block;
+            }
+            const innerPath = { ...path, depth: path.depth + 1 };
+            const mappedContent = mapBlocks(tb.content, transformer, innerPath);
+            if (mappedContent === tb.content) {
+                return block;
+            }
+            // textBox.content is typed as `readonly Paragraph[]`. If a
+            // `transformBodyContent` produced anything other than a paragraph
+            // (a table, an image, etc.) we'd be silently violating the type
+            // invariant — and downstream writers would crash trying to render
+            // the unexpected node. Throw loudly instead of dropping the data.
+            const filtered = [];
+            for (const b of mappedContent) {
+                if (b.type === "paragraph") {
+                    filtered.push(b);
+                }
+                else {
+                    throw new Error(`mapDocument: textBox.content must remain Paragraph[] but a ` +
+                        `transform produced "${b.type}". Either rewrite the transform ` +
+                        `to return only paragraphs here, or restructure the document ` +
+                        `at the body level instead.`);
+                }
+            }
+            return { ...block, content: filtered };
+        }
+        case "drawingShape": {
+            const shape = block;
+            if (!shape.textContent || shape.textContent.length === 0) {
+                return block;
+            }
+            const innerPath = { ...path, depth: path.depth + 1 };
+            const mappedText = mapBlocks(shape.textContent, transformer, innerPath);
+            if (mappedText === shape.textContent) {
+                return block;
+            }
+            const filtered = [];
+            for (const b of mappedText) {
+                if (b.type === "paragraph") {
+                    filtered.push(b);
+                }
+                else {
+                    throw new Error(`mapDocument: drawingShape.textContent must remain Paragraph[] ` +
+                        `but a transform produced "${b.type}".`);
+                }
+            }
+            return { ...block, textContent: filtered };
+        }
+        case "tableOfContents": {
+            const toc = block;
+            if (!toc.cachedParagraphs || toc.cachedParagraphs.length === 0) {
+                return block;
+            }
+            const innerPath = { ...path, depth: path.depth + 1 };
+            const mappedCache = mapBlocks(toc.cachedParagraphs, transformer, innerPath);
+            if (mappedCache === toc.cachedParagraphs) {
+                return block;
+            }
+            const filtered = [];
+            for (const b of mappedCache) {
+                if (b.type === "paragraph") {
+                    filtered.push(b);
+                }
+                else {
+                    throw new Error(`mapDocument: tableOfContents.cachedParagraphs must remain ` +
+                        `Paragraph[] but a transform produced "${b.type}".`);
+                }
+            }
+            return { ...block, cachedParagraphs: filtered };
+        }
+        default:
+            return block;
+    }
+}
+function mapParagraph(para, transformer, path) {
+    // Call transformParagraph
+    let current = para;
+    if (transformer.transformParagraph) {
+        current = transformer.transformParagraph(para, path);
+        if (current === null) {
+            return null;
+        }
+    }
+    // Map children (runs)
+    if (transformer.transformRun || transformer.transformRunContent) {
+        const newChildren = [];
+        for (let i = 0; i < current.children.length; i++) {
+            const child = current.children[i];
+            const childPath = { ...path, index: i, depth: path.depth + 1 };
+            const mapped = mapParagraphChild(child, transformer, childPath);
+            if (mapped !== null) {
+                newChildren.push(mapped);
+            }
+        }
+        current = { ...current, children: newChildren };
+    }
+    return current;
+}
+function mapParagraphChild(child, transformer, path) {
+    if (isRun(child)) {
+        return mapRun(child, transformer, path);
+    }
+    if ("type" in child) {
+        const typed = child;
+        switch (typed.type) {
+            case "hyperlink": {
+                const hl = child;
+                if (transformer.transformRun || transformer.transformRunContent) {
+                    const newChildren = [];
+                    for (let i = 0; i < hl.children.length; i++) {
+                        const run = hl.children[i];
+                        const runPath = { ...path, index: i, depth: path.depth + 1 };
+                        const mapped = mapRun(run, transformer, runPath);
+                        if (mapped !== null) {
+                            newChildren.push(mapped);
+                        }
+                    }
+                    return { ...hl, children: newChildren };
+                }
+                return child;
+            }
+            case "insertedRun": {
+                const ins = child;
+                const mappedRun = mapRun(ins.run, transformer, path);
+                if (mappedRun === null) {
+                    return null;
+                }
+                return { ...ins, run: mappedRun };
+            }
+            case "movedToRun": {
+                const moved = child;
+                const mappedRun = mapRun(moved.run, transformer, path);
+                if (mappedRun === null) {
+                    return null;
+                }
+                return { ...moved, run: mappedRun };
+            }
+            default:
+                return child;
+        }
+    }
+    // Default: treat as Run if isRun matches.
+    if (isRun(child)) {
+        return mapRun(child, transformer, path);
+    }
+    return child;
+}
+function mapRun(run, transformer, path) {
+    let current = run;
+    // Call transformRun
+    if (transformer.transformRun) {
+        current = transformer.transformRun(run, path);
+        if (current === null) {
+            return null;
+        }
+    }
+    // Map run content
+    if (transformer.transformRunContent) {
+        const newContent = [];
+        for (const content of current.content) {
+            const mapped = transformer.transformRunContent(content, current, path);
+            if (mapped !== null) {
+                newContent.push(mapped);
+            }
+        }
+        current = { ...current, content: newContent };
+    }
+    return current;
+}
+function mapTable(table, transformer, path) {
+    // Call transformTable
+    let current = table;
+    if (transformer.transformTable) {
+        current = transformer.transformTable(table, path);
+        if (current === null) {
+            return null;
+        }
+    }
+    // Always recurse into cells (even if transformTable returned as-is)
+    const newRows = [];
+    for (let ri = 0; ri < current.rows.length; ri++) {
+        const row = current.rows[ri];
+        const rowPath = { ...path, index: ri, depth: path.depth + 1 };
+        const newCells = [];
+        for (let ci = 0; ci < row.cells.length; ci++) {
+            const cell = row.cells[ci];
+            const cellPath = { ...rowPath, index: ci, depth: rowPath.depth + 1 };
+            const mappedContent = mapBlocks(cell.content, transformer, {
+                ...cellPath,
+                depth: cellPath.depth + 1
+            });
+            newCells.push({ ...cell, content: mappedContent });
+        }
+        newRows.push({ ...row, cells: newCells });
+    }
+    return { ...current, rows: newRows };
+}
+function mapSdt(sdt, transformer, path) {
+    // Call transformSdt
+    let current = sdt;
+    if (transformer.transformSdt) {
+        current = transformer.transformSdt(sdt, path);
+        if (current === null) {
+            return null;
+        }
+    }
+    // Recurse into content
+    const innerPath = { ...path, depth: path.depth + 1 };
+    const newContent = [];
+    for (let i = 0; i < current.content.length; i++) {
+        const item = current.content[i];
+        const itemPath = { ...innerPath, index: i };
+        if ("type" in item && item.type === "paragraph") {
+            const mapped = mapParagraph(item, transformer, itemPath);
+            if (mapped !== null) {
+                newContent.push(mapped);
+            }
+        }
+        else if ("type" in item && item.type === "table") {
+            const mapped = mapTable(item, transformer, itemPath);
+            if (mapped !== null) {
+                newContent.push(mapped);
+            }
+        }
+        else if ("type" in item && item.type === "sdt") {
+            // Recurse into nested SDTs (e.g. repeating-section item SDTs).
+            const mapped = mapSdt(item, transformer, itemPath);
+            if (mapped !== null) {
+                newContent.push(mapped);
+            }
+        }
+        else if ("content" in item && Array.isArray(item.content)) {
+            const mapped = mapRun(item, transformer, innerPath);
+            if (mapped !== null) {
+                newContent.push(mapped);
+            }
+        }
+        else {
+            newContent.push(item);
+        }
+    }
+    return { ...current, content: newContent };
+}

package/dist/browser/modules/word/core/opc-paths.d.ts

@@ -0,0 +1,33 @@
+/**
+ * OPC Path Utilities
+ *
+ * Small helpers for working with Open Packaging Conventions part paths.
+ * These are used throughout the reader/writer when resolving the location of
+ * a relationships file or extracting an extension to choose a content type.
+ */
+/**
+ * Get the `.rels` part path for a given part path.
+ *
+ * Per OPC convention, the relationships for `dir/name.ext` live at
+ * `dir/_rels/name.ext.rels`; for a top-level `name.ext` they live at
+ * `_rels/name.ext.rels`.
+ */
+export declare function getPartRelsPath(partPath: string): string;
+/**
+ * Extract the file name (last path segment) from a part path.
+ *
+ * @example
+ * getFileName("word/media/image1.png")  // "image1.png"
+ * getFileName("standalone.xml")         // "standalone.xml"
+ */
+export declare function getFileName(partPath: string): string;
+/**
+ * Extract the lower-cased file extension (without the dot) from a part path
+ * or file name. Returns an empty string when there is no extension.
+ *
+ * @example
+ * getFileExt("image1.PNG")        // "png"
+ * getFileExt("word/media/x.tiff") // "tiff"
+ * getFileExt("noext")             // ""
+ */
+export declare function getFileExt(partPath: string): string;

package/dist/browser/modules/word/core/opc-paths.js

@@ -0,0 +1,48 @@
+/**
+ * OPC Path Utilities
+ *
+ * Small helpers for working with Open Packaging Conventions part paths.
+ * These are used throughout the reader/writer when resolving the location of
+ * a relationships file or extracting an extension to choose a content type.
+ */
+/**
+ * Get the `.rels` part path for a given part path.
+ *
+ * Per OPC convention, the relationships for `dir/name.ext` live at
+ * `dir/_rels/name.ext.rels`; for a top-level `name.ext` they live at
+ * `_rels/name.ext.rels`.
+ */
+export function getPartRelsPath(partPath) {
+    const lastSlash = partPath.lastIndexOf("/");
+    const dir = lastSlash >= 0 ? partPath.substring(0, lastSlash) : "";
+    const name = lastSlash >= 0 ? partPath.substring(lastSlash + 1) : partPath;
+    return dir ? `${dir}/_rels/${name}.rels` : `_rels/${name}.rels`;
+}
+/**
+ * Extract the file name (last path segment) from a part path.
+ *
+ * @example
+ * getFileName("word/media/image1.png")  // "image1.png"
+ * getFileName("standalone.xml")         // "standalone.xml"
+ */
+export function getFileName(partPath) {
+    const lastSlash = partPath.lastIndexOf("/");
+    return lastSlash >= 0 ? partPath.substring(lastSlash + 1) : partPath;
+}
+/**
+ * Extract the lower-cased file extension (without the dot) from a part path
+ * or file name. Returns an empty string when there is no extension.
+ *
+ * @example
+ * getFileExt("image1.PNG")        // "png"
+ * getFileExt("word/media/x.tiff") // "tiff"
+ * getFileExt("noext")             // ""
+ */
+export function getFileExt(partPath) {
+    const fileName = getFileName(partPath);
+    const dot = fileName.lastIndexOf(".");
+    if (dot < 0 || dot === fileName.length - 1) {
+        return "";
+    }
+    return fileName.substring(dot + 1).toLowerCase();
+}

package/dist/browser/modules/word/core/text-utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * DOCX Module - Text Utilities & Type Guards
+ *
+ * Single source of truth for type guards and text extraction helpers
+ * used across the word module. Eliminates duplicated implementations
+ * of `isRun`, `extractParagraphText`, `extractMathText`, etc.
+ */
+import type { Paragraph, ParagraphChild, Run, MathContent, Hyperlink } from "../types.js";
+/**
+ * Check if a paragraph child is a Run.
+ *
+ * A Run is the only ParagraphChild without a `type` discriminator field.
+ * All other paragraph children (Hyperlink, InsertedRun, DeletedRun, MovedFromRun,
+ * MovedToRun, BookmarkStart/End, CommentRangeStart/End) have an explicit `type`
+ * string. Therefore, a child is a Run iff it has a `content` array AND no `type`
+ * field — this is more robust than checking `content` alone (since some typed
+ * children also have `content`-like properties).
+ */
+export declare function isRun(child: ParagraphChild): child is Run;
+/** Check if a paragraph child is a Hyperlink. */
+export declare function isHyperlink(child: ParagraphChild): child is Hyperlink;
+/**
+ * Extract plain text from a single run's content array.
+ */
+export declare function extractRunText(run: Run): string;
+/**
+ * Extract concatenated plain text from a paragraph's children (runs + hyperlinks).
+ * This recursively handles hyperlinks and tracked changes.
+ */
+export declare function extractParagraphText(para: Paragraph): string;
+/**
+ * Extract text from a single paragraph child (run, hyperlink, or tracked change).
+ */
+export declare function extractChildText(child: ParagraphChild): string;
+/**
+ * Extract plain text representation from math content elements.
+ */
+export declare function extractMathText(content: readonly MathContent[]): string;