@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/query/mail-merge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 type { DocxDocument } from "../types.js";
+/**
+ * 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 declare function mailMerge(doc: DocxDocument, data: Record<string, string>, options?: {
+    /** If true, remove fields not found in data. Default: false (leave unchanged). */
+    removeUnmatched?: boolean;
+}): number;

package/dist/browser/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;
+}

package/dist/browser/modules/word/query/merge.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Document Merge API
+ *
+ * Merge multiple DocxDocument bodies into a single document.
+ *
+ * The first document is taken as the base (its styles, settings, page layout,
+ * etc. become the foundation). Each subsequent document is appended after a
+ * section break. Numbering definitions, instances and the body references
+ * that point to them are rewritten when the appended document collides with
+ * IDs already present in the base. Image rIds, footnote/endnote ids and
+ * comment ids are also remapped, and the corresponding parts (footnotes,
+ * endnotes, comments) are merged so that references emitted in the body
+ * still resolve.
+ *
+ * What is *not* merged today (callers needing these should compose at a
+ * higher level):
+ *   - headers / footers (only the base document's are kept; appended
+ *     documents' header/footer parts are dropped)
+ *   - customXmlParts, embeddedFonts, settings, coreProperties, app
+ *     metadata, theme, document protection, signatures, vbaProject
+ *
+ * Body content from appended documents is deep-cloned so that callers'
+ * models are never mutated.
+ */
+import type { DocxDocument } from "../types.js";
+/** Options for merging documents. */
+export interface MergeOptions {
+    /** Break type between merged documents. Default: "nextPage". */
+    readonly sectionBreak?: "continuous" | "nextPage" | "evenPage" | "oddPage";
+}
+/**
+ * Merge multiple DocxDocument bodies into a single document.
+ *
+ * The first document is used as the base (preserving its styles, numbering,
+ * settings, etc.). Subsequent documents' body content is appended with
+ * section breaks between them. IDs that collide with the base are remapped
+ * during the deep-clone of each appended body:
+ *   - paragraph numbering refs (numId)
+ *   - inline / floating image rIds
+ *   - footnote, endnote and comment references (and their range markers)
+ *
+ * The corresponding `footnotes`, `endnotes`, `comments` and `images`
+ * collections are merged in tandem so references emitted into the body
+ * still resolve in the output package.
+ *
+ * @param documents - Array of documents to merge (at least 1).
+ * @param options - Optional merge settings.
+ * @returns A new merged DocxDocument.
+ */
+export declare function mergeDocuments(documents: readonly DocxDocument[], options?: MergeOptions): DocxDocument;