@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/esm/modules/word/query/format-search.js

@@ -0,0 +1,329 @@
+/**
+ * Format-based Search for DOCX Documents
+ *
+ * Provides the ability to search for text runs that match specific formatting
+ * criteria (bold, italic, font, color, style, etc.) and optionally match text patterns.
+ *
+ * @stability experimental
+ *
+ * @example
+ * ```ts
+ * import { searchByFormat, type FormatCriteria } from "excelts/word";
+ *
+ * // Find all bold red text
+ * const results = searchByFormat(doc, { bold: true, color: "FF0000" });
+ *
+ * // Find all text in "Heading1" style
+ * const headings = searchByFormat(doc, { paragraphStyle: "Heading1" });
+ *
+ * // Find specific text with specific formatting
+ * const results = searchByFormat(doc, { bold: true, textMatch: /TODO/i });
+ * ```
+ */
+import { extractRunText } from "../core/text-utils.js";
+import { walkDocument } from "../core/walker.js";
+/**
+ * Search a document for text runs matching specific formatting criteria.
+ *
+ * @param doc - The document to search.
+ * @param criteria - Formatting criteria (all specified fields must match).
+ * @returns Array of matching results.
+ */
+export function searchByFormat(doc, criteria) {
+    const results = [];
+    let currentBodyIndex = 0;
+    let currentParaIndex = 0;
+    let currentParagraph = null;
+    let currentLocation = "body";
+    let tableDepth = 0;
+    const visitor = {
+        enterTable(_table, path) {
+            if (tableDepth === 0) {
+                currentBodyIndex = path.index;
+            }
+            tableDepth++;
+            currentParaIndex = 0;
+            return "continue";
+        },
+        leaveTable() {
+            tableDepth--;
+        },
+        enterParagraph(para, path) {
+            currentParagraph = para;
+            if (tableDepth === 0) {
+                currentBodyIndex = path.index;
+                currentParaIndex = 0;
+            }
+            if (path.inHeader) {
+                currentLocation = "header";
+            }
+            else if (path.inFooter) {
+                currentLocation = "footer";
+            }
+            else if (path.inFootnote) {
+                currentLocation = "footnote";
+            }
+            else if (path.inEndnote) {
+                currentLocation = "endnote";
+            }
+            else {
+                currentLocation = "body";
+            }
+            // If criteria specifies paragraphStyle, check it first
+            const paraStyle = para.properties?.style;
+            if (criteria.paragraphStyle && paraStyle !== criteria.paragraphStyle) {
+                return "skip";
+            }
+            return "continue";
+        },
+        leaveParagraph() {
+            if (tableDepth > 0) {
+                currentParaIndex++;
+            }
+        },
+        enterRun(run, path) {
+            if (matchesFormat(run, criteria)) {
+                const text = extractRunText(run);
+                if (matchesTextPattern(text, criteria.textMatch)) {
+                    results.push({
+                        bodyIndex: currentBodyIndex,
+                        paragraphIndex: currentParaIndex,
+                        runIndex: path.index,
+                        text,
+                        properties: run.properties,
+                        paragraphStyle: currentParagraph?.properties?.style,
+                        location: currentLocation
+                    });
+                }
+            }
+            return "skip";
+        },
+        enterHyperlink(hyperlink, path) {
+            // Search child runs of hyperlink
+            for (let li = 0; li < hyperlink.children.length; li++) {
+                const run = hyperlink.children[li];
+                if (matchesFormat(run, criteria)) {
+                    const text = extractRunText(run);
+                    if (matchesTextPattern(text, criteria.textMatch)) {
+                        results.push({
+                            bodyIndex: currentBodyIndex,
+                            paragraphIndex: currentParaIndex,
+                            runIndex: path.index,
+                            text,
+                            properties: run.properties,
+                            paragraphStyle: currentParagraph?.properties?.style,
+                            location: currentLocation
+                        });
+                    }
+                }
+            }
+            return "skip";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: true,
+        includeFooters: true,
+        includeFootnotes: true,
+        includeEndnotes: true,
+        includeComments: false
+    });
+    return results;
+}
+/**
+ * Count the number of runs matching specific formatting criteria.
+ *
+ * @param doc - The document to search.
+ * @param criteria - Formatting criteria.
+ * @returns The count of matching runs.
+ */
+export function countByFormat(doc, criteria) {
+    return searchByFormat(doc, criteria).length;
+}
+/**
+ * Get all unique formatting styles used in the document.
+ * Useful for understanding what formats exist before searching.
+ *
+ * @param doc - The document to analyze.
+ * @returns Array of unique RunProperties objects found.
+ */
+export function getUsedFormats(doc) {
+    const formatSet = new Map();
+    const visitor = {
+        enterRun(run) {
+            if (run.properties) {
+                const key = formatKey(run.properties);
+                if (!formatSet.has(key)) {
+                    formatSet.set(key, run.properties);
+                }
+            }
+            return "skip";
+        },
+        enterHyperlink(hyperlink) {
+            for (const run of hyperlink.children) {
+                if (run.properties) {
+                    const key = formatKey(run.properties);
+                    if (!formatSet.has(key)) {
+                        formatSet.set(key, run.properties);
+                    }
+                }
+            }
+            return "skip";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: false,
+        includeFooters: false,
+        includeFootnotes: false,
+        includeEndnotes: false,
+        includeComments: false
+    });
+    return Array.from(formatSet.values());
+}
+// =============================================================================
+// Internal Implementation
+// =============================================================================
+function matchesFormat(run, criteria) {
+    const props = run.properties;
+    // Character style check
+    if (criteria.characterStyle) {
+        if (props?.style !== criteria.characterStyle) {
+            return false;
+        }
+    }
+    // Bold
+    if (criteria.bold !== undefined) {
+        if ((props?.bold ?? false) !== criteria.bold) {
+            return false;
+        }
+    }
+    // Italic
+    if (criteria.italic !== undefined) {
+        if ((props?.italic ?? false) !== criteria.italic) {
+            return false;
+        }
+    }
+    // Underline. Word emits an explicit `"none"` underline style when the
+    // user clears underlining on a run (rather than removing the property
+    // entirely), so treat that the same as "no underline".
+    if (criteria.underline !== undefined) {
+        const u = props?.underline;
+        const hasUnderline = u !== undefined && u !== false && u !== "none";
+        if (hasUnderline !== criteria.underline) {
+            return false;
+        }
+    }
+    // Strikethrough
+    if (criteria.strike !== undefined) {
+        if ((props?.strike ?? false) !== criteria.strike) {
+            return false;
+        }
+    }
+    // Font
+    if (criteria.font) {
+        const runFont = getRunFontString(props);
+        if (!runFont || runFont.toLowerCase() !== criteria.font.toLowerCase()) {
+            return false;
+        }
+    }
+    // Size
+    if (criteria.size !== undefined) {
+        if (props?.size !== criteria.size) {
+            return false;
+        }
+    }
+    // Color
+    if (criteria.color) {
+        const runColor = getRunColor(props);
+        if (!runColor || runColor.toLowerCase() !== criteria.color.toLowerCase()) {
+            return false;
+        }
+    }
+    // Highlight
+    if (criteria.highlight) {
+        if (props?.highlight !== criteria.highlight) {
+            return false;
+        }
+    }
+    // Superscript
+    if (criteria.superscript !== undefined) {
+        const isSuperscript = props?.vertAlign === "superscript";
+        if (isSuperscript !== criteria.superscript) {
+            return false;
+        }
+    }
+    // Subscript
+    if (criteria.subscript !== undefined) {
+        const isSubscript = props?.vertAlign === "subscript";
+        if (isSubscript !== criteria.subscript) {
+            return false;
+        }
+    }
+    // Caps
+    if (criteria.caps !== undefined) {
+        if ((props?.caps ?? false) !== criteria.caps) {
+            return false;
+        }
+    }
+    // Small caps
+    if (criteria.smallCaps !== undefined) {
+        if ((props?.smallCaps ?? false) !== criteria.smallCaps) {
+            return false;
+        }
+    }
+    // Hidden
+    if (criteria.hidden !== undefined) {
+        if ((props?.vanish ?? false) !== criteria.hidden) {
+            return false;
+        }
+    }
+    return true;
+}
+function matchesTextPattern(text, pattern) {
+    if (!pattern) {
+        return true;
+    }
+    if (typeof pattern === "string") {
+        return text.includes(pattern);
+    }
+    // RegExp.test() advances `lastIndex` for /g and /y flags. Mutating the
+    // caller's regex would surprise code that re-uses the same instance
+    // afterwards, so we test against a fresh clone instead. The clone is
+    // cheap (V8 caches the parsed source) and sidesteps the global-state
+    // hazard entirely.
+    const cloned = new RegExp(pattern.source, pattern.flags);
+    return cloned.test(text);
+}
+function getRunFontString(props) {
+    if (!props?.font) {
+        return undefined;
+    }
+    if (typeof props.font === "string") {
+        return props.font;
+    }
+    return props.font.ascii ?? props.font.hAnsi;
+}
+function getRunColor(props) {
+    if (!props?.color) {
+        return undefined;
+    }
+    if (typeof props.color === "string") {
+        return props.color;
+    }
+    return props.color.val;
+}
+function formatKey(props) {
+    return JSON.stringify({
+        bold: props.bold,
+        italic: props.italic,
+        underline: props.underline ? true : undefined,
+        strike: props.strike,
+        font: typeof props.font === "string" ? props.font : props.font?.ascii,
+        size: props.size,
+        color: typeof props.color === "string" ? props.color : props.color?.val,
+        highlight: props.highlight,
+        vertAlign: props.vertAlign,
+        caps: props.caps,
+        smallCaps: props.smallCaps,
+        style: props.style
+    });
+}

package/dist/esm/modules/word/query/mail-merge.js

@@ -0,0 +1,111 @@
+/**
+ * Mail Merge API
+ *
+ * Replace MERGEFIELD fields in a document with values from a data map.
+ * Uses the unified walker from core/walker.ts for consistent traversal
+ * across body, headers, footers, footnotes, endnotes, tables, and SDTs.
+ *
+ * Note: This API mutates the document in place for backward compatibility.
+ */
+import { isHyperlink, isRun } from "../core/text-utils.js";
+import { walkDocument } from "../core/walker.js";
+// =============================================================================
+// Constants
+// =============================================================================
+/** Regex to parse MERGEFIELD instruction: MERGEFIELD "FieldName" or MERGEFIELD FieldName */
+const MERGEFIELD_RE = /^\s*MERGEFIELD\s+(?:"([^"]+)"|(\S+))/i;
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Execute a mail merge: replace all MERGEFIELD fields in the document with values from the data map.
+ *
+ * Fields not found in the data map are left unchanged (or optionally cleared).
+ * Traverses body, headers, footers, footnotes, endnotes, tables, SDTs, and comments.
+ *
+ * @param doc - The document to modify (mutated in place).
+ * @param data - Map of field names to replacement values.
+ * @param options - Optional settings.
+ * @returns The number of fields replaced.
+ */
+export function mailMerge(doc, data, options) {
+    let count = 0;
+    const removeUnmatched = options?.removeUnmatched ?? false;
+    walkDocument(doc, {
+        enterParagraph(para) {
+            count += mergeFieldsInParagraph(para, data, removeUnmatched);
+            return "skip"; // We handle run content ourselves
+        }
+    }, {
+        includeHeaders: true,
+        includeFooters: true,
+        includeFootnotes: true,
+        includeEndnotes: true,
+        includeComments: true
+    });
+    return count;
+}
+// =============================================================================
+// Internal helpers
+// =============================================================================
+function mergeFieldsInParagraph(para, data, removeUnmatched) {
+    let count = 0;
+    // Recurse into hyperlinks too — MERGEFIELDs are commonly placed inside
+    // hyperlink text (e.g. for personalized URLs). Also descend through
+    // tracked-insert and moved-to wrappers so merge fields inside accepted
+    // tracked changes still get filled. (Deleted / movedFromRun wrappers
+    // represent removals and are skipped, matching replaceText's
+    // convention.)
+    const visit = (children) => {
+        for (const child of children) {
+            if (isHyperlink(child)) {
+                visit(child.children);
+                continue;
+            }
+            if ("type" in child &&
+                (child.type === "insertedRun" ||
+                    child.type === "movedToRun")) {
+                const inner = child.run;
+                if (inner) {
+                    visit([inner]);
+                }
+                continue;
+            }
+            if (!isRun(child)) {
+                continue;
+            }
+            const content = child.content;
+            for (let j = 0; j < content.length; j++) {
+                const c = content[j];
+                if (c.type !== "field") {
+                    continue;
+                }
+                const match = MERGEFIELD_RE.exec(c.instruction);
+                if (!match) {
+                    continue;
+                }
+                const fieldName = match[1] ?? match[2];
+                // Use Object.hasOwn so prototype-chain entries (`__proto__`,
+                // `toString`, `constructor`, …) cannot bind to merge fields. With
+                // `in`, an unsanitised CSV header like `__proto__` would resolve
+                // to `Object.prototype.__proto__` and inject a non-string value
+                // (or even a function reference) into the document.
+                if (fieldName !== undefined && Object.hasOwn(data, fieldName)) {
+                    const raw = data[fieldName];
+                    // Coerce to string defensively — extractMergeFields advertises
+                    // `Record<string, string>`, but callers commonly pass values
+                    // through unfettered JSON / CSV parsers.
+                    const text = typeof raw === "string" ? raw : raw == null ? "" : String(raw);
+                    content[j] = { type: "text", text };
+                    count++;
+                }
+                else if (removeUnmatched) {
+                    content[j] = { type: "text", text: "" };
+                    count++;
+                }
+            }
+        }
+    };
+    visit(para.children);
+    return count;
+}