docxmlater 10.0.2 → 10.0.3

package/src/tracking/TrackingContext.ts

@@ -0,0 +1,173 @@
+/**
+ * TrackingContext - Interface for automatic change tracking
+ *
+ * When enabled via Document.enableTrackChanges(), element setter methods
+ * use this context to automatically create Revision objects for changes.
+ *
+ * @module TrackingContext
+ */
+
+import type { Revision, RevisionType } from '../elements/Revision';
+import type { RevisionManager } from '../elements/RevisionManager';
+import type { Run } from '../elements/Run';
+import type { Paragraph } from '../elements/Paragraph';
+import type { Table } from '../elements/Table';
+import type { TableRow } from '../elements/TableRow';
+import type { TableCell } from '../elements/TableCell';
+import type { Section } from '../elements/Section';
+
+/** Union of element types that can be tracked */
+export type TrackableElement = Run | Paragraph | Table | TableRow | TableCell | Section | { constructor: { name: string } };
+
+/**
+ * Pending change entry before flushing to RevisionManager
+ */
+export interface PendingChange {
+  /** Type of revision to create */
+  type: RevisionType;
+  /** Property that changed */
+  property: string;
+  /** Value before the change */
+  previousValue: unknown;
+  /** Value after the change */
+  newValue: unknown;
+  /** Element that was modified */
+  element: TrackableElement;
+  /** When the change occurred */
+  timestamp: number;
+  /** Count for consolidated changes */
+  count?: number;
+}
+
+/**
+ * Interface for tracking changes to document elements.
+ *
+ * Elements call tracking methods when their setters are invoked.
+ * The context decides whether to create revisions based on enabled state.
+ */
+export interface TrackingContext {
+  /**
+   * Check if change tracking is currently enabled
+   */
+  isEnabled(): boolean;
+
+  /**
+   * Get the author name for new revisions
+   */
+  getAuthor(): string;
+
+  /**
+   * Get the RevisionManager for registering revisions
+   */
+  getRevisionManager(): RevisionManager;
+
+  /**
+   * Check if formatting changes should be tracked
+   */
+  isTrackFormattingEnabled(): boolean;
+
+  /**
+   * Track a Run property change (bold, italic, font, color, etc.)
+   * @param run - The Run that was modified
+   * @param property - Property name (e.g., 'bold', 'color')
+   * @param oldValue - Value before the change
+   * @param newValue - Value after the change
+   */
+  trackRunPropertyChange(
+    run: Run,
+    property: string,
+    oldValue: unknown,
+    newValue: unknown
+  ): void;
+
+  /**
+   * Track a Paragraph property change (alignment, spacing, etc.)
+   * @param paragraph - The Paragraph that was modified
+   * @param property - Property name (e.g., 'alignment', 'spaceBefore')
+   * @param oldValue - Value before the change
+   * @param newValue - Value after the change
+   */
+  trackParagraphPropertyChange(
+    paragraph: TrackableElement,
+    property: string,
+    oldValue: unknown,
+    newValue: unknown
+  ): void;
+
+  /**
+   * Track a Hyperlink change (URL, anchor, text, formatting)
+   * @param hyperlink - The Hyperlink that was modified
+   * @param changeType - Type of change (e.g., 'url', 'text', 'formatting')
+   * @param oldValue - Value before the change
+   * @param newValue - Value after the change
+   */
+  trackHyperlinkChange(
+    hyperlink: TrackableElement,
+    changeType: string,
+    oldValue: unknown,
+    newValue: unknown
+  ): void;
+
+  /**
+   * Track a Table element property change
+   * @param element - The table/row/cell that was modified
+   * @param property - Property name
+   * @param oldValue - Value before the change
+   * @param newValue - Value after the change
+   */
+  trackTableChange(
+    element: TrackableElement,
+    property: string,
+    oldValue: unknown,
+    newValue: unknown
+  ): void;
+
+  /**
+   * Track a Section property change
+   * @param section - The Section that was modified
+   * @param property - Property name (e.g., 'pageSize', 'margins')
+   * @param oldValue - Value before the change
+   * @param newValue - Value after the change
+   */
+  trackSectionChange(
+    section: TrackableElement,
+    property: string,
+    oldValue: unknown,
+    newValue: unknown
+  ): void;
+
+  /**
+   * Track text insertion
+   * @param element - Element containing the insertion
+   * @param text - Text that was inserted
+   */
+  trackInsertion(element: TrackableElement, text: string): void;
+
+  /**
+   * Track text deletion
+   * @param element - Element containing the deletion
+   * @param text - Text that was deleted
+   */
+  trackDeletion(element: TrackableElement, text: string): void;
+
+  /**
+   * Flush all pending changes and create Revision objects.
+   * This is called automatically before document save.
+   * @returns Array of created revisions
+   */
+  flushPendingChanges(): Revision[];
+
+  /**
+   * Create an insertion revision (factory to avoid circular dependency in Run)
+   * @param content - Run or array of content for the insertion
+   * @param date - Optional date for the revision
+   */
+  createInsertion(content: Run, date?: Date): Revision;
+
+  /**
+   * Create a deletion revision (factory to avoid circular dependency in Run)
+   * @param content - Run or array of content for the deletion
+   * @param date - Optional date for the revision
+   */
+  createDeletion(content: Run, date?: Date): Revision;
+}

package/src/types/compatibility-types.ts

@@ -0,0 +1,49 @@
+/**
+ * Word compatibility mode versions.
+ *
+ * These map to Microsoft's internal version numbers used in the
+ * w:compatSetting name="compatibilityMode" value within settings.xml.
+ *
+ * Per MS-DOCX specification, the default when absent is 12 (Word 2007).
+ * See: https://learn.microsoft.com/en-us/openspecs/office_standards/ms-docx/90138c4d-eb18-4edc-aa6c-dfb799cb1d0d
+ */
+export enum CompatibilityMode {
+  /** Word 2003 and earlier — uses MS-DOC feature set */
+  Word2003 = 11,
+  /** Word 2007 (ECMA-376 1st edition) — DEFAULT when absent */
+  Word2007 = 12,
+  /** Word 2010 (ISO/IEC 29500 with exclusions) */
+  Word2010 = 14,
+  /** Word 2013/2016/2019/365 (full modern features) */
+  Word2013Plus = 15,
+}
+
+/**
+ * A single w:compatSetting entry (name/uri/val triple).
+ *
+ * These are the modern extensibility mechanism for compatibility settings,
+ * added in ECMA-376 2nd edition. They coexist with legacy boolean flags
+ * in the Transitional schema.
+ */
+export interface CompatSetting {
+  name: string;
+  uri: string;
+  val: string;
+}
+
+/**
+ * Parsed compatibility settings from the w:compat block in settings.xml.
+ */
+export interface CompatibilityInfo {
+  /** The numeric compatibility mode value (11, 12, 14, or 15) */
+  mode: CompatibilityMode;
+
+  /** Whether the document is in a legacy compatibility mode (below 15) */
+  isLegacyMode: boolean;
+
+  /** Modern w:compatSetting entries (name/uri/val triples) */
+  compatSettings: CompatSetting[];
+
+  /** Legacy boolean compat flags that are present and enabled (without w: prefix) */
+  legacyFlags: string[];
+}

package/src/types/formatting.ts

@@ -0,0 +1,210 @@
+/**
+ * Additional formatting types for enhanced document manipulation
+ */
+
+// Forward references to avoid circular dependencies
+import type { Paragraph } from '../elements/Paragraph';
+import type { Run } from '../elements/Run';
+
+/**
+ * Border style options
+ */
+export type BorderStyleType = 'single' | 'double' | 'dashed' | 'dotted' | 'triple' | 'none';
+
+/**
+ * Individual border configuration
+ */
+export interface BorderStyle {
+  /** Border style */
+  style: BorderStyleType;
+  /** Border width in eighths of a point */
+  width: number;
+  /** Border color in hex format */
+  color: string;
+  /** Space between border and text in points */
+  space?: number;
+}
+
+/**
+ * Paragraph border configuration
+ */
+export interface ParagraphBorder {
+  /** Top border */
+  top?: BorderStyle;
+  /** Bottom border */
+  bottom?: BorderStyle;
+  /** Left border */
+  left?: BorderStyle;
+  /** Right border */
+  right?: BorderStyle;
+  /** Apply border between paragraphs */
+  between?: boolean;
+}
+
+/**
+ * Shading patterns — re-exported from CommonTypes for backward compatibility.
+ * @see CommonTypes.ShadingPattern for the canonical definition
+ */
+export type { ShadingPattern } from '../elements/CommonTypes';
+
+/**
+ * Paragraph shading configuration — re-exported from CommonTypes for backward compatibility.
+ * @see CommonTypes.ShadingConfig for the canonical definition (includes theme attributes)
+ */
+export type { ShadingConfig as ParagraphShading } from '../elements/CommonTypes';
+
+/**
+ * Tab stop alignment
+ */
+export type TabAlignment = 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear';
+
+/**
+ * Tab leader character
+ */
+export type TabLeader = 'none' | 'dot' | 'dash' | 'underscore' | 'heavy' | 'middleDot';
+
+/**
+ * Tab stop configuration
+ */
+export interface TabStop {
+  /** Position in twips from left margin */
+  position: number;
+  /** Tab alignment type */
+  type: TabAlignment;
+  /** Leader character */
+  leader?: TabLeader;
+}
+
+/**
+ * Text search options
+ */
+export interface FindOptions {
+  /** Case sensitive search */
+  caseSensitive?: boolean;
+  /** Match whole words only */
+  wholeWord?: boolean;
+  /** Use regular expressions */
+  useRegex?: boolean;
+  /** Include headers and footers */
+  includeHeadersFooters?: boolean;
+  /** Include footnotes and endnotes */
+  includeNotes?: boolean;
+}
+
+/**
+ * Text replacement options
+ */
+export interface ReplaceOptions extends FindOptions {
+  /** Maximum number of replacements (0 = unlimited) */
+  maxReplacements?: number;
+  /** Track changes for replacements */
+  trackChanges?: boolean;
+  /** Author for track changes */
+  author?: string;
+}
+
+/**
+ * Search result
+ */
+export interface SearchResult {
+  /** The paragraph containing the match */
+  paragraph: Paragraph;
+  /** The run containing the match */
+  run?: Run;
+  /** Match start position in paragraph */
+  startIndex: number;
+  /** Match end position in paragraph */
+  endIndex: number;
+  /** The matched text */
+  match: string;
+}
+
+/**
+ * Text emphasis options
+ */
+export type EmphasisType = 'bold' | 'italic' | 'underline';
+
+/**
+ * List prefix configuration
+ */
+export interface ListPrefix {
+  /** List format type */
+  format: 'bullet' | 'number';
+  /** Custom style string (e.g., '•', '1.', 'a)') */
+  style: string;
+}
+
+/**
+ * Format options for style application
+ */
+export interface FormatOptions {
+  // Text formatting
+  /** Font family name (e.g., 'Arial', 'Verdana') */
+  font?: string;
+  /** Font size in points */
+  size?: number;
+  /** Text color as 6-digit hex (e.g., 'FF0000' for red) */
+  color?: string;
+  /** Text emphasis (bold, italic, underline) */
+  emphasis?: EmphasisType[];
+
+  // Alignment
+  /** Paragraph alignment */
+  alignment?: 'left' | 'right' | 'center' | 'justify';
+
+  // Spacing (in points)
+  /** Space before paragraph in points */
+  spaceAbove?: number;
+  /** Space after paragraph in points */
+  spaceBelow?: number;
+  /** Line spacing in points or multiplier */
+  lineSpacing?: number;
+
+  // Indentation (in inches)
+  /** Left indentation in inches */
+  indentLeft?: number;
+  /** Right indentation in inches */
+  indentRight?: number;
+  /** First line indentation in inches */
+  indentFirst?: number;
+  /** Hanging indentation in inches */
+  indentHanging?: number;
+
+  // Padding (in points) - for table cells
+  /** Top padding in points */
+  paddingTop?: number;
+  /** Bottom padding in points */
+  paddingBottom?: number;
+  /** Left padding in points */
+  paddingLeft?: number;
+  /** Right padding in points */
+  paddingRight?: number;
+
+  // List formatting
+  /** List prefix style */
+  prefixList?: string | ListPrefix;
+
+  // Advanced options
+  /** Border color as 6-digit hex */
+  borderColor?: string;
+  /** Border width in points */
+  borderWidth?: number;
+  /** Background shading color as 6-digit hex */
+  shading?: string;
+  /** Keep with next paragraph */
+  keepWithNext?: boolean;
+  /** Keep lines together */
+  keepLines?: boolean;
+}
+
+/**
+ * Options for applying styles to paragraphs
+ */
+export interface StyleApplyOptions {
+  /** Specific paragraphs to apply style to (default: auto-detect) */
+  paragraphs?: Paragraph[];
+  /** Properties to preserve from existing formatting */
+  keepProperties?: string[];
+  /** Custom formatting to apply */
+  format?: FormatOptions;
+}

package/src/types/list-types.ts

@@ -0,0 +1,152 @@
+/**
+ * List Normalization Types for docxmlater
+ *
+ * These types support detection and normalization of typed list prefixes
+ * to proper Word list formatting.
+ */
+
+/** High-level list category */
+export type ListCategory = "numbered" | "bullet" | "none";
+
+/** Specific number format patterns */
+export type NumberFormat =
+  | "decimal" // 1. 2. 3.
+  | "lowerLetter" // a. b. c.
+  | "upperLetter" // A. B. C.
+  | "lowerRoman" // i. ii. iii.
+  | "upperRoman"; // I. II. III.
+
+/** Specific bullet format patterns */
+export type BulletFormat =
+  | "bullet" // • ● ○
+  | "dash" // - – —
+  | "arrow"; // ► ▸
+
+/**
+ * Result of detecting list type for a single paragraph
+ */
+export interface ListDetectionResult {
+  /** High-level category */
+  category: ListCategory;
+
+  /** True if paragraph has <w:numPr> (real Word list) */
+  isWordList: boolean;
+
+  /** The typed prefix found, e.g., "1. ", "a) ", "• " */
+  typedPrefix: string | null;
+
+  /** Inferred nesting level based on indentation */
+  inferredLevel: number;
+
+  /** Specific format detected */
+  format: NumberFormat | BulletFormat | null;
+
+  /** If Word list, the numId from <w:numPr> */
+  numId: number | null;
+
+  /** If Word list, the ilvl from <w:numPr> */
+  ilvl: number | null;
+
+  /** Raw indentation in twips for debugging */
+  indentationTwips: number;
+}
+
+/**
+ * Analysis of all lists within a scope (cell, table, document)
+ */
+export interface ListAnalysis {
+  /** All analyzed paragraphs with their detection results */
+  paragraphs: {
+    paragraph: unknown; // Paragraph instance - using unknown to avoid circular dep
+    text: string;
+    detection: ListDetectionResult;
+  }[];
+
+  /** True if any typed (non-Word) lists found */
+  hasTypedLists: boolean;
+
+  /** True if any real Word lists found */
+  hasWordLists: boolean;
+
+  /** True if both numbered AND bullet lists present */
+  hasMixedCategories: boolean;
+
+  /** The dominant list type in this scope */
+  majorityCategory: ListCategory;
+
+  /** Count by category */
+  counts: {
+    numbered: number;
+    bullet: number;
+    none: number;
+  };
+
+  /** Recommended action */
+  recommendedAction: "normalize" | "none";
+}
+
+/**
+ * User-defined indentation level configuration for list normalization
+ */
+export interface IndentationLevel {
+  level: number;
+  textIndent: number;      // in inches
+  symbolIndent: number;    // in inches
+  bulletChar?: string;
+  numberedFormat?: NumberFormat | string;
+}
+
+/**
+ * Options for list normalization
+ */
+export interface ListNormalizationOptions {
+  /** numId to use for numbered lists (from numbering.xml) */
+  numberedStyleNumId?: number;
+
+  /** numId to use for bullet lists (from numbering.xml) */
+  bulletStyleNumId?: number;
+
+  /** Processing scope */
+  scope?: "cell" | "table" | "document";
+
+  /**
+   * If true, convert ALL list items to majority type.
+   * If false, only convert typed lists (preserve existing Word lists).
+   */
+  forceMajority?: boolean;
+
+  /**
+   * If true, preserve original indentation instead of using level defaults.
+   */
+  preserveIndentation?: boolean;
+
+  /**
+   * User-defined indentation settings per list level.
+   * Used to configure symbol indent, text indent, and bullet characters.
+   */
+  indentationLevels?: IndentationLevel[];
+}
+
+/**
+ * Report returned after normalization
+ */
+export interface ListNormalizationReport {
+  /** Number of paragraphs successfully normalized */
+  normalized: number;
+
+  /** Number of paragraphs skipped (already correct or non-list) */
+  skipped: number;
+
+  /** Any errors encountered */
+  errors: string[];
+
+  /** The majority category that was applied */
+  appliedCategory: ListCategory;
+
+  /** Detailed per-paragraph results */
+  details: {
+    originalText: string;
+    action: "normalized" | "skipped" | "error";
+    reason?: string;
+  }[];
+}

package/src/types/settings-types.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared type definitions for document settings (settings.xml)
+ *
+ * These types are used by both Document.ts (in-memory state) and
+ * DocumentGenerator.ts (XML generation) to ensure consistency.
+ */
+
+/**
+ * Document protection settings per ECMA-376 CT_DocProtect
+ */
+export interface DocumentProtection {
+  edit: 'readOnly' | 'comments' | 'trackedChanges' | 'forms';
+  enforcement: boolean;
+  cryptProviderType?: string;
+  cryptAlgorithmClass?: string;
+  cryptAlgorithmType?: string;
+  cryptAlgorithmSid?: number;
+  cryptSpinCount?: number;
+  hash?: string;
+  salt?: string;
+}
+
+/**
+ * Revision view settings per ECMA-376 CT_TrackChangesView
+ */
+export interface RevisionViewSettings {
+  showInsertionsAndDeletions: boolean;
+  showFormatting: boolean;
+  showInkAnnotations: boolean;
+}
+
+/**
+ * Track changes and related settings passed to DocumentGenerator.generateSettings()
+ */
+export interface TrackChangesSettings {
+  trackChangesEnabled?: boolean;
+  trackFormatting?: boolean;
+  revisionView?: RevisionViewSettings;
+  rsidRoot?: string;
+  rsids?: string[];
+  documentProtection?: DocumentProtection;
+}
+
+/**
+ * Information about webSettings.xml per ECMA-376 CT_WebSettings
+ */
+export interface WebSettingsInfo {
+  divCount: number;
+  optimizeForBrowser: boolean;
+  allowPNG: boolean;
+  relyOnVML: boolean;
+  doNotRelyOnCSS: boolean;
+  doNotSaveAsSingleFile: boolean;
+  doNotOrganizeInFolder: boolean;
+  doNotUseLongFileNames: boolean;
+  pixelsPerInch?: number;
+  targetScreenSz?: string;
+  encoding?: string;
+}