docxmlater 10.4.0 → 11.0.4

package/src/core/DocumentContent.ts

@@ -5,18 +5,20 @@
  * Extracted from Document.ts for better separation of concerns.
  */
 
-import { Paragraph } from '../elements/Paragraph';
-import { Table } from '../elements/Table';
-import { Section } from '../elements/Section';
-import { StructuredDocumentTag } from '../elements/StructuredDocumentTag';
-import { TableOfContentsElement } from '../elements/TableOfContentsElement';
-import { AlternateContent } from '../elements/AlternateContent';
-import { MathParagraph } from '../elements/MathElement';
-import { CustomXmlBlock } from '../elements/CustomXml';
-import { PreservedElement } from '../elements/PreservedElement';
+import { Paragraph } from '../elements/Paragraph.js';
+import { Table } from '../elements/Table.js';
+import { Section } from '../elements/Section.js';
+import { StructuredDocumentTag } from '../elements/StructuredDocumentTag.js';
+import { TableOfContentsElement } from '../elements/TableOfContentsElement.js';
+import { AlternateContent } from '../elements/AlternateContent.js';
+import { MathParagraph } from '../elements/MathElement.js';
+import { CustomXmlBlock } from '../elements/CustomXml.js';
+import { PreservedElement } from '../elements/PreservedElement.js';
+import { RegisteredBodyElement } from '../elements/RegisteredBodyElement.js';
 
 /**
- * Body element type - can be a Paragraph, Table, TOC, SDT, or raw XML preservation element
+ * Body element type — Paragraph, Table, TOC, SDT, raw passthrough, or
+ * a consumer-defined element produced by `ElementRegistry`.
  */
 export type BodyElement =
   | Paragraph
@@ -26,7 +28,8 @@ export type BodyElement =
   | AlternateContent
   | MathParagraph
   | CustomXmlBlock
-  | PreservedElement;
+  | PreservedElement
+  | RegisteredBodyElement;
 
 /**
  * Manages document content (paragraphs, tables, sections)

package/src/core/DocumentEvents.ts

@@ -0,0 +1,90 @@
+/**
+ * Lightweight event system for Document lifecycle and content mutations.
+ *
+ * Designed for batch pipelines that need to react to programmatic edits
+ * (e.g., audit-logging every `paragraphAdded`). Listeners are synchronous;
+ * thrown errors are caught and logged via the global logger so a bad
+ * listener cannot abort `save()` or corrupt document state.
+ *
+ * `beforeSave` fires inside the save lock; `afterSave` and `afterLoad`
+ * fire only after success. Mutation events fire synchronously after the
+ * mutation is applied. Pure structural moves (moveElement) and
+ * load/parse-time construction do not fire mutation events.
+ */
+import type { Paragraph } from '../elements/Paragraph.js';
+import type { Table } from '../elements/Table.js';
+import { getGlobalLogger } from '../utils/logger.js';
+
+export interface DocumentEventMap {
+  /** Fired after a paragraph is added to the document body. */
+  paragraphAdded: { paragraph: Paragraph; index?: number };
+  /** Fired after a paragraph is removed from the document body. */
+  paragraphRemoved: { paragraph: Paragraph };
+  /** Fired after a table is added to the document body. */
+  tableAdded: { table: Table };
+  /** Fired after a table is removed from the document body. */
+  tableRemoved: { table: Table };
+  /** Fired immediately before save() / toBuffer() begins generation. */
+  beforeSave: { filePath?: string };
+  /** Fired immediately after save() / toBuffer() completes successfully. */
+  afterSave: { filePath?: string; bufferSize?: number };
+  /** Fired immediately after a load() / loadFromBuffer() completes. */
+  afterLoad: { source: 'file' | 'buffer'; path?: string };
+}
+
+export type DocumentEventType = keyof DocumentEventMap;
+
+export type DocumentEventListener<T extends DocumentEventType> = (
+  payload: DocumentEventMap[T]
+) => void;
+
+/**
+ * Internal emitter implementation. Stored on each Document instance.
+ */
+export class DocumentEventEmitter {
+  private listeners = new Map<DocumentEventType, Set<DocumentEventListener<DocumentEventType>>>();
+
+  on<T extends DocumentEventType>(event: T, listener: DocumentEventListener<T>): () => void {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(listener as DocumentEventListener<DocumentEventType>);
+    return () => this.off(event, listener);
+  }
+
+  off<T extends DocumentEventType>(event: T, listener: DocumentEventListener<T>): void {
+    const set = this.listeners.get(event);
+    if (set) {
+      set.delete(listener as DocumentEventListener<DocumentEventType>);
+    }
+  }
+
+  emit<T extends DocumentEventType>(event: T, payload: DocumentEventMap[T]): void {
+    const set = this.listeners.get(event);
+    if (!set || set.size === 0) return;
+    for (const listener of set) {
+      try {
+        (listener as DocumentEventListener<T>)(payload);
+      } catch (err) {
+        getGlobalLogger().warn('Document event listener threw', {
+          event,
+          error: String(err),
+        });
+      }
+    }
+  }
+
+  removeAllListeners(event?: DocumentEventType): void {
+    if (event) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+  }
+
+  listenerCount(event: DocumentEventType): number {
+    return this.listeners.get(event)?.size ?? 0;
+  }
+}

package/src/core/DocumentGenerator.ts

@@ -3,27 +3,27 @@
  * Converts structured data to OpenXML format
  */
 
-import { CommentManager } from '../elements/CommentManager';
-import { EndnoteManager } from '../elements/EndnoteManager';
-import { FontManager } from '../elements/FontManager';
-import { FootnoteManager } from '../elements/FootnoteManager';
-import { HeaderFooterManager } from '../elements/HeaderFooterManager';
-import { Hyperlink } from '../elements/Hyperlink';
-import { ImageManager } from '../elements/ImageManager';
-import { Paragraph } from '../elements/Paragraph';
-import { Revision } from '../elements/Revision';
-import { isHyperlinkContent } from '../elements/RevisionContent';
-import { Section } from '../elements/Section';
-import { StructuredDocumentTag } from '../elements/StructuredDocumentTag';
-import { Table } from '../elements/Table';
-import { PreservedElement } from '../elements/PreservedElement';
-import { formatDateForXml } from '../utils/dateFormatting';
-import { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger';
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
-import { DocumentProperties } from './Document';
-import { BodyElement } from './DocumentContent';
-import { RelationshipManager } from './RelationshipManager';
-import { TrackChangesSettings } from '../types/settings-types';
+import { CommentManager } from '../elements/CommentManager.js';
+import { EndnoteManager } from '../elements/EndnoteManager.js';
+import { FontManager } from '../elements/FontManager.js';
+import { FootnoteManager } from '../elements/FootnoteManager.js';
+import { HeaderFooterManager } from '../elements/HeaderFooterManager.js';
+import { Hyperlink } from '../elements/Hyperlink.js';
+import { ImageManager } from '../elements/ImageManager.js';
+import { Paragraph } from '../elements/Paragraph.js';
+import { Revision } from '../elements/Revision.js';
+import { isHyperlinkContent } from '../elements/RevisionContent.js';
+import { Section } from '../elements/Section.js';
+import { StructuredDocumentTag } from '../elements/StructuredDocumentTag.js';
+import { Table } from '../elements/Table.js';
+import { PreservedElement } from '../elements/PreservedElement.js';
+import { formatDateForXml } from '../utils/dateFormatting.js';
+import { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger.js';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder.js';
+import type { DocumentProperties } from '../types/document-types.js';
+import { BodyElement } from './DocumentContent.js';
+import { RelationshipManager } from './RelationshipManager.js';
+import { TrackChangesSettings } from '../types/settings-types.js';
 
 // Create scoped logger for DocumentGenerator operations
 function getLogger(): ILogger {
@@ -964,12 +964,24 @@ ${properties}
       if (
         !view.showInsertionsAndDeletions ||
         !view.showFormatting ||
-        view.showInkAnnotations === false
+        view.showInkAnnotations === false ||
+        view.showMarkup === false ||
+        view.showComments === false
       ) {
         xml += `\n  <w:revisionView w:insDel="${view.showInsertionsAndDeletions ? '1' : '0'}" w:formatting="${view.showFormatting ? '1' : '0'}"`;
         if (view.showInkAnnotations !== undefined) {
           xml += ` w:inkAnnotations="${view.showInkAnnotations ? '1' : '0'}"`;
         }
+        // CT_TrackChangesView §17.15.1.77: w:markup and w:comments control
+        // whether revision markup / comment balloons are visible. Emit
+        // when the field is set so the reviewer's default markup view
+        // survives round-trip.
+        if (view.showMarkup !== undefined) {
+          xml += ` w:markup="${view.showMarkup ? '1' : '0'}"`;
+        }
+        if (view.showComments !== undefined) {
+          xml += ` w:comments="${view.showComments ? '1' : '0'}"`;
+        }
         xml += '/>';
       }
     }
@@ -989,6 +1001,11 @@ ${properties}
     if (trackChangesSettings?.documentProtection) {
       const prot = trackChangesSettings.documentProtection;
       xml += `\n  <w:documentProtection w:edit="${prot.edit}" w:enforcement="${prot.enforcement ? '1' : '0'}"`;
+      // Emit w:formatting (CT_DocProtect §17.15.1.29) — allows formatting
+      // changes under edit protection, commonly paired with tracked edits.
+      if (prot.formatting !== undefined) {
+        xml += ` w:formatting="${prot.formatting ? '1' : '0'}"`;
+      }
       if (prot.cryptProviderType) {
         xml += ` w:cryptProviderType="${prot.cryptProviderType}"`;
       }
@@ -1010,6 +1027,16 @@ ${properties}
       if (prot.salt) {
         xml += ` w:salt="${prot.salt}"`;
       }
+      // Modern Word 2013+ crypto attributes (ISO/IEC 29500-4 §13).
+      if (prot.algorithmName) {
+        xml += ` w:algorithmName="${prot.algorithmName}"`;
+      }
+      if (prot.hashValue) {
+        xml += ` w:hashValue="${prot.hashValue}"`;
+      }
+      if (prot.saltValue) {
+        xml += ` w:saltValue="${prot.saltValue}"`;
+      }
       xml += '/>';
     }