docxmlater 11.0.10 → 12.1.0

package/src/elements/Header.ts

@@ -5,7 +5,8 @@
  * Different headers 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 Header {
   private type: HeaderType;
   private headerId?: 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 header
@@ -51,9 +58,43 @@ export class Header {
    */
   setRawXML(xml: string): this {
     this.rawXML = xml;
+    this.rawXmlBlockCount = Header.countTopLevelBlocks(xml);
     return this;
   }
 
+  /**
+   * Counts the top-level w:p/w:tbl children of a raw header 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:hdr'];
+      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 Header {
    */
   addParagraph(paragraph: Paragraph): this {
     this.elements.push(paragraph);
+    this.invalidateRawXmlOnGrowth();
     return this;
   }
 
@@ -103,6 +145,7 @@ export class Header {
       para.addText(text);
     }
     this.elements.push(para);
+    this.invalidateRawXmlOnGrowth();
     return para;
   }
 
@@ -127,6 +170,7 @@ export class Header {
     const para = new Paragraph();
     para.addText(text, formatting);
     this.elements.push(para);
+    this.invalidateRawXmlOnGrowth();
     return para;
   }
 
@@ -136,6 +180,7 @@ export class Header {
    */
   addTable(table: Table): this {
     this.elements.push(table);
+    this.invalidateRawXmlOnGrowth();
     return this;
   }
 
@@ -147,6 +192,7 @@ export class Header {
   createTable(rows: number, columns: number): Table {
     const table = new Table(rows, columns);
     this.elements.push(table);
+    this.invalidateRawXmlOnGrowth();
     return table;
   }
 
@@ -183,76 +229,25 @@ export class Header {
       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:hdr 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:hdr
+    if (children.length === 0) {
+      children.push(XMLBuilder.w('p'));
     }
 
-    xml += '</w:hdr>';
-
-    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:hdr', namespaces, children);
+    return builder.build(true);
   }
 
   /**

package/src/elements/HeaderFooterManager.ts

@@ -51,18 +51,31 @@ export class HeaderFooterManager {
    * Registers a header with the manager
    * @param header The header to register
    * @param relationshipId The relationship ID for this header
+   * @param originalFilename Part name from the relationship target for loaded
+   *   headers — kept as-is so saved content lands where the relationship points
    * @returns The filename assigned to this header
    */
-  registerHeader(header: Header, relationshipId: string): string {
+  registerHeader(header: Header, relationshipId: string, originalFilename?: string): string {
     // Check if already registered
     const existing = this.headers.get(header);
     if (existing) {
       return existing.filename;
     }
 
-    // Generate filename
-    const number = this.nextHeaderNumber++;
-    const filename = header.getFilename(number);
+    let number: number;
+    let filename: string;
+    if (originalFilename) {
+      filename = originalFilename;
+      const digits = /(\d+)\.xml$/i.exec(originalFilename)?.[1];
+      number = digits ? parseInt(digits, 10) : this.nextHeaderNumber;
+      // Keep the counter ahead of parsed part names so generated names never collide
+      if (number >= this.nextHeaderNumber) {
+        this.nextHeaderNumber = number + 1;
+      }
+    } else {
+      number = this.nextHeaderNumber++;
+      filename = header.getFilename(number);
+    }
 
     // Set header ID
     header.setHeaderId(relationshipId);
@@ -84,18 +97,31 @@ export class HeaderFooterManager {
    * Registers a footer with the manager
    * @param footer The footer to register
    * @param relationshipId The relationship ID for this footer
+   * @param originalFilename Part name from the relationship target for loaded
+   *   footers — kept as-is so saved content lands where the relationship points
    * @returns The filename assigned to this footer
    */
-  registerFooter(footer: Footer, relationshipId: string): string {
+  registerFooter(footer: Footer, relationshipId: string, originalFilename?: string): string {
     // Check if already registered
     const existing = this.footers.get(footer);
     if (existing) {
       return existing.filename;
     }
 
-    // Generate filename
-    const number = this.nextFooterNumber++;
-    const filename = footer.getFilename(number);
+    let number: number;
+    let filename: string;
+    if (originalFilename) {
+      filename = originalFilename;
+      const digits = /(\d+)\.xml$/i.exec(originalFilename)?.[1];
+      number = digits ? parseInt(digits, 10) : this.nextFooterNumber;
+      // Keep the counter ahead of parsed part names so generated names never collide
+      if (number >= this.nextFooterNumber) {
+        this.nextFooterNumber = number + 1;
+      }
+    } else {
+      number = this.nextFooterNumber++;
+      filename = footer.getFilename(number);
+    }
 
     // Set footer ID
     footer.setFooterId(relationshipId);
@@ -113,6 +139,28 @@ export class HeaderFooterManager {
     return filename;
   }
 
+  /**
+   * Returns the part filename this header has, or would receive when
+   * registered. Does not consume a sequence number — callers can create the
+   * relationship targeting the same part name registerHeader() will assign.
+   * @param header The header
+   * @returns The current or upcoming filename
+   */
+  peekHeaderFilename(header: Header): string {
+    return this.headers.get(header)?.filename ?? header.getFilename(this.nextHeaderNumber);
+  }
+
+  /**
+   * Returns the part filename this footer has, or would receive when
+   * registered. Does not consume a sequence number — callers can create the
+   * relationship targeting the same part name registerFooter() will assign.
+   * @param footer The footer
+   * @returns The current or upcoming filename
+   */
+  peekFooterFilename(footer: Footer): string {
+    return this.footers.get(footer)?.filename ?? footer.getFilename(this.nextFooterNumber);
+  }
+
   /**
    * Gets the filename for a header
    * @param header The header