docxmlater 11.0.10 → 12.1.0

package/src/elements/Comment.ts

@@ -9,6 +9,34 @@ import { Run } from './Run.js';
 import { XMLElement } from '../xml/XMLBuilder.js';
 import { formatDateForXml } from '../utils/dateFormatting.js';
 
+/**
+ * Inline comment content preserved as raw XML (e.g. w:hyperlink wrappers
+ * from a parsed comments.xml). The wrapper is re-emitted verbatim on
+ * regeneration so its r:id target survives; the runs parsed from inside
+ * it are kept alongside so text extraction still sees their text.
+ */
+export interface CommentPreservedContent {
+  /** Original XML emitted verbatim when comments.xml is regenerated */
+  rawXml: string;
+  /** Runs parsed from inside the preserved element (text extraction only) */
+  runs: Run[];
+}
+
+/** Ordered item of comment paragraph content */
+export type CommentContentItem = Run | CommentPreservedContent;
+
+/**
+ * One paragraph of comment content. CT_Comment accepts block-level content
+ * (ECMA-376 §17.13.4.2), so comments can span multiple paragraphs, each
+ * with its own paragraph properties (typically the CommentText style).
+ */
+export interface CommentParagraph {
+  /** Raw <w:pPr> XML preserved for round-trip */
+  pPr?: string;
+  /** Paragraph content in document order */
+  content: CommentContentItem[];
+}
+
 /**
  * Comment properties
  */
@@ -37,9 +65,10 @@ export class Comment {
   private author: string;
   private initials: string;
   private date: Date;
-  private runs: Run[];
+  private paragraphs: CommentParagraph[];
   private parentId?: number;
   private done: boolean;
+  private onModified: (() => void) | null = null;
 
   /**
    * Creates a new Comment
@@ -53,14 +82,16 @@ export class Comment {
     this.parentId = properties.parentId;
     this.done = properties.done ?? false;
 
-    // Convert content to runs
+    // Convert content to runs in a single paragraph
+    let runs: Run[];
     if (typeof properties.content === 'string') {
-      this.runs = [new Run(properties.content)];
+      runs = [new Run(properties.content)];
     } else if (Array.isArray(properties.content)) {
-      this.runs = properties.content;
+      runs = properties.content;
     } else {
-      this.runs = [properties.content];
+      runs = [properties.content];
     }
+    this.paragraphs = [{ content: runs }];
   }
 
   /**
@@ -98,6 +129,23 @@ export class Comment {
     this.id = id;
   }
 
+  /**
+   * Registers a callback invoked whenever this comment is mutated.
+   * Document wires this to its comments dirty flag so edits to parsed
+   * comments trigger regeneration of comments.xml instead of being
+   * silently discarded by the original-XML passthrough on save.
+   * @internal
+   */
+  setModifiedCallback(callback: () => void): void {
+    this.onModified = callback;
+  }
+
+  private notifyModified(): void {
+    if (this.onModified) {
+      this.onModified();
+    }
+  }
+
   /**
    * Gets the author
    */
@@ -110,6 +158,7 @@ export class Comment {
    */
   setAuthor(author: string): this {
     this.author = author;
+    this.notifyModified();
     return this;
   }
 
@@ -125,6 +174,7 @@ export class Comment {
    */
   setInitials(initials: string): this {
     this.initials = initials;
+    this.notifyModified();
     return this;
   }
 
@@ -140,6 +190,7 @@ export class Comment {
    */
   setDate(date: Date): this {
     this.date = date;
+    this.notifyModified();
     return this;
   }
 
@@ -167,42 +218,84 @@ export class Comment {
 
   /**
    * Marks the comment as resolved/done
-   * Sets w:done="1" in the XML output
+   * Persists as w15:done="1" in word/commentsExtended.xml on save
    */
   resolve(): this {
     this.done = true;
+    this.notifyModified();
     return this;
   }
 
   /**
    * Marks the comment as unresolved
-   * Removes w:done attribute from XML output
+   * Drops the w15:done flag from word/commentsExtended.xml on save
    */
   unresolve(): this {
     this.done = false;
+    this.notifyModified();
     return this;
   }
 
   /**
-   * Gets the runs in this comment
+   * Gets the runs in this comment (flattened across paragraphs,
+   * including runs inside preserved inline content)
    */
   getRuns(): Run[] {
-    return [...this.runs];
+    const runs: Run[] = [];
+    for (const paragraph of this.paragraphs) {
+      for (const item of paragraph.content) {
+        if (item instanceof Run) {
+          runs.push(item);
+        } else {
+          runs.push(...item.runs);
+        }
+      }
+    }
+    return runs;
   }
 
   /**
-   * Adds a run to this comment
+   * Adds a run to this comment (appended to the last paragraph)
    */
   addRun(run: Run): this {
-    this.runs.push(run);
+    let last = this.paragraphs[this.paragraphs.length - 1];
+    if (!last) {
+      last = { content: [] };
+      this.paragraphs.push(last);
+    }
+    last.content.push(run);
+    this.notifyModified();
     return this;
   }
 
+  /**
+   * Gets the comment content grouped by paragraph
+   */
+  getParagraphs(): CommentParagraph[] {
+    return this.paragraphs.map((paragraph) => ({
+      pPr: paragraph.pPr,
+      content: [...paragraph.content],
+    }));
+  }
+
+  /**
+   * Replaces the comment content with parsed paragraphs.
+   * Used by DocumentParser to preserve <w:p> boundaries, paragraph
+   * properties, and hyperlink wrappers of comments loaded from an
+   * existing comments.xml. Not a user mutation — no dirty notification.
+   * @internal
+   */
+  setParagraphs(paragraphs: CommentParagraph[]): void {
+    this.paragraphs = paragraphs;
+  }
+
   /**
    * Gets the comment text (combines all runs)
    */
   getText(): string {
-    return this.runs.map((run) => run.getText()).join('');
+    return this.getRuns()
+      .map((run) => run.getText())
+      .join('');
   }
 
   /**
@@ -289,16 +382,28 @@ export class Comment {
       attributes['w:done'] = '1';
     }
 
-    // Create paragraph containing the comment content
-    const commentParagraph: XMLElement = {
-      name: 'w:p',
-      children: this.runs.map((run) => run.toXML()),
-    };
+    // One <w:p> per stored paragraph — collapsing into a single paragraph
+    // concatenates words across the lost boundaries and drops the
+    // CommentText paragraph style of parsed comments
+    const commentParagraphs: XMLElement[] = this.paragraphs.map((paragraph) => {
+      const children: XMLElement[] = [];
+      if (paragraph.pPr) {
+        children.push({ name: '__rawXml', rawXml: paragraph.pPr });
+      }
+      for (const item of paragraph.content) {
+        if (item instanceof Run) {
+          children.push(item.toXML());
+        } else {
+          children.push({ name: '__rawXml', rawXml: item.rawXml });
+        }
+      }
+      return { name: 'w:p', children };
+    });
 
     return {
       name: 'w:comment',
       attributes,
-      children: [commentParagraph],
+      children: commentParagraphs,
     };
   }
 

package/src/elements/CommentManager.ts

@@ -42,6 +42,7 @@ export class CommentManager {
   private nextId = 0;
   private idProvider: IdProviderCallback | null = null;
   private idExistsNotifier: IdExistsCallback | null = null;
+  private modifiedNotifier: (() => void) | null = null;
 
   /**
    * Sets the centralized ID provider callback.
@@ -56,6 +57,21 @@ export class CommentManager {
     this.idExistsNotifier = existsNotifier || null;
   }
 
+  /**
+   * Sets the callback invoked when a registered comment is mutated.
+   * Document wires this to its comments dirty flag so instance-level edits
+   * (resolve, setAuthor, addRun, ...) force comments.xml regeneration
+   * instead of being silently discarded by the original-XML passthrough.
+   *
+   * @param notifier - Callback invoked on any comment mutation
+   */
+  setModifiedNotifier(notifier: () => void): void {
+    this.modifiedNotifier = notifier;
+    for (const entry of this.comments.values()) {
+      entry.comment.setModifiedCallback(notifier);
+    }
+  }
+
   /**
    * Registers a comment with the manager
    * Assigns a unique ID
@@ -67,6 +83,10 @@ export class CommentManager {
     const id = this.idProvider ? this.idProvider() : this.nextId++;
     comment.setId(id);
 
+    if (this.modifiedNotifier) {
+      comment.setModifiedCallback(this.modifiedNotifier);
+    }
+
     // Store comment
     const entry: CommentEntry = {
       comment,
@@ -99,6 +119,10 @@ export class CommentManager {
       this.idExistsNotifier(id);
     }
 
+    if (this.modifiedNotifier) {
+      comment.setModifiedCallback(this.modifiedNotifier);
+    }
+
     // Store comment
     const entry: CommentEntry = {
       comment,
@@ -251,6 +275,16 @@ export class CommentManager {
       this.comments.delete(reply.getId());
     }
 
+    // A reply is also tracked in its parent's replies array — drop it there
+    // too so getReplies()/hasReplies()/getCommentThread() agree with the map
+    const parentId = entry.comment.getParentId();
+    if (parentId !== undefined) {
+      const parentEntry = this.comments.get(parentId);
+      if (parentEntry) {
+        parentEntry.replies = parentEntry.replies.filter((reply) => reply !== entry.comment);
+      }
+    }
+
     // Remove the comment itself
     return this.comments.delete(id);
   }
@@ -420,31 +454,88 @@ export class CommentManager {
 
     // Build XML manually for comments
     const hasReplies = comments.some((c) => c.isReply());
+    const hasResolved = comments.some((c) => c.isResolved());
     let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
     xml += '<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"';
     xml += ' xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"';
+    if (hasResolved) {
+      xml += ' xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml"';
+    }
     if (hasReplies) {
       xml += ' xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"';
-      xml +=
-        ' xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="w15"';
+    }
+    if (hasReplies || hasResolved) {
+      const ignorable = [hasResolved ? 'w14' : '', hasReplies ? 'w15' : '']
+        .filter((ns) => ns.length > 0)
+        .join(' ');
+      xml += ` xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="${ignorable}"`;
     }
     xml += '>\n';
 
-    // Add each comment
+    // Add each comment. CT_Comment declares no resolved-state attribute —
+    // that lives in commentsExtended.xml keyed by the w14:paraId of each
+    // comment's last paragraph, so emit those anchors when any comment is
+    // resolved (see generateCommentsExtendedXml)
     for (const comment of comments) {
-      xml += this.commentToXmlString(comment);
+      xml += this.commentToXmlString(
+        comment,
+        hasResolved ? CommentManager.commentParaId(comment.getId()) : undefined
+      );
     }
 
     xml += '</w:comments>';
     return xml;
   }
 
+  /**
+   * Derives the w14:paraId anchor for a comment's last paragraph.
+   * Deterministic so comments.xml and commentsExtended.xml agree without
+   * shared state. Values must be 8 hex digits, nonzero, and below
+   * 0x80000000 per ST_LongHexNumber conventions for paraId.
+   * @param commentId - Comment ID
+   * @returns 8-character uppercase hex paraId
+   */
+  static commentParaId(commentId: number): string {
+    return ((commentId + 1) & 0x7fffffff).toString(16).toUpperCase().padStart(8, '0');
+  }
+
+  /**
+   * Generates the word/commentsExtended.xml content carrying resolved
+   * state (w15:done) and reply threading (w15:paraIdParent).
+   * @returns XML string, or null when no comment is resolved (the part is
+   *   only regenerated when it carries information)
+   */
+  generateCommentsExtendedXml(): string | null {
+    const comments = this.getAllCommentsWithReplies();
+    if (!comments.some((c) => c.isResolved())) {
+      return null;
+    }
+
+    let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+    xml += '<w15:commentsEx xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"';
+    xml +=
+      ' xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" mc:Ignorable="w15">\n';
+    for (const comment of comments) {
+      xml += `  <w15:commentEx w15:paraId="${CommentManager.commentParaId(comment.getId())}"`;
+      const parentId = comment.getParentId();
+      if (parentId !== undefined && this.comments.has(parentId)) {
+        xml += ` w15:paraIdParent="${CommentManager.commentParaId(parentId)}"`;
+      }
+      xml += ` w15:done="${comment.isResolved() ? '1' : '0'}"/>\n`;
+    }
+    xml += '</w15:commentsEx>';
+    return xml;
+  }
+
   /**
    * Converts a comment to XML string
    * @param comment - Comment to convert
+   * @param paraId - w14:paraId to anchor on the last paragraph (links the
+   *   comment to its commentsExtended.xml entry), omitted when no comment
+   *   in the document is resolved
    * @returns XML string for the comment
    */
-  private commentToXmlString(comment: Comment): string {
+  private commentToXmlString(comment: Comment, paraId?: string): string {
     let xml = `  <w:comment w:id="${comment.getId()}"`;
     xml += ` w:author="${XMLBuilder.escapeXmlAttribute(comment.getAuthor())}"`;
     xml += ` w:date="${formatDateForXml(comment.getDate())}"`;
@@ -454,19 +545,31 @@ export class CommentManager {
       xml += ` w15:parentId="${comment.getParentId()}"`;
     }
 
-    // Add done attribute for resolved comments (per ECMA-376)
-    if (comment.isResolved()) {
-      xml += ` w:done="1"`;
-    }
-
     xml += '>\n';
 
-    // Add paragraph with runs
-    xml += '    <w:p>\n';
-    for (const run of comment.getRuns()) {
-      xml += this.runToXmlString(run, 6);
+    // One <w:p> per stored paragraph — collapsing into a single paragraph
+    // concatenates words across the lost boundaries and drops paragraph
+    // properties (CommentText pStyle) of parsed comments
+    const paragraphs = comment.getParagraphs();
+    for (let i = 0; i < paragraphs.length; i++) {
+      const paragraph = paragraphs[i]!;
+      // commentsExtended.xml entries reference the LAST paragraph's paraId
+      const isLast = i === paragraphs.length - 1;
+      xml += isLast && paraId ? `    <w:p w14:paraId="${paraId}">\n` : '    <w:p>\n';
+      if (paragraph.pPr) {
+        xml += `      ${paragraph.pPr}\n`;
+      }
+      for (const item of paragraph.content) {
+        if (item instanceof Run) {
+          xml += this.runToXmlString(item, 6);
+        } else {
+          // Preserved inline XML (e.g. w:hyperlink) re-emitted verbatim so
+          // its r:id target keeps pointing at word/_rels/comments.xml.rels
+          xml += `      ${item.rawXml}\n`;
+        }
+      }
+      xml += '    </w:p>\n';
     }
-    xml += '    </w:p>\n';
 
     xml += '  </w:comment>\n';
     return xml;
@@ -480,13 +583,9 @@ export class CommentManager {
    */
   private runToXmlString(run: Run, indent: number): string {
     const spaces = ' '.repeat(indent);
-    const text = XMLBuilder.escapeXmlText(run.getText());
-
-    let xml = `${spaces}<w:r>\n`;
-    xml += `${spaces}  <w:t xml:space="preserve">${text}</w:t>\n`;
-    xml += `${spaces}</w:r>\n`;
-
-    return xml;
+    // Serialize through Run.toXML() so w:rPr formatting and non-text
+    // content (w:annotationRef, tabs, breaks) survive regeneration
+    return `${spaces}${XMLBuilder.elementToString(run.toXML())}\n`;
   }
 
   /**

package/src/elements/EndnoteManager.ts

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