docxmlater 10.0.1 → 10.0.3

package/src/utils/cnfStyleDecoder.ts

@@ -0,0 +1,217 @@
+/**
+ * cnfStyle Decoder - Decodes the conditional formatting style bitmask
+ * Per ECMA-376 Part 1 Section 17.4.7 (w:cnfStyle)
+ *
+ * The cnfStyle is a 12-character string where each character is '0' or '1'
+ * representing whether a particular conditional format applies.
+ */
+
+import { ConditionalFormattingType } from "../formatting/Style";
+
+/**
+ * Decoded cnfStyle flags
+ * Each flag corresponds to a conditional formatting type that may apply to a cell
+ */
+export interface CnfStyleFlags {
+  /** First row of table (header row) */
+  firstRow: boolean;
+  /** Last row of table */
+  lastRow: boolean;
+  /** First column of table */
+  firstCol: boolean;
+  /** Last column of table */
+  lastCol: boolean;
+  /** Odd vertical band (column banding) */
+  band1Vert: boolean;
+  /** Even vertical band (column banding) */
+  band2Vert: boolean;
+  /** Odd horizontal band (row banding) */
+  band1Horz: boolean;
+  /** Even horizontal band (row banding) */
+  band2Horz: boolean;
+  /** Northeast cell (top-right corner) */
+  neCell: boolean;
+  /** Northwest cell (top-left corner) */
+  nwCell: boolean;
+  /** Southeast cell (bottom-right corner) */
+  seCell: boolean;
+  /** Southwest cell (bottom-left corner) */
+  swCell: boolean;
+}
+
+/**
+ * Maps flag names to ConditionalFormattingType values
+ */
+export const CNF_TO_CONDITIONAL_MAP: Record<
+  keyof CnfStyleFlags,
+  ConditionalFormattingType
+> = {
+  firstRow: "firstRow",
+  lastRow: "lastRow",
+  firstCol: "firstCol",
+  lastCol: "lastCol",
+  band1Vert: "band1Vert",
+  band2Vert: "band2Vert",
+  band1Horz: "band1Horz",
+  band2Horz: "band2Horz",
+  neCell: "neCell",
+  nwCell: "nwCell",
+  seCell: "seCell",
+  swCell: "swCell",
+};
+
+/**
+ * Bit positions in the cnfStyle string (0-indexed from left)
+ * Per ECMA-376 Part 1 Section 17.4.7
+ */
+const BIT_POSITIONS: Record<keyof CnfStyleFlags, number> = {
+  firstRow: 0,
+  lastRow: 1,
+  firstCol: 2,
+  lastCol: 3,
+  band1Vert: 4,
+  band2Vert: 5,
+  band1Horz: 6,
+  band2Horz: 7,
+  neCell: 8,
+  nwCell: 9,
+  seCell: 10,
+  swCell: 11,
+};
+
+/**
+ * Priority order for conditional formatting resolution
+ * More specific conditions (corners) override less specific (edges, banding)
+ * Per ECMA-376, this is the order in which conditionals should be applied
+ */
+export const CONDITIONAL_PRIORITY_ORDER: (keyof CnfStyleFlags)[] = [
+  // Corner cells (most specific)
+  "nwCell",
+  "neCell",
+  "swCell",
+  "seCell",
+  // Edge rows/columns
+  "firstRow",
+  "lastRow",
+  "firstCol",
+  "lastCol",
+  // Banding (least specific)
+  "band1Horz",
+  "band2Horz",
+  "band1Vert",
+  "band2Vert",
+];
+
+/**
+ * Decodes a cnfStyle string into individual flags
+ *
+ * @param cnfStyle - 12-character binary string (e.g., "100000000000" for firstRow)
+ * @returns Decoded flags object
+ *
+ * @example
+ * ```typescript
+ * const flags = decodeCnfStyle('100000000000');
+ * console.log(flags.firstRow); // true
+ * console.log(flags.lastRow);  // false
+ * ```
+ */
+export function decodeCnfStyle(cnfStyle: string): CnfStyleFlags {
+  // Pad to 12 characters if shorter (handles legacy or truncated values)
+  // Use padEnd because the string represents left-to-right bit positions
+  const normalized = cnfStyle.padEnd(12, "0");
+
+  return {
+    firstRow: normalized.startsWith("1"),
+    lastRow: normalized[BIT_POSITIONS.lastRow] === "1",
+    firstCol: normalized[BIT_POSITIONS.firstCol] === "1",
+    lastCol: normalized[BIT_POSITIONS.lastCol] === "1",
+    band1Vert: normalized[BIT_POSITIONS.band1Vert] === "1",
+    band2Vert: normalized[BIT_POSITIONS.band2Vert] === "1",
+    band1Horz: normalized[BIT_POSITIONS.band1Horz] === "1",
+    band2Horz: normalized[BIT_POSITIONS.band2Horz] === "1",
+    neCell: normalized[BIT_POSITIONS.neCell] === "1",
+    nwCell: normalized[BIT_POSITIONS.nwCell] === "1",
+    seCell: normalized[BIT_POSITIONS.seCell] === "1",
+    swCell: normalized[BIT_POSITIONS.swCell] === "1",
+  };
+}
+
+/**
+ * Encodes CnfStyleFlags back to a binary string
+ *
+ * @param flags - Flags to encode
+ * @returns 12-character binary string
+ *
+ * @example
+ * ```typescript
+ * const cnfStyle = encodeCnfStyle({ firstRow: true, lastCol: true });
+ * console.log(cnfStyle); // '100100000000'
+ * ```
+ */
+export function encodeCnfStyle(flags: Partial<CnfStyleFlags>): string {
+  const bits = new Array(12).fill("0");
+
+  for (const [key, position] of Object.entries(BIT_POSITIONS)) {
+    if (flags[key as keyof CnfStyleFlags]) {
+      bits[position] = "1";
+    }
+  }
+
+  return bits.join("");
+}
+
+/**
+ * Gets the active conditional formatting types from a cnfStyle
+ *
+ * @param cnfStyle - The cnfStyle string to decode
+ * @returns Array of active ConditionalFormattingType values
+ *
+ * @example
+ * ```typescript
+ * const types = getActiveConditionals('110000000000');
+ * console.log(types); // ['firstRow', 'lastRow']
+ * ```
+ */
+export function getActiveConditionals(
+  cnfStyle: string
+): ConditionalFormattingType[] {
+  const flags = decodeCnfStyle(cnfStyle);
+  const active: ConditionalFormattingType[] = [];
+
+  for (const [key, isActive] of Object.entries(flags)) {
+    if (isActive) {
+      active.push(CNF_TO_CONDITIONAL_MAP[key as keyof CnfStyleFlags]);
+    }
+  }
+
+  return active;
+}
+
+/**
+ * Gets the active conditional formatting types in priority order
+ * More specific conditions come first (corners before edges before banding)
+ *
+ * @param cnfStyle - The cnfStyle string to decode
+ * @returns Array of active ConditionalFormattingType values in priority order
+ *
+ * @example
+ * ```typescript
+ * // Cell is both in first row and is the nwCell (top-left corner)
+ * const types = getActiveConditionalsInPriorityOrder('100000000100');
+ * console.log(types); // ['nwCell', 'firstRow'] - corner takes priority
+ * ```
+ */
+export function getActiveConditionalsInPriorityOrder(
+  cnfStyle: string
+): ConditionalFormattingType[] {
+  const flags = decodeCnfStyle(cnfStyle);
+  const active: ConditionalFormattingType[] = [];
+
+  for (const flagName of CONDITIONAL_PRIORITY_ORDER) {
+    if (flags[flagName]) {
+      active.push(CNF_TO_CONDITIONAL_MAP[flagName]);
+    }
+  }
+
+  return active;
+}

package/src/utils/corruptionDetection.ts

@@ -0,0 +1,345 @@
+/**
+ * Corruption Detection - Utilities to detect and diagnose XML corruption in documents
+ *
+ * This module helps users identify when they've accidentally passed XML-like strings
+ * to text methods instead of using the proper API. This is a common mistake that
+ * results in escaped XML tags being displayed as literal text in Word.
+ */
+
+import { Paragraph } from '../elements/Paragraph';
+import { Run } from '../elements/Run';
+
+/** Minimal interface for document corruption scanning (avoids circular import) */
+interface DocumentLike {
+  getAllParagraphs?(): Paragraph[];
+}
+
+/**
+ * Types of corruption that can be detected
+ */
+export type CorruptionType =
+  | 'escaped-xml'      // <w:t> style escaping
+  | 'xml-tags'         // <w:t> tags in text
+  | 'entities'         // &quot; &apos; etc.
+  | 'mixed';           // Multiple types
+
+/**
+ * Location of corruption within a document
+ */
+export interface CorruptionLocation {
+  /** Index of the paragraph containing corruption */
+  paragraphIndex: number;
+  /** Index of the run within the paragraph */
+  runIndex: number;
+  /** The corrupted text content */
+  text: string;
+  /** Type of corruption detected */
+  corruptionType: CorruptionType;
+  /** Suggested fix for the corruption */
+  suggestedFix: string;
+  /** Length of corrupted text */
+  length: number;
+}
+
+/**
+ * Comprehensive corruption report for a document
+ */
+export interface CorruptionReport {
+  /** Whether any corruption was found */
+  isCorrupted: boolean;
+  /** Total number of corrupted locations */
+  totalLocations: number;
+  /** Detailed list of corruption locations */
+  locations: CorruptionLocation[];
+  /** Human-readable summary */
+  summary: string;
+  /** Statistics about corruption types */
+  statistics: {
+    escapedXml: number;
+    xmlTags: number;
+    entities: number;
+    mixed: number;
+  };
+}
+
+/**
+ * Detects XML corruption in a document
+ *
+ * Scans all paragraphs and runs to find text that contains escaped XML
+ * or XML-like patterns that suggest the user passed XML strings to text methods.
+ *
+ * @param doc - The document to scan
+ * @returns Corruption report with locations and suggested fixes
+ *
+ * @example
+ * ```typescript
+ * const doc = await Document.load('corrupted.docx');
+ * const report = detectCorruptionInDocument(doc);
+ *
+ * if (report.isCorrupted) {
+ *   console.log(report.summary);
+ *   report.locations.forEach(loc => {
+ *     console.log(`Paragraph ${loc.paragraphIndex}, Run ${loc.runIndex}: ${loc.suggestedFix}`);
+ *   });
+ * }
+ * ```
+ */
+export function detectCorruptionInDocument(doc: DocumentLike): CorruptionReport {
+  const locations: CorruptionLocation[] = [];
+  const stats = {
+    escapedXml: 0,
+    xmlTags: 0,
+    entities: 0,
+    mixed: 0,
+  };
+
+  // Get all paragraphs from the document
+  const paragraphs = doc.getAllParagraphs ? doc.getAllParagraphs() : [];
+
+  // Scan each paragraph
+  for (let pIdx = 0; pIdx < paragraphs.length; pIdx++) {
+    const paragraph = paragraphs[pIdx];
+    if (!paragraph || !(paragraph instanceof Paragraph)) {
+      continue;
+    }
+
+    // Get runs from paragraph
+    const runs = paragraph.getRuns();
+
+    // Scan each run
+    for (let rIdx = 0; rIdx < runs.length; rIdx++) {
+      const run = runs[rIdx];
+      if (!run || !(run instanceof Run)) {
+        continue;
+      }
+
+      const text = run.getText();
+      if (!text || text.length === 0) {
+        continue;
+      }
+
+      // Check for corruption in this text
+      const corruption = detectCorruptionInText(text);
+
+      if (corruption.isCorrupted) {
+        locations.push({
+          paragraphIndex: pIdx,
+          runIndex: rIdx,
+          text: text,
+          corruptionType: corruption.type,
+          suggestedFix: corruption.suggestedFix,
+          length: text.length,
+        });
+
+        // Update statistics
+        if (corruption.type === 'escaped-xml') stats.escapedXml++;
+        else if (corruption.type === 'xml-tags') stats.xmlTags++;
+        else if (corruption.type === 'entities') stats.entities++;
+        else if (corruption.type === 'mixed') stats.mixed++;
+      }
+    }
+  }
+
+  // Generate summary
+  const summary = generateSummary(locations, stats);
+
+  return {
+    isCorrupted: locations.length > 0,
+    totalLocations: locations.length,
+    locations,
+    summary,
+    statistics: stats,
+  };
+}
+
+/**
+ * Internal result from text corruption detection
+ */
+interface TextCorruptionResult {
+  isCorrupted: boolean;
+  type: CorruptionType;
+  suggestedFix: string;
+}
+
+/**
+ * Detects XML corruption in a single text string
+ *
+ * Checks for common patterns that indicate the user passed XML strings
+ * instead of plain text.
+ *
+ * @param text - Text to check
+ * @returns True if corruption detected
+ *
+ * @example
+ * ```typescript
+ * const corrupted = detectCorruptionInText('Hello &lt;w:t&gt;World');
+ * // Returns: true
+ *
+ * const clean = detectCorruptionInText('Hello World');
+ * // Returns: false
+ * ```
+ */
+export function detectCorruptionInText(text: string): TextCorruptionResult {
+  if (!text || typeof text !== 'string') {
+    return { isCorrupted: false, type: 'mixed', suggestedFix: String(text || '') };
+  }
+
+  let hasEscapedXml = false;
+  let hasXmlTags = false;
+  let hasEntities = false;
+
+  // Pattern 1: Escaped XML tags (most common corruption)
+  // Matches: &lt;w:t&gt;, &lt;/w:t&gt;, &lt;w:r&gt;, etc.
+  const escapedXmlPattern = /&lt;\/?w:[a-z]+[^&]*&gt;/i;
+  if (escapedXmlPattern.test(text)) {
+    hasEscapedXml = true;
+  }
+
+  // Pattern 2: Raw XML tags (less common, but possible)
+  // Matches: <w:t>, </w:t>, <w:r>, etc.
+  const xmlTagPattern = /<\/?w:[a-z]+[^>]*>/i;
+  if (xmlTagPattern.test(text)) {
+    hasXmlTags = true;
+  }
+
+  // Pattern 3: Escaped entities combined with Word XML attributes
+  // ONLY flag if we see Word-specific patterns, not just any entities
+  // This avoids false positives from legitimate escaped characters
+  // Matches all OOXML namespaces: w: (word), a: (drawingML), pic: (picture), r: (relationships), wp: (word drawing)
+  const wordXmlAttributePattern = /(&lt;(?:w|a|r|pic|wp|m|mc|wpc|wps|wpg|c|dgm|o|v):|xml:space=&quot;preserve&quot;)/i;
+  if (wordXmlAttributePattern.test(text)) {
+    hasEntities = true;
+  }
+
+  // Determine corruption type
+  const corruptionCount = [hasEscapedXml, hasXmlTags, hasEntities].filter(Boolean).length;
+
+  if (corruptionCount === 0) {
+    return { isCorrupted: false, type: 'mixed', suggestedFix: text };
+  }
+
+  // More precise type detection - check primary indicator first
+  let type: CorruptionType;
+  if (hasEscapedXml && (hasEntities || hasXmlTags)) {
+    // Escaped XML combined with other patterns - this is the classic corruption case
+    type = 'escaped-xml';
+  } else if (hasXmlTags && hasEntities) {
+    type = 'xml-tags';
+  } else if (corruptionCount > 1) {
+    type = 'mixed';
+  } else if (hasEscapedXml) {
+    type = 'escaped-xml';
+  } else if (hasXmlTags) {
+    type = 'xml-tags';
+  } else {
+    type = 'entities';
+  }
+
+  const suggestedFix = suggestFix(text);
+
+  return { isCorrupted: true, type, suggestedFix };
+}
+
+/**
+ * Suggests a fix for corrupted text
+ *
+ * Attempts to clean XML patterns from text to restore the intended content.
+ * Uses the same cleaning logic as cleanXmlFromText() from validation.ts.
+ *
+ * @param corruptedText - Text containing XML corruption
+ * @returns Cleaned text with XML patterns removed
+ *
+ * @example
+ * ```typescript
+ * const fixed = suggestFix('Hello &lt;w:t&gt;World&lt;/w:t&gt;');
+ * // Returns: 'Hello World'
+ * ```
+ */
+export function suggestFix(corruptedText: string): string {
+  if (!corruptedText || typeof corruptedText !== 'string') {
+    return corruptedText;
+  }
+
+  let cleaned = corruptedText;
+
+  // Step 1: Unescape XML entities first
+  cleaned = cleaned
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+
+  // Step 2: Remove Word XML tags
+  // Matches: <w:t xml:space="preserve">, </w:t>, <w:r>, etc.
+  cleaned = cleaned.replace(/<w:[^>]+>/g, '');
+  cleaned = cleaned.replace(/<\/w:[^>]+>/g, '');
+
+  // Step 3: Remove any remaining XML-like tags
+  cleaned = cleaned.replace(/<[^>]+>/g, '');
+
+  // Step 4: Clean up whitespace
+  cleaned = cleaned.replace(/\s+/g, ' ').trim();
+
+  return cleaned;
+}
+
+/**
+ * Generates a human-readable summary of corruption
+ */
+function generateSummary(
+  locations: CorruptionLocation[],
+  stats: { escapedXml: number; xmlTags: number; entities: number; mixed: number }
+): string {
+  if (locations.length === 0) {
+    return 'No corruption detected. Document is clean.';
+  }
+
+  const lines: string[] = [];
+  lines.push(`Found ${locations.length} corrupted text location(s) in the document.`);
+  lines.push('');
+  lines.push('Corruption breakdown:');
+
+  if (stats.escapedXml > 0) {
+    lines.push(`  - Escaped XML: ${stats.escapedXml} location(s)`);
+  }
+  if (stats.xmlTags > 0) {
+    lines.push(`  - XML Tags: ${stats.xmlTags} location(s)`);
+  }
+  if (stats.entities > 0) {
+    lines.push(`  - XML Entities: ${stats.entities} location(s)`);
+  }
+  if (stats.mixed > 0) {
+    lines.push(`  - Mixed: ${stats.mixed} location(s)`);
+  }
+
+  lines.push('');
+  lines.push('This corruption typically occurs when XML strings are passed to text methods.');
+  lines.push('Instead of: paragraph.addText("Text<w:t>1</w:t>")');
+  lines.push('Use: paragraph.addText("Text"); paragraph.addText("1");');
+  lines.push('');
+  lines.push('To automatically clean text, use: new Run(text, { cleanXmlFromText: true })');
+
+  return lines.join('\n');
+}
+
+/**
+ * Checks if text looks like it might be corrupted (less strict check)
+ *
+ * This is a quick check that can be used for warnings without full analysis.
+ *
+ * @param text - Text to check
+ * @returns True if text might be corrupted
+ */
+export function looksCorrupted(text: string): boolean {
+  if (!text || typeof text !== 'string') {
+    return false;
+  }
+
+  // Quick regex checks for common corruption patterns
+  return (
+    /&lt;\/?(w|r|p):[a-z]+/i.test(text) ||
+    /<\/?(w|r|p):[a-z]+/i.test(text) ||
+    /xml:space=&quot;/i.test(text)
+  );
+}

package/src/utils/dateFormatting.ts

@@ -0,0 +1,20 @@
+/**
+ * Date formatting utilities for OOXML XML generation
+ *
+ * ECMA-376 requires dates in ISO 8601 format WITHOUT milliseconds:
+ *   Valid:   "2024-01-01T12:00:00Z"
+ *   Invalid: "2024-01-01T12:00:00.000Z" (Word rejects milliseconds in w:date attributes)
+ *
+ * JavaScript's Date.toISOString() always includes milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ),
+ * so we must strip the .sss portion for all w:date attributes in tracked changes.
+ */
+
+/**
+ * Formats a Date to ISO 8601 without milliseconds for OOXML w:date attributes.
+ *
+ * @param date - Date to format
+ * @returns ISO 8601 date string without milliseconds (e.g., "2024-01-01T12:00:00Z")
+ */
+export function formatDateForXml(date: Date): string {
+  return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+}

package/src/utils/deepClone.ts

@@ -0,0 +1,78 @@
+/**
+ * Deep clone utility for safely cloning objects
+ * More efficient and type-safe than JSON.parse(JSON.stringify())
+ */
+
+/**
+ * Deep clone an object using structured cloning
+ * Preserves most object types including Date, RegExp, Map, Set, etc.
+ *
+ * For simple objects (like formatting options), this is more efficient
+ * than JSON.parse(JSON.stringify()) and doesn't lose non-serializable values.
+ *
+ * @param obj - Object to clone
+ * @returns Deep cloned copy of the object
+ *
+ * @example
+ * ```typescript
+ * const original = { bold: true, color: "FF0000", date: new Date() };
+ * const cloned = deepClone(original);
+ * cloned.bold = false;
+ * console.log(original.bold); // true (unchanged)
+ * console.log(cloned.date instanceof Date); // true (preserved)
+ * ```
+ */
+export function deepClone<T>(obj: T): T {
+  // Handle primitive types and null
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  // Handle Date
+  if (obj instanceof Date) {
+    return new Date(obj.getTime()) as T;
+  }
+
+  // Handle Array
+  if (Array.isArray(obj)) {
+    const arrCopy: unknown[] = [];
+    for (let i = 0; i < obj.length; i++) {
+      arrCopy[i] = deepClone(obj[i]);
+    }
+    return arrCopy as T;
+  }
+
+  // Handle Map
+  if (obj instanceof Map) {
+    const mapCopy = new Map();
+    obj.forEach((value, key) => {
+      mapCopy.set(deepClone(key), deepClone(value));
+    });
+    return mapCopy as T;
+  }
+
+  // Handle Set
+  if (obj instanceof Set) {
+    const setCopy = new Set();
+    obj.forEach(value => {
+      setCopy.add(deepClone(value));
+    });
+    return setCopy as T;
+  }
+
+  // Handle RegExp
+  if (obj instanceof RegExp) {
+    return new RegExp(obj.source, obj.flags) as T;
+  }
+
+  // Handle plain objects
+  const objCopy = Object.create(Object.getPrototypeOf(obj)) as Record<string, unknown>;
+  for (const key in obj) {
+    if (obj.hasOwnProperty(key)) {
+      objCopy[key] = deepClone((obj as Record<string, unknown>)[key]);
+    }
+  }
+
+  return objCopy as T;
+}
+