docxmlater 11.0.10 → 12.1.0

package/src/elements/Field.ts

@@ -6,11 +6,12 @@
  */
 
 import { XMLElement } from '../xml/XMLBuilder.js';
-import { RunFormatting, FormFieldData } from './Run.js';
+import { Run, RunFormatting, FormFieldData } from './Run.js';
 import {
   ParsedHyperlinkInstruction,
   parseHyperlinkInstruction,
   isHyperlinkInstruction,
+  escapeFieldArgument,
 } from './FieldHelpers.js';
 import type { Revision } from './Revision.js';
 import { pointsToHalfPoints } from '../utils/units.js';
@@ -74,6 +75,15 @@ export interface FieldProperties {
   dirty?: boolean;
 }
 
+/**
+ * One run of a simple field's cached result: the text Word last computed
+ * for the field plus the run formatting it was displayed with.
+ */
+export interface CachedFieldResultRun {
+  text: string;
+  formatting?: RunFormatting;
+}
+
 /**
  * Represents a dynamic field
  */
@@ -83,6 +93,21 @@ export class Field {
   private formatting?: RunFormatting;
   private fldLock?: boolean;
   private dirty?: boolean;
+  /**
+   * Cached field result emitted as the fldSimple run text. For fields like
+   * HYPERLINK the visible text is NOT derivable from the instruction, so
+   * without this Word would display a generic placeholder until the user
+   * manually refreshes fields (F9).
+   */
+  private cachedResult?: string;
+  /**
+   * Per-run cached result parsed from a loaded `<w:fldSimple>`. Per
+   * ECMA-376 §17.16.16 CT_SimpleField, the child runs hold the field's
+   * current (cached) result — Word does not refresh fields on open by
+   * default, so discarding them replaces the user-visible text with a
+   * synthetic placeholder. Takes precedence over `cachedResult` in toXML().
+   */
+  private cachedResultRuns?: CachedFieldResultRun[];
 
   /**
    * Creates a new field
@@ -160,6 +185,36 @@ export class Field {
     return this.formatting;
   }
 
+  /**
+   * Sets the cached field result as plain text (single run; the field's
+   * own formatting applies). Clears any per-run cached result.
+   */
+  setCachedResult(text: string): this {
+    this.cachedResult = text;
+    this.cachedResultRuns = undefined;
+    return this;
+  }
+
+  /**
+   * Sets the cached field result as individual runs so per-run formatting
+   * from a parsed document survives round-trip.
+   */
+  setCachedResultRuns(runs: CachedFieldResultRun[]): this {
+    this.cachedResultRuns = runs.length > 0 ? [...runs] : undefined;
+    return this;
+  }
+
+  /**
+   * Gets the cached field result text (concatenated across runs), or
+   * undefined when the field has no cached result.
+   */
+  getCachedResult(): string | undefined {
+    if (this.cachedResultRuns) {
+      return this.cachedResultRuns.map((run) => run.text).join('');
+    }
+    return this.cachedResult;
+  }
+
   /**
    * Checks if this field is a HYPERLINK field
    * @returns True if the field type is HYPERLINK or instruction starts with HYPERLINK
@@ -190,21 +245,49 @@ export class Field {
    * The fldSimple element should be added directly to paragraph children (not wrapped in w:r).
    */
   toXML(): XMLElement {
-    // Build the inner run with optional formatting
-    const runChildren: XMLElement[] = [];
-    if (this.formatting) {
-      runChildren.push(this.createRunProperties());
+    let resultRuns: XMLElement[];
+    if (this.cachedResultRuns) {
+      // Re-emit the parsed cached result runs verbatim: per ECMA-376
+      // §17.16.16 they ARE the field's current result, and Word does not
+      // refresh fields on open by default — substituting a placeholder
+      // would corrupt the visible content. Field-level formatting (e.g.
+      // setColor after parse) is layered over each run's own formatting
+      // so programmatic styling still takes effect.
+      resultRuns = this.cachedResultRuns.map((cached) => {
+        const children: XMLElement[] = [];
+        const merged =
+          cached.formatting || this.formatting
+            ? { ...cached.formatting, ...this.formatting }
+            : undefined;
+        const rPr = merged ? Run.generateRunPropertiesXML(merged) : null;
+        if (rPr) {
+          children.push(rPr);
+        }
+        children.push({
+          name: 'w:t',
+          attributes: { 'xml:space': 'preserve' },
+          children: [cached.text],
+        });
+        return { name: 'w:r', children };
+      });
+    } else {
+      // Build the inner run with optional formatting
+      const runChildren: XMLElement[] = [];
+      if (this.formatting) {
+        runChildren.push(this.createRunProperties());
+      }
+      // Per ECMA-376 §22.1.2.33 CT_Text, `xml:space="preserve"` is the
+      // standard sentinel that stops XML processors from collapsing leading /
+      // trailing whitespace in the text content. Run.ts always emits it;
+      // emit it here too so field placeholders with spaces (e.g. localized
+      // date formats like "1 Jan 2026") survive XML round-trip intact.
+      runChildren.push({
+        name: 'w:t',
+        attributes: { 'xml:space': 'preserve' },
+        children: [this.cachedResult ?? this.getPlaceholderText()],
+      });
+      resultRuns = [{ name: 'w:r', children: runChildren }];
     }
-    // Per ECMA-376 §22.1.2.33 CT_Text, `xml:space="preserve"` is the
-    // standard sentinel that stops XML processors from collapsing leading /
-    // trailing whitespace in the text content. Run.ts always emits it;
-    // emit it here too so field placeholders with spaces (e.g. localized
-    // date formats like "1 Jan 2026") survive XML round-trip intact.
-    runChildren.push({
-      name: 'w:t',
-      attributes: { 'xml:space': 'preserve' },
-      children: [this.getPlaceholderText()],
-    });
 
     // CT_SimpleField (§17.16.16) carries two ST_OnOff attributes beyond
     // the required w:instr: w:fldLock (locked against updates) and
@@ -224,12 +307,7 @@ export class Field {
     return {
       name: 'w:fldSimple',
       attributes: fldSimpleAttrs,
-      children: [
-        {
-          name: 'w:r',
-          children: runChildren,
-        },
-      ],
+      children: resultRuns,
     };
   }
 
@@ -481,23 +559,25 @@ export class Field {
    */
   static createHyperlink(
     url: string,
-    _displayText: string = url,
+    displayText: string = url,
     tooltip?: string,
     formatting?: RunFormatting
   ): Field {
-    let instruction = `HYPERLINK "${url}"`;
+    let instruction = `HYPERLINK "${escapeFieldArgument(url)}"`;
 
     if (tooltip) {
-      instruction += ` \\o "${tooltip}"`;
+      instruction += ` \\o "${escapeFieldArgument(tooltip)}"`;
     }
 
     instruction += ' \\* MERGEFORMAT';
 
-    return new Field({
+    const field = new Field({
       type: 'HYPERLINK',
       instruction,
       formatting,
     });
+    field.cachedResult = displayText;
+    return field;
   }
 
   /**
@@ -535,7 +615,7 @@ export class Field {
       throw new Error('TC level must be between 1 and 9');
     }
 
-    const instruction = `TC "${text}" \\f C \\l ${level}`;
+    const instruction = `TC "${escapeFieldArgument(text)}" \\f C \\l ${level}`;
 
     return new Field({
       type: 'TC',
@@ -551,11 +631,12 @@ export class Field {
    * @param formatting Optional run formatting
    */
   static createXEEntry(text: string, subEntry?: string, formatting?: RunFormatting): Field {
-    let instruction = `XE "${text}"`;
-
-    if (subEntry) {
-      instruction += `:${subEntry}`;
-    }
+    // Per ECMA-376 §17.16.5.75 the main-entry/subentry colon separator
+    // belongs INSIDE the quoted field-argument ({ XE "Main:Sub" }) —
+    // text after the closing quote would be misparsed as stray switches.
+    const instruction = subEntry
+      ? `XE "${escapeFieldArgument(text)}:${escapeFieldArgument(subEntry)}"`
+      : `XE "${escapeFieldArgument(text)}"`;
 
     return new Field({
       type: 'XE',
@@ -571,7 +652,7 @@ export class Field {
    */
   static createCustom(instruction: string, formatting?: RunFormatting): Field {
     return new Field({
-      type: 'PAGE', // Placeholder type
+      type: 'CUSTOM',
       instruction,
       formatting,
     });
@@ -1120,17 +1201,27 @@ export class ComplexField {
       runs.push(...nestedField.toXML());
     }
 
-    // 3. Separator run
-    runs.push({
-      name: 'w:r',
-      children: [
-        {
-          name: 'w:fldChar',
-          attributes: { 'w:fldCharType': 'separate' },
-          selfClosing: true,
-        },
-      ],
-    });
+    // 3. Separator run — only when the field carries a result section.
+    // Per ECMA-376, fields without results (XE/TC markers, never-updated
+    // fields) skip w:fldSep entirely; synthesizing one would break
+    // round-trip fidelity for parsed separator-less fields.
+    const emitsResultSection =
+      this._hasResultSection ||
+      !!this.result ||
+      this.resultContent.length > 0 ||
+      this.resultRevisions.length > 0;
+    if (emitsResultSection) {
+      runs.push({
+        name: 'w:r',
+        children: [
+          {
+            name: 'w:fldChar',
+            attributes: { 'w:fldCharType': 'separate' },
+            selfClosing: true,
+          },
+        ],
+      });
+    }
 
     // 4. Result content (prioritize custom XML content, then simple text)
     // Design note: For INCLUDEPICTURE fields, the parser stores the w:drawing

package/src/elements/FieldHelpers.ts

@@ -133,6 +133,22 @@ export function parseHyperlinkInstruction(instruction: string): ParsedHyperlinkI
   };
 }
 
+/**
+ * Escapes a value for use inside a quoted field-instruction argument.
+ *
+ * Per ECMA-376 field-argument syntax (§17.16.4.1), a literal double quote
+ * inside a quoted argument must be written as \" and a literal backslash
+ * as \\ — otherwise an embedded quote terminates the argument early and
+ * the remainder is misparsed as stray switches. The XML layer only
+ * escapes XML entities, so this must happen at field-code level.
+ *
+ * @param value Raw argument text
+ * @returns Text safe to interpolate between double quotes in a field code
+ */
+export function escapeFieldArgument(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
 /**
  * Creates a HYPERLINK field instruction string from components
  *
@@ -148,14 +164,14 @@ export function parseHyperlinkInstruction(instruction: string): ParsedHyperlinkI
  * ```
  */
 export function buildHyperlinkInstruction(url: string, anchor?: string, tooltip?: string): string {
-  let instruction = `HYPERLINK "${url}"`;
+  let instruction = `HYPERLINK "${escapeFieldArgument(url)}"`;
 
   if (anchor) {
-    instruction += ` \\l "${anchor}"`;
+    instruction += ` \\l "${escapeFieldArgument(anchor)}"`;
   }
 
   if (tooltip) {
-    instruction += ` \\o "${tooltip}"`;
+    instruction += ` \\o "${escapeFieldArgument(tooltip)}"`;
   }
 
   // Always add \h switch for clickable hyperlinks
@@ -291,7 +307,7 @@ export function createIFField(
   trueContent: string,
   falseContent = ''
 ): ComplexField {
-  const instruction = ` IF ${condition} "${trueContent}" "${falseContent}" `;
+  const instruction = ` IF ${condition} "${escapeFieldArgument(trueContent)}" "${escapeFieldArgument(falseContent)}" `;
 
   return new ComplexField({
     instruction,

package/src/elements/Footer.ts

@@ -5,7 +5,8 @@
  * Different footers can be defined for first page, odd pages, and even pages.
  */
 
-import { XMLElement } from '../xml/XMLBuilder.js';
+import { XMLBuilder } from '../xml/XMLBuilder.js';
+import { XMLParser } from '../xml/XMLParser.js';
 import { Paragraph } from './Paragraph.js';
 import { RunFormatting } from './Run.js';
 import { Table } from './Table.js';
@@ -36,6 +37,12 @@ export class Footer {
   private type: FooterType;
   private footerId?: string;
   private rawXML?: string; // Store original XML for preservation
+  // Top-level w:p/w:tbl count of the preserved raw XML. DocumentParser calls
+  // setRawXML() before repopulating elements from that same XML, so mutators
+  // can't simply clear rawXML — they would fire during parsing and lose the
+  // preserved bytes. Instead, growth beyond this count is the signal that
+  // content was added after load and the preserved XML is stale.
+  private rawXmlBlockCount = Number.MAX_SAFE_INTEGER;
 
   /**
    * Creates a new footer
@@ -51,9 +58,43 @@ export class Footer {
    */
   setRawXML(xml: string): this {
     this.rawXML = xml;
+    this.rawXmlBlockCount = Footer.countTopLevelBlocks(xml);
     return this;
   }
 
+  /**
+   * Counts the top-level w:p/w:tbl children of a raw footer part.
+   * Parsing populates this.elements from exactly those blocks, so the count
+   * is the baseline against which mutators detect post-load additions.
+   */
+  private static countTopLevelBlocks(xml: string): number {
+    try {
+      const parsed = XMLParser.parseToObject(xml) as Record<string, unknown>;
+      const root = parsed?.['w:ftr'];
+      if (!root || typeof root !== 'object') {
+        return 0;
+      }
+      const count = (node: unknown): number =>
+        node === undefined ? 0 : Array.isArray(node) ? node.length : 1;
+      const rootObj = root as Record<string, unknown>;
+      return count(rootObj['w:p']) + count(rootObj['w:tbl']);
+    } catch {
+      // Unparseable part: never invalidate, keep the preserved bytes
+      return Number.MAX_SAFE_INTEGER;
+    }
+  }
+
+  /**
+   * Drops the preserved raw XML once content grows beyond what that XML
+   * already contains, so toXML() regenerates from elements and post-load
+   * edits are not silently discarded on save.
+   */
+  private invalidateRawXmlOnGrowth(): void {
+    if (this.rawXML !== undefined && this.elements.length > this.rawXmlBlockCount) {
+      this.rawXML = undefined;
+    }
+  }
+
   /**
    * Gets the raw XML content if available
    */
@@ -90,6 +131,7 @@ export class Footer {
    */
   addParagraph(paragraph: Paragraph): this {
     this.elements.push(paragraph);
+    this.invalidateRawXmlOnGrowth();
     return this;
   }
 
@@ -103,6 +145,7 @@ export class Footer {
       para.addText(text);
     }
     this.elements.push(para);
+    this.invalidateRawXmlOnGrowth();
     return para;
   }
 
@@ -125,6 +168,7 @@ export class Footer {
     const para = new Paragraph();
     para.addText(text, formatting);
     this.elements.push(para);
+    this.invalidateRawXmlOnGrowth();
     return para;
   }
 
@@ -134,6 +178,7 @@ export class Footer {
    */
   addTable(table: Table): this {
     this.elements.push(table);
+    this.invalidateRawXmlOnGrowth();
     return this;
   }
 
@@ -145,6 +190,7 @@ export class Footer {
   createTable(rows: number, columns: number): Table {
     const table = new Table(rows, columns);
     this.elements.push(table);
+    this.invalidateRawXmlOnGrowth();
     return table;
   }
 
@@ -181,76 +227,25 @@ export class Footer {
       return this.rawXML;
     }
 
-    // Otherwise generate from elements
-    const elementXmls = this.elements.map((el) => el.toXML());
-
-    let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
-    xml += '<w:ftr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" ';
-    xml += 'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">\n';
-
-    // Add elements
-    for (const element of elementXmls) {
-      xml += this.renderElement(element, 1);
-    }
+    // Serialize through XMLBuilder so text and attribute values are
+    // XML-escaped and rawXml passthrough children are honored
+    const children = this.elements.map((el) => el.toXML());
 
-    // If no elements, add an empty paragraph
-    if (this.elements.length === 0) {
-      xml += '  <w:p/>\n';
+    // ECMA-376 requires block-level content in w:ftr
+    if (children.length === 0) {
+      children.push(XMLBuilder.w('p'));
     }
 
-    xml += '</w:ftr>';
-
-    return xml;
-  }
-
-  /**
-   * Renders an XML element to string with indentation
-   */
-  private renderElement(element: XMLElement, indent: number): string {
-    const spaces = '  '.repeat(indent);
-    let xml = '';
-
-    if (element.selfClosing) {
-      xml += `${spaces}<${element.name}`;
-      if (element.attributes) {
-        for (const [key, value] of Object.entries(element.attributes)) {
-          xml += ` ${key}="${value}"`;
-        }
-      }
-      xml += '/>\n';
-    } else {
-      xml += `${spaces}<${element.name}`;
-      if (element.attributes) {
-        for (const [key, value] of Object.entries(element.attributes)) {
-          xml += ` ${key}="${value}"`;
-        }
-      }
-      xml += '>';
-
-      if (element.children && element.children.length > 0) {
-        const hasOnlyText = element.children.every((c) => typeof c === 'string');
-
-        if (hasOnlyText) {
-          // Inline text content
-          xml += element.children.join('');
-        } else {
-          // Block-level children
-          xml += '\n';
-          for (const child of element.children) {
-            if (typeof child === 'string') {
-              xml += spaces + '  ' + child + '\n';
-            } else {
-              xml += this.renderElement(child, indent + 1);
-            }
-          }
-          xml += spaces;
-        }
-      }
-
-      xml += `</${element.name}>\n`;
-    }
+    const namespaces: Record<string, string> = {
+      ...XMLBuilder.createNamespaces(),
+      // Extension namespaces (w14:paraId etc. on regenerated paragraphs)
+      // must be declared ignorable or Word rejects the part
+      'mc:Ignorable': 'w14 w15 wp14 asvg',
+    };
 
-    return xml;
+    const builder = new XMLBuilder();
+    builder.element('w:ftr', namespaces, children);
+    return builder.build(true);
   }
 
   /**

package/src/elements/FootnoteManager.ts

@@ -130,7 +130,10 @@ export class FootnoteManager {
   }
 
   /**
-   * Removes a footnote
+   * Removes a footnote from the model only. Does not touch body
+   * w:footnoteReference runs or the document's dirty flags — callers going
+   * through a Document should use Document.removeFootnote(), which also
+   * strips the matching references and forces footnotes.xml regeneration.
    * @param id Footnote ID
    * @returns True if removed, false if not found or if it's a special type
    */