docxmlater 10.4.0 → 11.0.4

package/src/elements/RangeMarker.ts

@@ -5,8 +5,8 @@
  * They enable Word to properly display and manage complex revision regions.
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
-import { formatDateForXml } from '../utils/dateFormatting';
+import { XMLElement } from '../xml/XMLBuilder.js';
+import { formatDateForXml } from '../utils/dateFormatting.js';
 
 /**
  * Range marker type
@@ -25,6 +25,13 @@ export type RangeMarkerType =
   | 'customXmlDelRangeStart'
   | 'customXmlDelRangeEnd';
 
+/**
+ * `w:displacedByCustomXml` attribute value per ECMA-376 §17.13.5 — ST_DisplacedByCustomXml.
+ * Indicates which side of a custom-XML boundary a displaced range marker
+ * semantically belongs to.
+ */
+export type DisplacedByCustomXml = 'next' | 'prev';
+
 /**
  * Range marker properties
  */
@@ -39,6 +46,26 @@ export interface RangeMarkerProperties {
   author?: string;
   /** Date when the change was made (for start markers only) */
   date?: Date;
+  /**
+   * `w:displacedByCustomXml` per ECMA-376 CT_MarkupRange / CT_MoveBookmark.
+   * Only valid on moveFromRangeStart, moveToRangeStart, moveFromRangeEnd,
+   * and moveToRangeEnd (the CT_MarkupRange-derived marker types).
+   * Ignored on serialize for other types. "next" / "prev".
+   */
+  displacedByCustomXml?: DisplacedByCustomXml;
+  /**
+   * `w:colFirst` per ECMA-376 CT_BookmarkRange — first column index for
+   * table-column-scoped moves. Only valid on moveFromRangeStart /
+   * moveToRangeStart (CT_MoveBookmark-derived). Ignored on serialize for
+   * other types. 0-based, inclusive.
+   */
+  colFirst?: number;
+  /**
+   * `w:colLast` per ECMA-376 CT_BookmarkRange — last column index for
+   * table-column-scoped moves. Only valid on moveFromRangeStart /
+   * moveToRangeStart. 0-based, inclusive.
+   */
+  colLast?: number;
 }
 
 /**
@@ -51,6 +78,9 @@ export class RangeMarker {
   private name?: string;
   private author?: string;
   private date?: Date;
+  private displacedByCustomXml?: DisplacedByCustomXml;
+  private colFirst?: number;
+  private colLast?: number;
 
   /**
    * Creates a new RangeMarker
@@ -62,6 +92,9 @@ export class RangeMarker {
     this.name = properties.name;
     this.author = properties.author;
     this.date = properties.date;
+    this.displacedByCustomXml = properties.displacedByCustomXml;
+    this.colFirst = properties.colFirst;
+    this.colLast = properties.colLast;
   }
 
   /**
@@ -107,6 +140,30 @@ export class RangeMarker {
     return this.date;
   }
 
+  /**
+   * Gets the w:displacedByCustomXml attribute value. Only meaningful on
+   * moveFrom/moveTo range start/end markers; undefined on all other types.
+   */
+  getDisplacedByCustomXml(): DisplacedByCustomXml | undefined {
+    return this.displacedByCustomXml;
+  }
+
+  /**
+   * Gets the w:colFirst column index. Only meaningful on CT_MoveBookmark-
+   * derived start markers; undefined otherwise.
+   */
+  getColFirst(): number | undefined {
+    return this.colFirst;
+  }
+
+  /**
+   * Gets the w:colLast column index. Only meaningful on CT_MoveBookmark-
+   * derived start markers; undefined otherwise.
+   */
+  getColLast(): number | undefined {
+    return this.colLast;
+  }
+
   /**
    * Checks if this is a start marker
    */
@@ -164,24 +221,108 @@ export class RangeMarker {
   }
 
   /**
-   * Generates XML for this range marker
-   * @returns XMLElement representing the range marker
+   * Returns true for marker types whose OOXML schema base is CT_MoveBookmark
+   * (ECMA-376 §17.13.5.15 / 19). Only these carry a w:name attribute.
+   * moveFromRangeEnd/moveToRangeEnd derive from CT_MarkupRange, and all
+   * customXml* markers derive from CT_TrackChange or CT_Markup — none of
+   * those have w:name in the schema, so emitting it produces invalid XML
+   * that fails Open XML SDK validation.
+   */
+  private supportsName(): boolean {
+    return this.type === 'moveFromRangeStart' || this.type === 'moveToRangeStart';
+  }
+
+  /**
+   * Returns true for marker types derived from CT_MarkupRange, which are the
+   * only ones whose schema permits `w:displacedByCustomXml` (ECMA-376 §17.13.5).
+   * customXml* markers (CT_TrackChange / CT_Markup) do NOT have this attribute,
+   * so emitting it there would fail schema validation.
+   */
+  private supportsDisplacedByCustomXml(): boolean {
+    return (
+      this.type === 'moveFromRangeStart' ||
+      this.type === 'moveToRangeStart' ||
+      this.type === 'moveFromRangeEnd' ||
+      this.type === 'moveToRangeEnd'
+    );
+  }
+
+  /**
+   * Returns true for marker types derived from CT_BookmarkRange, the only
+   * ones whose schema permits `w:colFirst` / `w:colLast` (ECMA-376 §17.13.5).
+   * The end markers and customXml* markers do NOT have these attributes.
+   */
+  private supportsColumnRange(): boolean {
+    return this.type === 'moveFromRangeStart' || this.type === 'moveToRangeStart';
+  }
+
+  /**
+   * Generates XML for this range marker.
+   *
+   * Required-attribute compliance per ECMA-376:
+   *   - moveFromRangeStart / moveToRangeStart (CT_MoveBookmark §17.13.5.24):
+   *     REQUIRE w:id, w:author, w:date, w:name. If any is missing, supply a
+   *     sentinel default so the emitted XML stays schema-valid:
+   *       - author → "Unknown"     (matches CT_TrackChange fallback elsewhere)
+   *       - date   → new Date()    (best-effort; the revision couldn't be
+   *                                 recorded without any time information)
+   *       - name   → "_move_${id}" (synthesized link name; both halves of a
+   *                                 move operation must use the same name,
+   *                                 so construct it deterministically from
+   *                                 the id)
+   *   - customXml*RangeStart (CT_TrackChangeRange §17.13.5.5): REQUIRE
+   *     w:id, w:author, w:date. Same defaults for author/date.
+   *   - End markers (CT_MarkupRange §17.13.5.4): only w:id required.
+   *
+   * Defaults are preferred over throwing or returning null because they
+   * keep the surrounding tracked-change context intact and leave the
+   * document openable. Factory methods (`createMoveFromStart`, etc.)
+   * already enforce the required fields at construction, so the defaults
+   * only fire when a caller directly invokes the public constructor with
+   * incomplete properties.
+   *
+   * @returns XMLElement representing the range marker.
    */
   toXML(): XMLElement {
     const attributes: Record<string, string> = {
       'w:id': this.id.toString(),
     };
 
-    // Add name attribute for move operations
-    if (this.name) {
-      attributes['w:name'] = this.name;
+    const isStart = this.isStartMarker();
+    const isMoveBookmark = this.supportsName();
+
+    // Emit w:name only on CT_MoveBookmark-derived elements (moveFromRangeStart /
+    // moveToRangeStart). CT_MoveBookmark requires w:name (§17.13.5.24); supply a
+    // synthesized fallback if the caller constructed the marker without one.
+    // Other range markers — customXml*Range* (CT_TrackChange / CT_Markup) and
+    // moveFrom/ToRangeEnd (CT_MarkupRange) — have no w:name in their schema.
+    if (isMoveBookmark) {
+      attributes['w:name'] = this.name || `_move_${this.id}`;
     }
 
-    // Add author and date for start markers
-    if (this.isStartMarker() && this.author) {
-      attributes['w:author'] = this.author;
-      if (this.date) {
-        attributes['w:date'] = this.formatDate(this.date);
+    // Author and date are required on both CT_MoveBookmark and CT_TrackChange
+    // start markers. Supply defaults if missing so the emission stays valid.
+    if (isStart) {
+      attributes['w:author'] = this.author || 'Unknown';
+      attributes['w:date'] = this.formatDate(this.date ?? new Date());
+    }
+
+    // Emit w:displacedByCustomXml only on CT_MarkupRange-derived types
+    // (move*RangeStart / move*RangeEnd). On CT_TrackChange and CT_Markup
+    // elements the attribute is not defined by the schema.
+    if (this.displacedByCustomXml && this.supportsDisplacedByCustomXml()) {
+      attributes['w:displacedByCustomXml'] = this.displacedByCustomXml;
+    }
+
+    // Emit w:colFirst / w:colLast only on CT_BookmarkRange-derived start
+    // markers (moveFromRangeStart / moveToRangeStart). Explicit-undefined
+    // check so valid column index 0 is not dropped.
+    if (this.supportsColumnRange()) {
+      if (this.colFirst !== undefined) {
+        attributes['w:colFirst'] = this.colFirst.toString();
+      }
+      if (this.colLast !== undefined) {
+        attributes['w:colLast'] = this.colLast.toString();
       }
     }
 

package/src/elements/RegisteredBodyElement.ts

@@ -0,0 +1,52 @@
+/**
+ * Body element produced by an `ElementRegistry` handler. Carries the
+ * consumer's parsed model object together with the handler reference so
+ * the document save flow can call `handler.serialize(model)` to round
+ * the element back to XML — letting consumers mutate their own model and
+ * have changes survive `doc.save()`.
+ *
+ * If the handler's `serialize()` throws, the original raw XML is emitted
+ * unchanged so a buggy custom serializer cannot corrupt the document.
+ */
+import type { ElementHandler } from '../core/ElementRegistry.js';
+import type { XMLElement } from '../xml/XMLBuilder.js';
+import { getGlobalLogger } from '../utils/logger.js';
+
+export class RegisteredBodyElement<E = unknown> {
+  constructor(
+    private readonly tag: string,
+    private readonly model: E,
+    private readonly handler: ElementHandler<E>,
+    private readonly originalXml: string
+  ) {}
+
+  getTag(): string {
+    return this.tag;
+  }
+
+  getModel(): E {
+    return this.model;
+  }
+
+  getRawXml(): string {
+    return this.originalXml;
+  }
+
+  getType(): string {
+    return 'registeredBodyElement';
+  }
+
+  toXML(): XMLElement {
+    let xml: string;
+    try {
+      xml = this.handler.serialize(this.model);
+    } catch (err) {
+      getGlobalLogger().warn('ElementRegistry serializer threw; emitting original XML', {
+        tag: this.tag,
+        error: String(err),
+      });
+      xml = this.originalXml;
+    }
+    return { name: '__rawXml', rawXml: xml } as XMLElement;
+  }
+}

package/src/elements/Revision.ts

@@ -5,13 +5,13 @@
  * to document content, showing who made changes and when.
  */
 
-import { Run } from './Run';
-import type { RunFormatting } from './Run';
-import { XMLElement } from '../xml/XMLBuilder';
-import type { RevisionLocation } from './PropertyChangeTypes';
-import type { RevisionContent } from './RevisionContent';
-import { isRunContent, isHyperlinkContent } from './RevisionContent';
-import { formatDateForXml } from '../utils/dateFormatting';
+import { Run } from './Run.js';
+import type { RunFormatting } from './Run.js';
+import { XMLElement } from '../xml/XMLBuilder.js';
+import type { RevisionLocation } from './PropertyChangeTypes.js';
+import type { RevisionContent } from './RevisionContent.js';
+import { isRunContent, isHyperlinkContent } from './RevisionContent.js';
+import { formatDateForXml } from '../utils/dateFormatting.js';
 
 /**
  * Revision type - All OpenXML WordprocessingML revision types
@@ -52,7 +52,7 @@ export type RevisionType =
  */
 export interface FieldContext {
   /** Reference to the parent ComplexField (if revision is in field result) */
-  field?: import('./Field').ComplexField;
+  field?: import('./Field.js').ComplexField;
   /** Field instruction (e.g., "HYPERLINK", "TOC", "MERGEFIELD") */
   instruction?: string;
   /** Position within field: 'instruction' or 'result' */
@@ -194,8 +194,8 @@ export class Revision {
    * Gets only the Hyperlink objects from this revision
    * @returns Array of Hyperlink objects
    */
-  getHyperlinks(): import('./Hyperlink').Hyperlink[] {
-    return this.content.filter((item): item is import('./Hyperlink').Hyperlink =>
+  getHyperlinks(): import('./Hyperlink.js').Hyperlink[] {
+    return this.content.filter((item): item is import('./Hyperlink.js').Hyperlink =>
       isHyperlinkContent(item)
     );
   }
@@ -211,7 +211,7 @@ export class Revision {
   /**
    * Adds a hyperlink to this revision
    */
-  addHyperlink(hyperlink: import('./Hyperlink').Hyperlink): this {
+  addHyperlink(hyperlink: import('./Hyperlink.js').Hyperlink): this {
     this.content.push(hyperlink);
     return this;
   }
@@ -232,7 +232,7 @@ export class Revision {
   getText(): string {
     return this.content
       .filter(
-        (item): item is Run | import('./Hyperlink').Hyperlink =>
+        (item): item is Run | import('./Hyperlink.js').Hyperlink =>
           isRunContent(item) || isHyperlinkContent(item)
       )
       .map((item) => item.getText())
@@ -331,7 +331,7 @@ export class Revision {
    * Gets the parent field if this revision is inside a complex field
    * @returns The parent ComplexField or undefined
    */
-  getParentField(): import('./Field').ComplexField | undefined {
+  getParentField(): import('./Field.js').ComplexField | undefined {
     return this.fieldContext?.field;
   }
 
@@ -832,7 +832,7 @@ export class Revision {
    * <w:hyperlink r:id="rId1"><w:ins ...><w:r>...</w:r></w:ins></w:hyperlink>
    */
   private createHyperlinkWrappedRevisionXml(
-    hyperlink: import('./Hyperlink').Hyperlink,
+    hyperlink: import('./Hyperlink.js').Hyperlink,
     revisionElementName: string,
     revisionAttributes: Record<string, string>
   ): XMLElement {

package/src/elements/RevisionContent.ts

@@ -9,9 +9,9 @@
  * This module provides the type definitions and type guards for revision content.
  */
 
-import type { Run } from './Run';
-import type { Hyperlink } from './Hyperlink';
-import type { ImageRun } from './ImageRun';
+import type { Run } from './Run.js';
+import type { Hyperlink } from './Hyperlink.js';
+import type { ImageRun } from './ImageRun.js';
 
 /**
  * Content types valid within a revision (tracked change)

package/src/elements/RevisionManager.ts

@@ -4,9 +4,9 @@
  * Tracks all revisions, assigns unique IDs, and provides statistics.
  */
 
-import { Revision, RevisionType } from './Revision';
-import type { RevisionLocation } from './PropertyChangeTypes';
-import { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger';
+import { Revision, RevisionType } from './Revision.js';
+import type { RevisionLocation } from './PropertyChangeTypes.js';
+import { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger.js';
 
 // Scoped logger for RevisionManager
 function getLogger(): ILogger {