docxmlater 10.4.0 → 11.0.4

package/src/core/DocumentValidator.ts

@@ -3,13 +3,13 @@
  * Prevents security issues and data corruption
  */
 
-import { Paragraph } from '../elements/Paragraph';
-import { Table } from '../elements/Table';
-import { ImageManager } from '../elements/ImageManager';
-import { DocumentProperties } from './Document';
-import { BodyElement } from './DocumentContent';
-import { LIMITS } from '../constants/limits';
-import { defaultLogger } from '../utils/logger';
+import { Paragraph } from '../elements/Paragraph.js';
+import { Table } from '../elements/Table.js';
+import { ImageManager } from '../elements/ImageManager.js';
+import type { DocumentProperties } from '../types/document-types.js';
+import { BodyElement } from './DocumentContent.js';
+import { LIMITS } from '../constants/limits.js';
+import { defaultLogger } from '../utils/logger.js';
 import * as v8 from 'v8';
 
 /**

package/src/core/ElementRegistry.ts

@@ -0,0 +1,69 @@
+/**
+ * Plugin extension point for custom OOXML element handlers. When the
+ * parser encounters an unknown qualified-name child of the body and a
+ * handler is registered for that tag, the handler's `parse()` is invoked
+ * and the result becomes a `PreservedElement` carrying the original raw
+ * XML (so save round-trips byte-for-byte). Handlers that return objects
+ * with a `toXml()` method allow consumers to roundtrip through their
+ * own model — see DocumentParser.processBodyElement for the contract.
+ *
+ * Registration is process-global; clear via `clear()` between tests.
+ *
+ * @example
+ * ```typescript
+ * ElementRegistry.register('myco:specialBlock', {
+ *   parse: (xml) => new MySpecialBlock(xml),
+ *   serialize: (element) => (element as MySpecialBlock).toXML(),
+ * });
+ * ```
+ */
+import { KeyedRegistry } from '../utils/KeyedRegistry.js';
+
+export interface ElementHandler<E = unknown> {
+  /** Parse the raw XML fragment for this element into a model object. */
+  parse(rawXml: string, context?: ElementParseContext): E;
+  /** Serialize the model object back to raw XML. */
+  serialize(element: E, context?: ElementSerializeContext): string;
+}
+
+export interface ElementParseContext {
+  /** Path of the OOXML part being parsed (e.g., 'word/document.xml'). */
+  partPath?: string;
+}
+
+export interface ElementSerializeContext {
+  partPath?: string;
+}
+
+class ElementRegistryImpl {
+  private readonly inner = new KeyedRegistry<ElementHandler<unknown>>('ElementRegistry');
+
+  register<E>(tag: string, handler: ElementHandler<E>): void {
+    this.inner.register(tag, handler as ElementHandler<unknown>);
+  }
+
+  unregister(tag: string): boolean {
+    return this.inner.unregister(tag);
+  }
+
+  has(tag: string): boolean {
+    return this.inner.has(tag);
+  }
+
+  get<E = unknown>(tag: string): ElementHandler<E> | undefined {
+    return this.inner.get(tag) as ElementHandler<E> | undefined;
+  }
+
+  /** Returns the list of currently-registered tags (snapshot). */
+  registeredTags(): string[] {
+    return this.inner.keys();
+  }
+
+  /** Remove all handlers — primarily for test isolation. */
+  clear(): void {
+    this.inner.clear();
+  }
+}
+
+/** Process-global element registry instance. */
+export const ElementRegistry = new ElementRegistryImpl();

package/src/core/Relationship.ts

@@ -5,7 +5,7 @@
  * They are stored in _rels/*.xml.rels files throughout the document structure.
  */
 
-import { XMLBuilder } from '../xml/XMLBuilder';
+import { XMLBuilder } from '../xml/XMLBuilder.js';
 
 /**
  * Relationship types used in Word documents

package/src/core/RelationshipManager.ts

@@ -5,10 +5,10 @@
  * document parts (document.xml, header.xml, footer.xml, etc.)
  */
 
-import { Relationship, RelationshipType } from './Relationship';
-import { XMLParser } from '../xml/XMLParser';
-import { sanitizeHyperlinkUrl } from '../utils/validation';
-import { InvalidDocxError, CorruptedArchiveError } from '../zip/errors';
+import { Relationship, RelationshipType } from './Relationship.js';
+import { XMLParser } from '../xml/XMLParser.js';
+import { sanitizeHyperlinkUrl } from '../utils/validation.js';
+import { InvalidDocxError, CorruptedArchiveError } from '../zip/errors.js';
 
 /**
  * Manages relationships for a document or document part

package/src/elements/AlternateContent.ts

@@ -7,7 +7,7 @@
  * Stored as raw XML for round-trip fidelity since the internal structure varies widely.
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
+import { XMLElement } from '../xml/XMLBuilder.js';
 
 export class AlternateContent {
   private rawXml: string;

package/src/elements/Bookmark.ts

@@ -5,7 +5,16 @@
  * They consist of a start marker and an end marker with matching IDs.
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
+import { XMLElement } from '../xml/XMLBuilder.js';
+
+/**
+ * `w:displacedByCustomXml` attribute value per ECMA-376 CT_MarkupRange —
+ * ST_DisplacedByCustomXml enum: "next" | "prev". Indicates which side of
+ * a custom-XML boundary the marker semantically belongs to when the
+ * marker had to be displaced because a custom-XML node boundary fell at
+ * the same position.
+ */
+export type DisplacedByCustomXml = 'next' | 'prev';
 
 /**
  * Bookmark properties
@@ -21,6 +30,13 @@ export interface BookmarkProperties {
   colFirst?: number;
   /** Last column in table bookmark range (ECMA-376 §17.16.5) */
   colLast?: number;
+  /**
+   * `w:displacedByCustomXml` per ECMA-376 CT_MarkupRange / CT_Bookmark.
+   * Valid on both `<w:bookmarkStart>` (CT_Bookmark) and `<w:bookmarkEnd>`
+   * (CT_MarkupRange). Preserves the custom-XML boundary disambiguator
+   * that Word emits when a bookmark was displaced by a custom-XML node.
+   */
+  displacedByCustomXml?: DisplacedByCustomXml;
 }
 
 /**
@@ -31,6 +47,7 @@ export class Bookmark {
   private name: string;
   private colFirst?: number;
   private colLast?: number;
+  private displacedByCustomXml?: DisplacedByCustomXml;
 
   /**
    * Creates a new Bookmark
@@ -45,6 +62,7 @@ export class Bookmark {
       : this.normalizeName(properties.name);
     this.colFirst = properties.colFirst;
     this.colLast = properties.colLast;
+    this.displacedByCustomXml = properties.displacedByCustomXml;
   }
 
   /**
@@ -167,6 +185,24 @@ export class Bookmark {
     return this;
   }
 
+  /**
+   * Gets the `w:displacedByCustomXml` attribute value.
+   * Preserved on both bookmarkStart and bookmarkEnd per ECMA-376
+   * CT_MarkupRange (§17.13.5) / CT_Bookmark (§17.16.5).
+   */
+  getDisplacedByCustomXml(): DisplacedByCustomXml | undefined {
+    return this.displacedByCustomXml;
+  }
+
+  /**
+   * Sets the `w:displacedByCustomXml` attribute value.
+   * @param value "next" | "prev" | undefined
+   */
+  setDisplacedByCustomXml(value: DisplacedByCustomXml | undefined): this {
+    this.displacedByCustomXml = value;
+    return this;
+  }
+
   /**
    * Generates XML for the bookmark start marker
    * @returns XMLElement for bookmarkStart
@@ -179,6 +215,11 @@ export class Bookmark {
     // Table bookmark column range per ECMA-376 §17.16.5
     if (this.colFirst !== undefined) attrs['w:colFirst'] = this.colFirst.toString();
     if (this.colLast !== undefined) attrs['w:colLast'] = this.colLast.toString();
+    // Custom-XML displacement marker per CT_MarkupRange (§17.13.5) —
+    // the same attribute also carried by the RangeMarker sibling class.
+    if (this.displacedByCustomXml) {
+      attrs['w:displacedByCustomXml'] = this.displacedByCustomXml;
+    }
     return {
       name: 'w:bookmarkStart',
       attributes: attrs,
@@ -191,11 +232,18 @@ export class Bookmark {
    * @returns XMLElement for bookmarkEnd
    */
   toEndXML(): XMLElement {
+    const attrs: Record<string, string | number> = {
+      'w:id': this.id.toString(),
+    };
+    // bookmarkEnd is CT_MarkupRange per ECMA-376 §17.13.6.1 — w:displacedByCustomXml
+    // is valid here too (the BookmarkRange column attributes are NOT, so those
+    // stay scoped to toStartXML above).
+    if (this.displacedByCustomXml) {
+      attrs['w:displacedByCustomXml'] = this.displacedByCustomXml;
+    }
     return {
       name: 'w:bookmarkEnd',
-      attributes: {
-        'w:id': this.id.toString(),
-      },
+      attributes: attrs,
       selfClosing: true,
     };
   }

package/src/elements/BookmarkManager.ts

@@ -7,8 +7,8 @@
  * in a document. Use setIdProvider() to connect to a centralized ID allocator.
  */
 
-import { Bookmark } from './Bookmark';
-import { InvalidDocxError } from '../zip/errors';
+import { Bookmark } from './Bookmark.js';
+import { InvalidDocxError } from '../zip/errors.js';
 
 /**
  * Type for the centralized ID provider callback.

package/src/elements/Comment.ts

@@ -5,9 +5,9 @@
  * They include author, date, content, and can have replies.
  */
 
-import { Run } from './Run';
-import { XMLElement } from '../xml/XMLBuilder';
-import { formatDateForXml } from '../utils/dateFormatting';
+import { Run } from './Run.js';
+import { XMLElement } from '../xml/XMLBuilder.js';
+import { formatDateForXml } from '../utils/dateFormatting.js';
 
 /**
  * Comment properties

package/src/elements/CommentManager.ts

@@ -8,10 +8,10 @@
  * in a document. Use setIdProvider() to connect to a centralized ID allocator.
  */
 
-import { Comment } from './Comment';
-import { Run } from './Run';
-import { XMLBuilder } from '../xml/XMLBuilder';
-import { formatDateForXml } from '../utils/dateFormatting';
+import { Comment } from './Comment.js';
+import { Run } from './Run.js';
+import { XMLBuilder } from '../xml/XMLBuilder.js';
+import { formatDateForXml } from '../utils/dateFormatting.js';
 
 /**
  * Type for the centralized ID provider callback.

package/src/elements/CommonTypes.ts

@@ -150,14 +150,37 @@ export type FullBorderStyle =
  * TableCell.ts (CellBorder), Table.ts (TableBorder)
  */
 export interface BorderDefinition {
-  /** Border style */
-  style?: BorderStyle | ExtendedBorderStyle;
+  /**
+   * Border style per ECMA-376 Part 1 §17.18.2 ST_Border. Uses the full
+   * 25+ value set (triple / dotDash / multi-line gap variants / inset /
+   * outset / etc.) rather than the narrower ExtendedBorderStyle subset
+   * — the generator passes the raw string through unfiltered, so any
+   * ST_Border value is spec-valid here.
+   */
+  style?: FullBorderStyle;
   /** Border width in eighths of a point (1-96) */
   size?: number;
   /** Border color in hex format (without #) */
   color?: string;
   /** Space between border and content in points (0-31) */
   space?: number;
+  /**
+   * Theme color reference (ST_ThemeColor per §17.18.97) — e.g. "accent1",
+   * "text2". When both `color` and `themeColor` are set, Word uses the
+   * themeColor lookup and treats `color` as a fallback.
+   */
+  themeColor?: string;
+  /** Theme tint (0-255, hex string) applied to themeColor lookup */
+  themeTint?: string;
+  /** Theme shade (0-255, hex string) applied to themeColor lookup */
+  themeShade?: string;
+  /** Whether the border casts a shadow (CT_OnOff attribute on CT_Border) */
+  shadow?: boolean;
+  /**
+   * Whether the border is part of a frame around the content (CT_OnOff).
+   * Primarily used on page borders but valid per CT_Border for all sides.
+   */
+  frame?: boolean;
 }
 
 /**
@@ -216,11 +239,13 @@ export type VerticalAlignment =
 export type PageVerticalAlignment = 'top' | 'center' | 'bottom' | 'both';
 
 /**
- * Vertical alignment for table cells
+ * Vertical alignment for table cells per ECMA-376 Part 1 §17.18.101
+ * ST_VerticalJc. `both` distributes the cell content vertically with
+ * equal top/bottom gaps — the vertical-axis analogue of justified text.
  *
  * From: TableCell.ts (CellVerticalAlignment)
  */
-export type CellVerticalAlignment = 'top' | 'center' | 'bottom';
+export type CellVerticalAlignment = 'top' | 'center' | 'both' | 'bottom';
 
 /**
  * Paragraph text alignment per ECMA-376 §17.18.44 (ST_Jc)
@@ -241,7 +266,13 @@ export type ParagraphAlignment =
   | 'mediumKashida'
   | 'highKashida'
   | 'lowKashida'
-  | 'thaiDistribute';
+  | 'thaiDistribute'
+  /**
+   * `numTab` per ST_Jc — numbering tab alignment mode used when the paragraph
+   * is the anchor of a numbered list and the alignment should follow the
+   * numbering tab stop. Rare in practice but spec-valid per §17.18.44.
+   */
+  | 'numTab';
 
 /**
  * Table alignment (horizontal positioning) per ECMA-376 §17.18.45 (ST_JcTable)
@@ -270,11 +301,17 @@ export type TextVerticalAlignment = 'top' | 'center' | 'baseline' | 'bottom' | '
  *
  * From: Paragraph.ts (TabAlignment)
  */
+/**
+ * Tab stop alignment per ECMA-376 Part 1 §17.18.94 ST_TabJc.
+ * `start` / `end` are the bidi-aware alternatives to `left` / `right`.
+ */
 export type TabAlignment =
   | 'clear' // Remove tab stop
-  | 'left' // Left-aligned
+  | 'left' // Left-aligned (LTR-biased)
+  | 'start' // Start-aligned (bidi-aware)
   | 'center' // Center-aligned
-  | 'right' // Right-aligned
+  | 'right' // Right-aligned (LTR-biased)
+  | 'end' // End-aligned (bidi-aware)
   | 'decimal' // Decimal-aligned (for numbers)
   | 'bar' // Bar tab (vertical line)
   | 'num'; // List number alignment
@@ -493,6 +530,7 @@ export function isParagraphAlignment(value: string): value is ParagraphAlignment
     'highKashida',
     'lowKashida',
     'thaiDistribute',
+    'numTab',
   ].includes(value);
 }
 

package/src/elements/CustomXml.ts

@@ -7,7 +7,7 @@
  * Stored as raw XML for round-trip fidelity.
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
+import { XMLElement } from '../xml/XMLBuilder.js';
 
 /**
  * Block-level custom XML (w:customXml wrapping block content)

package/src/elements/Endnote.ts

@@ -5,8 +5,8 @@
  * within the document text via endnote references.
  */
 
-import { Paragraph } from './Paragraph';
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+import { Paragraph } from './Paragraph.js';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder.js';
 
 /**
  * Endnote type

package/src/elements/EndnoteManager.ts

@@ -5,9 +5,9 @@
  * Maintains unique IDs and proper ordering.
  */
 
-import { Endnote, EndnoteType } from './Endnote';
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
-import { XMLParser } from '../xml/XMLParser';
+import { Endnote, EndnoteType } from './Endnote.js';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder.js';
+import { XMLParser } from '../xml/XMLParser.js';
 
 /**
  * Manages endnotes in a document

package/src/elements/Field.ts

@@ -5,15 +5,15 @@
  * They are represented using the <w:fldSimple> element with field codes.
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
-import { RunFormatting, FormFieldData } from './Run';
+import { XMLElement } from '../xml/XMLBuilder.js';
+import { RunFormatting, FormFieldData } from './Run.js';
 import {
   ParsedHyperlinkInstruction,
   parseHyperlinkInstruction,
   isHyperlinkInstruction,
-} from './FieldHelpers';
-import type { Revision } from './Revision';
-import { pointsToHalfPoints } from '../utils/units';
+} from './FieldHelpers.js';
+import type { Revision } from './Revision.js';
+import { pointsToHalfPoints } from '../utils/units.js';
 
 /**
  * Common field types
@@ -61,6 +61,17 @@ export interface FieldProperties {
   preserveFormatting?: boolean;
   /** Run formatting for field result */
   formatting?: RunFormatting;
+  /**
+   * `<w:fldSimple w:fldLock="…">` — CT_OnOff per ECMA-376 §17.16.16.
+   * When true, the field is locked against automatic updates.
+   */
+  fldLock?: boolean;
+  /**
+   * `<w:fldSimple w:dirty="…">` — CT_OnOff per ECMA-376 §17.16.16.
+   * When true, the field's cached result is out of date and Word should
+   * refresh it at open-time.
+   */
+  dirty?: boolean;
 }
 
 /**
@@ -70,6 +81,8 @@ export class Field {
   private type: FieldType;
   private instruction: string;
   private formatting?: RunFormatting;
+  private fldLock?: boolean;
+  private dirty?: boolean;
 
   /**
    * Creates a new field
@@ -78,6 +91,8 @@ export class Field {
   constructor(properties: FieldProperties) {
     this.type = properties.type;
     this.formatting = properties.formatting;
+    this.fldLock = properties.fldLock;
+    this.dirty = properties.dirty;
 
     // Build field instruction
     if (properties.instruction) {
@@ -180,16 +195,35 @@ export class Field {
     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.getPlaceholderText()],
     });
 
+    // CT_SimpleField (§17.16.16) carries two ST_OnOff attributes beyond
+    // the required w:instr: w:fldLock (locked against updates) and
+    // w:dirty (cached result out of date). Emit when the caller set
+    // them so Word-authored fldSimple documents round-trip their
+    // lock/dirty state instead of silently clearing it.
+    const fldSimpleAttrs: Record<string, string> = {
+      'w:instr': this.instruction,
+    };
+    if (this.fldLock !== undefined) {
+      fldSimpleAttrs['w:fldLock'] = this.fldLock ? '1' : '0';
+    }
+    if (this.dirty !== undefined) {
+      fldSimpleAttrs['w:dirty'] = this.dirty ? '1' : '0';
+    }
+
     return {
       name: 'w:fldSimple',
-      attributes: {
-        'w:instr': this.instruction,
-      },
+      attributes: fldSimpleAttrs,
       children: [
         {
           name: 'w:r',
@@ -627,7 +661,7 @@ export class ComplexField {
    */
   private _hasResultSection = false;
   private _formFieldData?: FormFieldData;
-  private trackingContext?: import('../tracking/TrackingContext').TrackingContext;
+  private trackingContext?: import('../tracking/TrackingContext.js').TrackingContext;
 
   /**
    * Creates a new complex field
@@ -848,7 +882,7 @@ export class ComplexField {
    * Sets the tracking context for automatic change tracking
    * @internal
    */
-  _setTrackingContext(context: import('../tracking/TrackingContext').TrackingContext): void {
+  _setTrackingContext(context: import('../tracking/TrackingContext.js').TrackingContext): void {
     this.trackingContext = context;
   }
 

package/src/elements/FieldHelpers.ts

@@ -2,8 +2,8 @@
  * Helper functions for creating complex and nested fields
  */
 
-import { ComplexField } from './Field';
-import { defaultLogger } from '../utils/logger';
+import { ComplexField } from './Field.js';
+import { defaultLogger } from '../utils/logger.js';
 
 /**
  * Parsed components of a HYPERLINK field instruction

package/src/elements/Footer.ts

@@ -5,10 +5,10 @@
  * Different footers can be defined for first page, odd pages, and even pages.
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
-import { Paragraph } from './Paragraph';
-import { RunFormatting } from './Run';
-import { Table } from './Table';
+import { XMLElement } from '../xml/XMLBuilder.js';
+import { Paragraph } from './Paragraph.js';
+import { RunFormatting } from './Run.js';
+import { Table } from './Table.js';
 
 /**
  * Footer type

package/src/elements/Footnote.ts

@@ -5,8 +5,8 @@
  * within the document text via footnote references.
  */
 
-import { Paragraph } from './Paragraph';
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+import { Paragraph } from './Paragraph.js';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder.js';
 
 /**
  * Footnote type

package/src/elements/FootnoteManager.ts

@@ -5,9 +5,9 @@
  * Maintains unique IDs and proper ordering.
  */
 
-import { Footnote, FootnoteType } from './Footnote';
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
-import { XMLParser } from '../xml/XMLParser';
+import { Footnote, FootnoteType } from './Footnote.js';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder.js';
+import { XMLParser } from '../xml/XMLParser.js';
 
 /**
  * Manages footnotes in a document

package/src/elements/Header.ts

@@ -5,10 +5,10 @@
  * Different headers can be defined for first page, odd pages, and even pages.
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
-import { Paragraph } from './Paragraph';
-import { RunFormatting } from './Run';
-import { Table } from './Table';
+import { XMLElement } from '../xml/XMLBuilder.js';
+import { Paragraph } from './Paragraph.js';
+import { RunFormatting } from './Run.js';
+import { Table } from './Table.js';
 
 /**
  * Header type

package/src/elements/HeaderFooterManager.ts

@@ -5,8 +5,8 @@
  * and manages relationships.
  */
 
-import { Header } from './Header';
-import { Footer } from './Footer';
+import { Header } from './Header.js';
+import { Footer } from './Footer.js';
 
 /**
  * Header entry with metadata