docxmlater 10.4.1 → 11.0.4

package/dist/esm/utils/formatting.js

@@ -0,0 +1,93 @@
+export function mergeFormatting(base, override) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (value === undefined)
+            continue;
+        if (typeof value === 'object' && !Array.isArray(value) && value !== null) {
+            result[key] = mergeFormatting(result[key] || {}, value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export function cloneFormatting(formatting) {
+    return JSON.parse(JSON.stringify(formatting));
+}
+export function hasFormatting(formatting) {
+    for (const value of Object.values(formatting)) {
+        if (value !== undefined && value !== null) {
+            return true;
+        }
+    }
+    return false;
+}
+export function cleanFormatting(formatting) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(formatting)) {
+        if (value !== undefined && value !== null) {
+            if (typeof value === 'object' && !Array.isArray(value)) {
+                const cleanedNested = cleanFormatting(value);
+                if (Object.keys(cleanedNested).length > 0) {
+                    cleaned[key] = cleanedNested;
+                }
+            }
+            else {
+                cleaned[key] = value;
+            }
+        }
+    }
+    return cleaned;
+}
+export function isEqualFormatting(format1, format2) {
+    if (format1 === format2)
+        return true;
+    if (!format1 || !format2)
+        return false;
+    const keys1 = Object.keys(format1);
+    const keys2 = Object.keys(format2);
+    if (keys1.length !== keys2.length)
+        return false;
+    for (const key of keys1) {
+        const val1 = format1[key];
+        const val2 = format2[key];
+        if ((val1 === undefined || val1 === null) && (val2 === undefined || val2 === null)) {
+            continue;
+        }
+        if ((val1 === undefined || val1 === null) !== (val2 === undefined || val2 === null)) {
+            return false;
+        }
+        if (typeof val1 === 'object' &&
+            val1 !== null &&
+            typeof val2 === 'object' &&
+            val2 !== null &&
+            !Array.isArray(val1) &&
+            !Array.isArray(val2)) {
+            if (!isEqualFormatting(val1, val2))
+                return false;
+        }
+        else if (val1 !== val2) {
+            return false;
+        }
+    }
+    return true;
+}
+export function applyDefaults(formatting, defaults) {
+    const result = { ...defaults };
+    for (const [key, value] of Object.entries(formatting)) {
+        if (value !== undefined) {
+            if (typeof value === 'object' &&
+                !Array.isArray(value) &&
+                value !== null &&
+                typeof defaults[key] === 'object') {
+                result[key] = applyDefaults(value, defaults[key]);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=formatting.js.map

package/dist/esm/utils/formatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.js","sourceRoot":"","sources":["../../../src/utils/formatting.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Formatting utilities for deep merging and cloning formatting objects\n * Used for style inheritance and applying formatting\n */\n\n/**\n * Deep merges two formatting objects, with override taking precedence\n * Used for style inheritance and applying formatting\n *\n * @param base - Base formatting object\n * @param override - Override formatting object (takes precedence)\n * @returns Merged formatting object\n *\n * @example\n * ```typescript\n * const baseFormat = { bold: true, fontSize: 24 };\n * const overrideFormat = { fontSize: 28, italic: true };\n * const result = mergeFormatting(baseFormat, overrideFormat);\n * // Result: { bold: true, fontSize: 28, italic: true }\n * ```\n */\nexport function mergeFormatting<T extends Record<string, any>>(base: T, override: Partial<T>): T {\n  const result = { ...base };\n\n  for (const [key, value] of Object.entries(override)) {\n    if (value === undefined) continue;\n\n    if (typeof value === 'object' && !Array.isArray(value) && value !== null) {\n      // Deep merge nested objects\n      result[key as keyof T] = mergeFormatting(result[key as keyof T] || ({} as any), value);\n    } else {\n      // Direct assignment for primitives\n      result[key as keyof T] = value;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Deep clones a formatting object\n * Creates a completely independent copy with no shared references\n *\n * @param formatting - Formatting object to clone\n * @returns Cloned formatting object\n *\n * @example\n * ```typescript\n * const original = { bold: true, indentation: { left: 100 } };\n * const cloned = cloneFormatting(original);\n * cloned.indentation.left = 200; // Doesn't affect original\n * ```\n */\nexport function cloneFormatting<T>(formatting: T): T {\n  return JSON.parse(JSON.stringify(formatting));\n}\n\n/**\n * Checks if a formatting object has any defined properties\n *\n * @param formatting - Formatting object to check\n * @returns True if the object has at least one defined property\n *\n * @example\n * ```typescript\n * hasFormatting({}) // false\n * hasFormatting({ bold: true }) // true\n * hasFormatting({ bold: undefined }) // false\n * ```\n */\nexport function hasFormatting(formatting: Record<string, unknown>): boolean {\n  for (const value of Object.values(formatting)) {\n    if (value !== undefined && value !== null) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * Removes undefined and null properties from a formatting object\n * Useful for cleaning up formatting before comparison or serialization\n *\n * @param formatting - Formatting object to clean\n * @returns Cleaned formatting object with no undefined/null values\n *\n * @example\n * ```typescript\n * const dirty = { bold: true, italic: undefined, fontSize: null, underline: false };\n * const clean = cleanFormatting(dirty);\n * // Result: { bold: true, underline: false }\n * ```\n */\nexport function cleanFormatting<T extends Record<string, any>>(formatting: T): Partial<T> {\n  const cleaned: Partial<T> = {};\n\n  for (const [key, value] of Object.entries(formatting)) {\n    if (value !== undefined && value !== null) {\n      if (typeof value === 'object' && !Array.isArray(value)) {\n        // Recursively clean nested objects\n        const cleanedNested = cleanFormatting(value);\n        if (Object.keys(cleanedNested).length > 0) {\n          cleaned[key as keyof T] = cleanedNested as any;\n        }\n      } else {\n        cleaned[key as keyof T] = value;\n      }\n    }\n  }\n\n  return cleaned;\n}\n\n/**\n * Compares two formatting objects for equality\n * Performs deep comparison of all properties\n *\n * @param format1 - First formatting object\n * @param format2 - Second formatting object\n * @returns True if the formatting objects are equal\n *\n * @example\n * ```typescript\n * const a = { bold: true, fontSize: 24 };\n * const b = { bold: true, fontSize: 24 };\n * const c = { bold: true, fontSize: 28 };\n * isEqualFormatting(a, b) // true\n * isEqualFormatting(a, c) // false\n * ```\n */\nexport function isEqualFormatting(\n  format1: Record<string, unknown>,\n  format2: Record<string, unknown>\n): boolean {\n  // Quick reference check\n  if (format1 === format2) return true;\n\n  // Null/undefined checks\n  if (!format1 || !format2) return false;\n\n  // Get all keys from both objects\n  const keys1 = Object.keys(format1);\n  const keys2 = Object.keys(format2);\n\n  // Check if they have the same number of properties\n  if (keys1.length !== keys2.length) return false;\n\n  // Check all properties\n  for (const key of keys1) {\n    const val1 = format1[key];\n    const val2 = format2[key];\n\n    // Both undefined/null - considered equal\n    if ((val1 === undefined || val1 === null) && (val2 === undefined || val2 === null)) {\n      continue;\n    }\n\n    // One is undefined/null and the other isn't\n    if ((val1 === undefined || val1 === null) !== (val2 === undefined || val2 === null)) {\n      return false;\n    }\n\n    // Check nested objects\n    if (\n      typeof val1 === 'object' &&\n      val1 !== null &&\n      typeof val2 === 'object' &&\n      val2 !== null &&\n      !Array.isArray(val1) &&\n      !Array.isArray(val2)\n    ) {\n      if (!isEqualFormatting(val1 as Record<string, unknown>, val2 as Record<string, unknown>))\n        return false;\n    } else if (val1 !== val2) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Applies default values to a formatting object for any undefined properties\n *\n * @param formatting - Formatting object to apply defaults to\n * @param defaults - Default values\n * @returns Formatting object with defaults applied\n *\n * @example\n * ```typescript\n * const format = { bold: true };\n * const defaults = { bold: false, italic: false, fontSize: 24 };\n * const result = applyDefaults(format, defaults);\n * // Result: { bold: true, italic: false, fontSize: 24 }\n * ```\n */\nexport function applyDefaults<T extends Record<string, any>>(\n  formatting: Partial<T>,\n  defaults: T\n): T {\n  const result = { ...defaults };\n\n  for (const [key, value] of Object.entries(formatting)) {\n    if (value !== undefined) {\n      if (\n        typeof value === 'object' &&\n        !Array.isArray(value) &&\n        value !== null &&\n        typeof defaults[key] === 'object'\n      ) {\n        // Deep merge nested objects\n        result[key as keyof T] = applyDefaults(value, defaults[key]);\n      } else {\n        result[key as keyof T] = value;\n      }\n    }\n  }\n\n  return result;\n}\n"]}

package/dist/esm/utils/list-detection.js

@@ -0,0 +1,148 @@
+export const TYPED_LIST_PATTERNS = {
+    decimal: /^(\d+)[.)]\s+/,
+    lowerLetter: /^([a-z])[.)]\s+/,
+    upperLetter: /^([A-Z])[.)]\s+/,
+    lowerRoman: /^((?:i{1,3}|iv|vi{0,3}|ix|x{1,3}))[.)]\s+/i,
+    bullet: /^[•●○◦▪■□]\s+/,
+    dash: /^[-–—]\s+/,
+    arrow: /^[►▸▶→]\s+/,
+};
+export const PATTERN_TO_CATEGORY = {
+    decimal: 'numbered',
+    lowerLetter: 'numbered',
+    upperLetter: 'numbered',
+    lowerRoman: 'numbered',
+    bullet: 'bullet',
+    dash: 'bullet',
+    arrow: 'bullet',
+};
+export const FORMAT_TO_LEVEL = {
+    decimal: 0,
+    lowerLetter: 1,
+    upperLetter: 1,
+    lowerRoman: 2,
+    upperRoman: 2,
+    bullet: 0,
+    dash: 0,
+    arrow: 0,
+};
+export function getLevelFromFormat(format) {
+    if (!format)
+        return 0;
+    return FORMAT_TO_LEVEL[format] ?? 0;
+}
+const WORD_BASE_INDENT = 720;
+const INDENT_PER_LEVEL = 360;
+export function inferLevelFromIndentation(indentTwips) {
+    if (indentTwips < WORD_BASE_INDENT)
+        return 0;
+    return Math.floor((indentTwips - WORD_BASE_INDENT) / INDENT_PER_LEVEL);
+}
+export function inferLevelFromRelativeIndentation(relativeIndentTwips) {
+    if (relativeIndentTwips <= 0)
+        return 0;
+    return Math.min(8, Math.floor(relativeIndentTwips / INDENT_PER_LEVEL));
+}
+export function detectTypedPrefix(text) {
+    for (const [format, regex] of Object.entries(TYPED_LIST_PATTERNS)) {
+        const match = text.match(regex);
+        if (match) {
+            if (format === 'lowerLetter' || format === 'upperLetter') {
+                const remaining = text.substring(match[0].length);
+                if (/^[A-Za-z]\./.test(remaining)) {
+                    continue;
+                }
+            }
+            return {
+                prefix: match[0],
+                format: format,
+                category: PATTERN_TO_CATEGORY[format] ?? 'none',
+            };
+        }
+    }
+    return { prefix: null, format: null, category: 'none' };
+}
+export function getParagraphIndentation(paragraph) {
+    const formatting = paragraph.getFormatting();
+    return formatting?.indentation?.left ?? 0;
+}
+export function detectListType(paragraph) {
+    const text = paragraph.getText();
+    const indentation = getParagraphIndentation(paragraph);
+    const numbering = paragraph.getNumbering();
+    if (numbering?.numId !== undefined && numbering.numId !== 0) {
+        return {
+            category: 'numbered',
+            isWordList: true,
+            typedPrefix: null,
+            inferredLevel: numbering.level ?? 0,
+            format: null,
+            numId: numbering.numId,
+            ilvl: numbering.level ?? 0,
+            indentationTwips: indentation,
+        };
+    }
+    const typed = detectTypedPrefix(text);
+    if (typed.prefix) {
+        return {
+            category: typed.category,
+            isWordList: false,
+            typedPrefix: typed.prefix,
+            inferredLevel: getLevelFromFormat(typed.format),
+            format: typed.format,
+            numId: null,
+            ilvl: null,
+            indentationTwips: indentation,
+        };
+    }
+    return {
+        category: 'none',
+        isWordList: false,
+        typedPrefix: null,
+        inferredLevel: 0,
+        format: null,
+        numId: null,
+        ilvl: null,
+        indentationTwips: indentation,
+    };
+}
+export function validateListSequence(paragraphs) {
+    const warnings = [];
+    let lastDecimal = 0;
+    let lastLetter = '';
+    for (const { detection } of paragraphs) {
+        if (!detection.typedPrefix || detection.category !== 'numbered')
+            continue;
+        const match = /^(\d+|[a-zA-Z]+)/.exec(detection.typedPrefix);
+        if (!match?.[1])
+            continue;
+        const marker = match[1];
+        if (/^\d+$/.test(marker)) {
+            const num = parseInt(marker, 10);
+            if (lastDecimal > 0 && num !== lastDecimal + 1 && num !== 1) {
+                warnings.push(`Unexpected number sequence: ${lastDecimal} → ${num}`);
+            }
+            lastDecimal = num;
+        }
+        if (/^[a-z]$/i.test(marker)) {
+            const letter = marker.toLowerCase();
+            if (lastLetter && letter.charCodeAt(0) !== lastLetter.charCodeAt(0) + 1 && letter !== 'a') {
+                warnings.push(`Unexpected letter sequence: ${lastLetter} → ${letter}`);
+            }
+            lastLetter = letter;
+        }
+    }
+    return { valid: warnings.length === 0, warnings };
+}
+export function getListCategoryFromFormat(format) {
+    if (!format)
+        return 'none';
+    if (['bullet', 'dash', 'arrow'].includes(format)) {
+        return 'bullet';
+    }
+    if (['decimal', 'lowerLetter', 'upperLetter', 'lowerRoman', 'upperRoman'].includes(format)) {
+        return 'numbered';
+    }
+    return 'none';
+}
+//# sourceMappingURL=list-detection.js.map

package/dist/esm/utils/list-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-detection.js","sourceRoot":"","sources":["../../../src/utils/list-detection.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * List Detection Utilities for docxmlater\n *\n * Provides functions to detect typed list prefixes and analyze\n * paragraph list properties.\n */\n\nimport type { Paragraph } from '../elements/Paragraph.js';\nimport type {\n  ListCategory,\n  ListDetectionResult,\n  NumberFormat,\n  BulletFormat,\n} from '../types/list-types.js';\n\n// =============================================================================\n// CONSTANTS\n// =============================================================================\n\n/**\n * Regex patterns for typed list prefixes.\n * Order matters: more specific patterns first.\n */\nexport const TYPED_LIST_PATTERNS: Record<string, RegExp> = {\n  // Numbered patterns (capture the marker for validation)\n  decimal: /^(\\d+)[.)]\\s+/,\n  lowerLetter: /^([a-z])[.)]\\s+/,\n  upperLetter: /^([A-Z])[.)]\\s+/,\n  lowerRoman: /^((?:i{1,3}|iv|vi{0,3}|ix|x{1,3}))[.)]\\s+/i,\n\n  // Bullet patterns\n  bullet: /^[•●○◦▪■□]\\s+/,\n  dash: /^[-–—]\\s+/,\n  arrow: /^[►▸▶→]\\s+/,\n};\n\n/** Map pattern names to categories */\nexport const PATTERN_TO_CATEGORY: Record<string, ListCategory> = {\n  decimal: 'numbered',\n  lowerLetter: 'numbered',\n  upperLetter: 'numbered',\n  lowerRoman: 'numbered',\n  bullet: 'bullet',\n  dash: 'bullet',\n  arrow: 'bullet',\n};\n\n/**\n * Map typed prefix format to Word numbering level.\n * Word's default multilevel list uses:\n *   Level 0: 1., 2., 3. (decimal)\n *   Level 1: a., b., c. (lowerLetter)\n *   Level 2: i., ii., iii. (lowerRoman)\n */\nexport const FORMAT_TO_LEVEL: Record<string, number> = {\n  decimal: 0, // 1., 2., 3.\n  lowerLetter: 1, // a., b., c.\n  upperLetter: 1, // A., B., C.\n  lowerRoman: 2, // i., ii., iii.\n  upperRoman: 2, // I., II., III.\n  bullet: 0, // Top-level bullet (filled circle)\n  dash: 0, // Top-level dash marker\n  arrow: 0, // Top-level arrow marker\n};\n\n/**\n * Get the Word numbering level for a given format.\n * Returns 0 (top level) for decimal or unknown formats.\n */\nexport function getLevelFromFormat(format: string | null): number {\n  if (!format) return 0;\n  return FORMAT_TO_LEVEL[format] ?? 0;\n}\n\n/**\n * Word standard indentation values in twips.\n * Level 0: 720 twips (0.5 inch) left indent\n * Level 1: 1080 twips (0.75 inch) left indent\n * Level 2: 1440 twips (1 inch) left indent\n * Each subsequent level adds 360 twips.\n */\nconst WORD_BASE_INDENT = 720;\nconst INDENT_PER_LEVEL = 360;\n\n// =============================================================================\n// CORE DETECTION FUNCTIONS\n// =============================================================================\n\n/**\n * Infer list level from indentation.\n * Uses standard Word indentation: 720 twips for level 0, +360 per level.\n */\nexport function inferLevelFromIndentation(indentTwips: number): number {\n  if (indentTwips < WORD_BASE_INDENT) return 0;\n  return Math.floor((indentTwips - WORD_BASE_INDENT) / INDENT_PER_LEVEL);\n}\n\n/**\n * Infer list level from relative indentation (baseline already subtracted).\n * Used when normalizing lists within a table cell where the baseline\n * indentation varies per cell.\n */\nexport function inferLevelFromRelativeIndentation(relativeIndentTwips: number): number {\n  if (relativeIndentTwips <= 0) return 0;\n  return Math.min(8, Math.floor(relativeIndentTwips / INDENT_PER_LEVEL));\n}\n\n/**\n * Detect typed list prefix in text.\n * Returns the matched prefix and format type.\n *\n * Special handling for abbreviations:\n * - Single letter prefixes (A., B., P.) are NOT treated as list markers\n *   if the remaining text also starts with a letter+period pattern,\n *   indicating an abbreviation like \"P.O. Box\", \"U.S. Army\", etc.\n */\nexport function detectTypedPrefix(text: string): {\n  prefix: string | null;\n  format: NumberFormat | BulletFormat | null;\n  category: ListCategory;\n} {\n  for (const [format, regex] of Object.entries(TYPED_LIST_PATTERNS)) {\n    const match = text.match(regex);\n    if (match) {\n      // Special check for single-letter patterns (lowerLetter, upperLetter)\n      // to avoid false positives on abbreviations like \"P.O. Box\", \"U.S.\", \"A.M.\"\n      if (format === 'lowerLetter' || format === 'upperLetter') {\n        const remaining = text.substring(match[0].length);\n        // If remaining text starts with another letter followed by period,\n        // this is likely an abbreviation, not a list marker\n        if (/^[A-Za-z]\\./.test(remaining)) {\n          continue; // Skip this pattern, try others\n        }\n      }\n\n      return {\n        prefix: match[0],\n        format: format as NumberFormat | BulletFormat,\n        category: PATTERN_TO_CATEGORY[format] ?? 'none',\n      };\n    }\n  }\n\n  return { prefix: null, format: null, category: 'none' };\n}\n\n/**\n * Get the left indentation from a paragraph in twips.\n */\nexport function getParagraphIndentation(paragraph: Paragraph): number {\n  const formatting = paragraph.getFormatting();\n  return formatting?.indentation?.left ?? 0;\n}\n\n/**\n * Main detection function: analyze a single paragraph for list properties.\n */\nexport function detectListType(paragraph: Paragraph): ListDetectionResult {\n  const text = paragraph.getText();\n  const indentation = getParagraphIndentation(paragraph);\n  const numbering = paragraph.getNumbering();\n\n  // Priority 1: Real Word list with <w:numPr>\n  if (numbering?.numId !== undefined && numbering.numId !== 0) {\n    return {\n      category: 'numbered', // Default, caller can refine with NumberingManager lookup\n      isWordList: true,\n      typedPrefix: null,\n      inferredLevel: numbering.level ?? 0,\n      format: null, // Would need numbering.xml lookup\n      numId: numbering.numId,\n      ilvl: numbering.level ?? 0,\n      indentationTwips: indentation,\n    };\n  }\n\n  // Priority 2: Typed prefix detection\n  const typed = detectTypedPrefix(text);\n  if (typed.prefix) {\n    return {\n      category: typed.category,\n      isWordList: false,\n      typedPrefix: typed.prefix,\n      // Use FORMAT to determine level, not indentation!\n      // decimal=0, lowerLetter=1, lowerRoman=2\n      inferredLevel: getLevelFromFormat(typed.format),\n      format: typed.format,\n      numId: null,\n      ilvl: null,\n      indentationTwips: indentation,\n    };\n  }\n\n  // Priority 3: Not a list\n  return {\n    category: 'none',\n    isWordList: false,\n    typedPrefix: null,\n    inferredLevel: 0,\n    format: null,\n    numId: null,\n    ilvl: null,\n    indentationTwips: indentation,\n  };\n}\n\n/**\n * Validate that a typed prefix sequence is reasonable.\n * E.g., \"1. 2. 3.\" is valid, \"1. 5. 2.\" is suspicious.\n */\nexport function validateListSequence(\n  paragraphs: { detection: ListDetectionResult; text: string }[]\n): { valid: boolean; warnings: string[] } {\n  const warnings: string[] = [];\n  let lastDecimal = 0;\n  let lastLetter = '';\n\n  for (const { detection } of paragraphs) {\n    if (!detection.typedPrefix || detection.category !== 'numbered') continue;\n\n    const match = /^(\\d+|[a-zA-Z]+)/.exec(detection.typedPrefix);\n    if (!match?.[1]) continue;\n\n    const marker = match[1];\n\n    // Check decimal sequence\n    if (/^\\d+$/.test(marker)) {\n      const num = parseInt(marker, 10);\n      if (lastDecimal > 0 && num !== lastDecimal + 1 && num !== 1) {\n        warnings.push(`Unexpected number sequence: ${lastDecimal} → ${num}`);\n      }\n      lastDecimal = num;\n    }\n\n    // Check letter sequence\n    if (/^[a-z]$/i.test(marker)) {\n      const letter = marker.toLowerCase();\n      if (lastLetter && letter.charCodeAt(0) !== lastLetter.charCodeAt(0) + 1 && letter !== 'a') {\n        warnings.push(`Unexpected letter sequence: ${lastLetter} → ${letter}`);\n      }\n      lastLetter = letter;\n    }\n  }\n\n  return { valid: warnings.length === 0, warnings };\n}\n\n/**\n * Determine the list category for a given numId by checking the abstractNum.\n * This requires access to the NumberingManager.\n */\nexport function getListCategoryFromFormat(format: string | undefined): ListCategory {\n  if (!format) return 'none';\n\n  if (['bullet', 'dash', 'arrow'].includes(format)) {\n    return 'bullet';\n  }\n\n  if (['decimal', 'lowerLetter', 'upperLetter', 'lowerRoman', 'upperRoman'].includes(format)) {\n    return 'numbered';\n  }\n\n  return 'none';\n}\n"]}

package/dist/esm/utils/logger.js

@@ -0,0 +1,205 @@
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["DEBUG"] = "debug";
+    LogLevel["INFO"] = "info";
+    LogLevel["WARN"] = "warn";
+    LogLevel["ERROR"] = "error";
+})(LogLevel || (LogLevel = {}));
+export class ConsoleLogger {
+    minLevel;
+    showTimestamp;
+    constructor(minLevel = LogLevel.WARN, options) {
+        this.minLevel = minLevel;
+        this.showTimestamp = options?.showTimestamp ?? true;
+    }
+    debug(message, context) {
+        if (this.shouldLog(LogLevel.DEBUG)) {
+            console.debug(this.formatMessage(LogLevel.DEBUG, message, context));
+        }
+    }
+    info(message, context) {
+        if (this.shouldLog(LogLevel.INFO)) {
+            console.info(this.formatMessage(LogLevel.INFO, message, context));
+        }
+    }
+    warn(message, context) {
+        if (this.shouldLog(LogLevel.WARN)) {
+            console.warn(this.formatMessage(LogLevel.WARN, message, context));
+        }
+    }
+    error(message, context) {
+        if (this.shouldLog(LogLevel.ERROR)) {
+            console.error(this.formatMessage(LogLevel.ERROR, message, context));
+        }
+    }
+    shouldLog(level) {
+        const levels = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR];
+        const minIndex = levels.indexOf(this.minLevel);
+        const currentIndex = levels.indexOf(level);
+        return currentIndex >= minIndex;
+    }
+    formatMessage(level, message, context) {
+        const parts = [];
+        if (this.showTimestamp) {
+            const timestamp = new Date().toISOString().slice(11, 23);
+            parts.push(timestamp);
+        }
+        parts.push(`[${level.toUpperCase().padEnd(5)}]`);
+        if (context?.source) {
+            parts.push(`[${context.source}]`);
+        }
+        parts.push(message);
+        if (context && Object.keys(context).length > 0) {
+            const contextWithoutSource = { ...context };
+            delete contextWithoutSource.source;
+            if (Object.keys(contextWithoutSource).length > 0) {
+                const contextStr = this.formatContext(contextWithoutSource);
+                if (contextStr) {
+                    parts.push(contextStr);
+                }
+            }
+        }
+        return parts.join(' ');
+    }
+    formatContext(context) {
+        const pairs = [];
+        for (const [key, value] of Object.entries(context)) {
+            if (value === undefined || value === null)
+                continue;
+            if (typeof value === 'object' && !Array.isArray(value)) {
+                pairs.push(`${key}=${JSON.stringify(value)}`);
+            }
+            else if (Array.isArray(value)) {
+                pairs.push(`${key}=[${value.length}]`);
+            }
+            else {
+                pairs.push(`${key}=${value}`);
+            }
+        }
+        return pairs.length > 0 ? pairs.join(' ') : '';
+    }
+}
+export class SilentLogger {
+    debug() {
+    }
+    info() {
+    }
+    warn() {
+    }
+    error() {
+    }
+}
+export class CollectingLogger {
+    logs = [];
+    debug(message, context) {
+        this.addLog(LogLevel.DEBUG, message, context);
+    }
+    info(message, context) {
+        this.addLog(LogLevel.INFO, message, context);
+    }
+    warn(message, context) {
+        this.addLog(LogLevel.WARN, message, context);
+    }
+    error(message, context) {
+        this.addLog(LogLevel.ERROR, message, context);
+    }
+    addLog(level, message, context) {
+        this.logs.push({
+            timestamp: new Date(),
+            level,
+            message,
+            context,
+        });
+    }
+    getLogs() {
+        return [...this.logs];
+    }
+    getLogsByLevel(level) {
+        return this.logs.filter((log) => log.level === level);
+    }
+    clear() {
+        this.logs = [];
+    }
+    getCount(level) {
+        if (level) {
+            return this.logs.filter((log) => log.level === level).length;
+        }
+        return this.logs.length;
+    }
+}
+export const defaultLogger = {
+    debug(message, context) {
+        getGlobalLogger().debug(message, context);
+    },
+    info(message, context) {
+        getGlobalLogger().info(message, context);
+    },
+    warn(message, context) {
+        getGlobalLogger().warn(message, context);
+    },
+    error(message, context) {
+        getGlobalLogger().error(message, context);
+    },
+};
+export function createScopedLogger(logger, source) {
+    return {
+        debug(message, context) {
+            logger.debug(message, { ...context, source });
+        },
+        info(message, context) {
+            logger.info(message, { ...context, source });
+        },
+        warn(message, context) {
+            logger.warn(message, { ...context, source });
+        },
+        error(message, context) {
+            logger.error(message, { ...context, source });
+        },
+    };
+}
+function parseLogLevel(level) {
+    if (!level)
+        return undefined;
+    const normalized = level.toLowerCase();
+    switch (normalized) {
+        case 'debug':
+            return LogLevel.DEBUG;
+        case 'info':
+            return LogLevel.INFO;
+        case 'warn':
+            return LogLevel.WARN;
+        case 'error':
+            return LogLevel.ERROR;
+        default:
+            return undefined;
+    }
+}
+function createLoggerFromEnv() {
+    const debugEnv = process.env.DEBUG || '';
+    if (debugEnv.includes('docxmlater')) {
+        return new ConsoleLogger(LogLevel.DEBUG);
+    }
+    const envLevel = process.env.DOCXMLATER_LOG_LEVEL?.toLowerCase();
+    if (envLevel === 'silent') {
+        return new SilentLogger();
+    }
+    const parsedLevel = parseLogLevel(envLevel);
+    if (parsedLevel) {
+        return new ConsoleLogger(parsedLevel);
+    }
+    return new SilentLogger();
+}
+let globalLogger = createLoggerFromEnv();
+export function setGlobalLogger(logger) {
+    globalLogger = logger;
+}
+export function getGlobalLogger() {
+    return globalLogger;
+}
+export function resetGlobalLogger() {
+    globalLogger = createLoggerFromEnv();
+}
+export function createComponentLogger(componentName) {
+    return createScopedLogger(getGlobalLogger(), componentName);
+}
+//# sourceMappingURL=logger.js.map

package/dist/esm/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/utils/logger.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Logging interface for docXMLater\n * Allows library consumers to control logging behavior\n */\n\n/**\n * Log severity levels\n */\nexport enum LogLevel {\n  /** Debugging information (most verbose) */\n  DEBUG = 'debug',\n  /** Informational messages */\n  INFO = 'info',\n  /** Warning messages - potential issues that don't prevent operation */\n  WARN = 'warn',\n  /** Error messages - serious issues that may cause failures */\n  ERROR = 'error',\n}\n\n/**\n * Log entry structure\n */\nexport interface LogEntry {\n  /** Timestamp when log was created */\n  timestamp: Date;\n  /** Severity level */\n  level: LogLevel;\n  /** Log message */\n  message: string;\n  /** Optional context data */\n  context?: Record<string, any>;\n  /** Source component that generated the log */\n  source?: string;\n}\n\n/**\n * Logger interface that consumers can implement\n * Provides full control over how logs are handled\n */\nexport interface ILogger {\n  /**\n   * Log a debug message\n   * @param message - Debug message\n   * @param context - Optional context data\n   */\n  debug(message: string, context?: Record<string, any>): void;\n\n  /**\n   * Log an informational message\n   * @param message - Info message\n   * @param context - Optional context data\n   */\n  info(message: string, context?: Record<string, any>): void;\n\n  /**\n   * Log a warning message\n   * @param message - Warning message\n   * @param context - Optional context data\n   */\n  warn(message: string, context?: Record<string, any>): void;\n\n  /**\n   * Log an error message\n   * @param message - Error message\n   * @param context - Optional context data\n   */\n  error(message: string, context?: Record<string, any>): void;\n}\n\n/**\n * Console-based logger implementation\n * Uses standard console methods for output with timestamps and source prefixes\n */\nexport class ConsoleLogger implements ILogger {\n  private showTimestamp: boolean;\n\n  constructor(\n    private minLevel: LogLevel = LogLevel.WARN,\n    options?: { showTimestamp?: boolean }\n  ) {\n    this.showTimestamp = options?.showTimestamp ?? true;\n  }\n\n  debug(message: string, context?: Record<string, any>): void {\n    if (this.shouldLog(LogLevel.DEBUG)) {\n      console.debug(this.formatMessage(LogLevel.DEBUG, message, context));\n    }\n  }\n\n  info(message: string, context?: Record<string, any>): void {\n    if (this.shouldLog(LogLevel.INFO)) {\n      console.info(this.formatMessage(LogLevel.INFO, message, context));\n    }\n  }\n\n  warn(message: string, context?: Record<string, any>): void {\n    if (this.shouldLog(LogLevel.WARN)) {\n      console.warn(this.formatMessage(LogLevel.WARN, message, context));\n    }\n  }\n\n  error(message: string, context?: Record<string, any>): void {\n    if (this.shouldLog(LogLevel.ERROR)) {\n      console.error(this.formatMessage(LogLevel.ERROR, message, context));\n    }\n  }\n\n  private shouldLog(level: LogLevel): boolean {\n    const levels = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR];\n    const minIndex = levels.indexOf(this.minLevel);\n    const currentIndex = levels.indexOf(level);\n    return currentIndex >= minIndex;\n  }\n\n  private formatMessage(level: LogLevel, message: string, context?: Record<string, any>): string {\n    const parts: string[] = [];\n\n    // Add timestamp if enabled\n    if (this.showTimestamp) {\n      const timestamp = new Date().toISOString().slice(11, 23); // HH:mm:ss.SSS\n      parts.push(timestamp);\n    }\n\n    // Add level tag\n    parts.push(`[${level.toUpperCase().padEnd(5)}]`);\n\n    // Add source if present\n    if (context?.source) {\n      parts.push(`[${context.source}]`);\n    }\n\n    // Add message\n    parts.push(message);\n\n    // Add context (excluding source which is already shown)\n    if (context && Object.keys(context).length > 0) {\n      const contextWithoutSource = { ...context };\n      delete contextWithoutSource.source;\n      if (Object.keys(contextWithoutSource).length > 0) {\n        // Format context as key=value pairs for readability\n        const contextStr = this.formatContext(contextWithoutSource);\n        if (contextStr) {\n          parts.push(contextStr);\n        }\n      }\n    }\n\n    return parts.join(' ');\n  }\n\n  private formatContext(context: Record<string, any>): string {\n    const pairs: string[] = [];\n    for (const [key, value] of Object.entries(context)) {\n      if (value === undefined || value === null) continue;\n      if (typeof value === 'object' && !Array.isArray(value)) {\n        // Nested object - use compact JSON\n        pairs.push(`${key}=${JSON.stringify(value)}`);\n      } else if (Array.isArray(value)) {\n        pairs.push(`${key}=[${value.length}]`);\n      } else {\n        pairs.push(`${key}=${value}`);\n      }\n    }\n    return pairs.length > 0 ? pairs.join(' ') : '';\n  }\n}\n\n/**\n * Silent logger that discards all log messages\n * Useful for testing or when logging is not desired\n */\nexport class SilentLogger implements ILogger {\n  debug(): void {\n    // No-op\n  }\n\n  info(): void {\n    // No-op\n  }\n\n  warn(): void {\n    // No-op\n  }\n\n  error(): void {\n    // No-op\n  }\n}\n\n/**\n * Collecting logger that stores log entries in memory\n * Useful for testing and diagnostics\n */\nexport class CollectingLogger implements ILogger {\n  private logs: LogEntry[] = [];\n\n  debug(message: string, context?: Record<string, any>): void {\n    this.addLog(LogLevel.DEBUG, message, context);\n  }\n\n  info(message: string, context?: Record<string, any>): void {\n    this.addLog(LogLevel.INFO, message, context);\n  }\n\n  warn(message: string, context?: Record<string, any>): void {\n    this.addLog(LogLevel.WARN, message, context);\n  }\n\n  error(message: string, context?: Record<string, any>): void {\n    this.addLog(LogLevel.ERROR, message, context);\n  }\n\n  private addLog(level: LogLevel, message: string, context?: Record<string, any>): void {\n    this.logs.push({\n      timestamp: new Date(),\n      level,\n      message,\n      context,\n    });\n  }\n\n  /**\n   * Get all collected log entries\n   */\n  getLogs(): readonly LogEntry[] {\n    return [...this.logs];\n  }\n\n  /**\n   * Get logs filtered by level\n   */\n  getLogsByLevel(level: LogLevel): readonly LogEntry[] {\n    return this.logs.filter((log) => log.level === level);\n  }\n\n  /**\n   * Clear all collected logs\n   */\n  clear(): void {\n    this.logs = [];\n  }\n\n  /**\n   * Get count of logs by level\n   */\n  getCount(level?: LogLevel): number {\n    if (level) {\n      return this.logs.filter((log) => log.level === level).length;\n    }\n    return this.logs.length;\n  }\n}\n\n/**\n * Default logger instance\n * Delegates to the global logger, respecting setGlobalLogger() and environment variables\n */\nexport const defaultLogger: ILogger = {\n  debug(message: string, context?: Record<string, any>): void {\n    getGlobalLogger().debug(message, context);\n  },\n  info(message: string, context?: Record<string, any>): void {\n    getGlobalLogger().info(message, context);\n  },\n  warn(message: string, context?: Record<string, any>): void {\n    getGlobalLogger().warn(message, context);\n  },\n  error(message: string, context?: Record<string, any>): void {\n    getGlobalLogger().error(message, context);\n  },\n};\n\n/**\n * Creates a scoped logger that adds source information\n * @param logger - Base logger\n * @param source - Source component name\n * @returns Scoped logger with source context\n */\nexport function createScopedLogger(logger: ILogger, source: string): ILogger {\n  return {\n    debug(message: string, context?: Record<string, any>): void {\n      logger.debug(message, { ...context, source });\n    },\n    info(message: string, context?: Record<string, any>): void {\n      logger.info(message, { ...context, source });\n    },\n    warn(message: string, context?: Record<string, any>): void {\n      logger.warn(message, { ...context, source });\n    },\n    error(message: string, context?: Record<string, any>): void {\n      logger.error(message, { ...context, source });\n    },\n  };\n}\n\n/**\n * Parse log level from string\n * @param level - Log level string (case-insensitive)\n * @returns LogLevel or undefined if invalid\n */\nfunction parseLogLevel(level: string | undefined): LogLevel | undefined {\n  if (!level) return undefined;\n  const normalized = level.toLowerCase();\n  switch (normalized) {\n    case 'debug':\n      return LogLevel.DEBUG;\n    case 'info':\n      return LogLevel.INFO;\n    case 'warn':\n      return LogLevel.WARN;\n    case 'error':\n      return LogLevel.ERROR;\n    default:\n      return undefined;\n  }\n}\n\n/**\n * Create a logger based on environment variables\n *\n * Environment variables (in order of precedence):\n * - DEBUG=docxmlater or DEBUG=docxmlater:* - Enables DEBUG level\n * - DOCXMLATER_LOG_LEVEL=debug|info|warn|error|silent - Sets specific level\n *\n * @returns Logger configured from environment, or SilentLogger if not configured\n */\nfunction createLoggerFromEnv(): ILogger {\n  // Check DEBUG environment variable first (highest precedence for debug mode)\n  const debugEnv = process.env.DEBUG || '';\n  if (debugEnv.includes('docxmlater')) {\n    return new ConsoleLogger(LogLevel.DEBUG);\n  }\n\n  // Check DOCXMLATER_LOG_LEVEL environment variable\n  const envLevel = process.env.DOCXMLATER_LOG_LEVEL?.toLowerCase();\n  if (envLevel === 'silent') {\n    return new SilentLogger();\n  }\n\n  const parsedLevel = parseLogLevel(envLevel);\n  if (parsedLevel) {\n    return new ConsoleLogger(parsedLevel);\n  }\n\n  // Default: silent (no logging unless explicitly enabled)\n  return new SilentLogger();\n}\n\n// Global logger instance - initialized from environment\nlet globalLogger: ILogger = createLoggerFromEnv();\n\n/**\n * Set the global logger instance\n * Use this to configure logging programmatically\n *\n * @example\n * ```typescript\n * import { setGlobalLogger, ConsoleLogger, LogLevel } from 'docxmlater';\n *\n * // Enable info-level logging\n * setGlobalLogger(new ConsoleLogger(LogLevel.INFO));\n * ```\n *\n * @param logger - Logger instance to use globally\n */\nexport function setGlobalLogger(logger: ILogger): void {\n  globalLogger = logger;\n}\n\n/**\n * Get the global logger instance\n * Used internally by framework components\n *\n * @returns Current global logger\n */\nexport function getGlobalLogger(): ILogger {\n  return globalLogger;\n}\n\n/**\n * Reset the global logger to its default (environment-based) configuration\n * Useful for testing cleanup\n */\nexport function resetGlobalLogger(): void {\n  globalLogger = createLoggerFromEnv();\n}\n\n/**\n * Creates a component-scoped logger using the global logger.\n * This is a convenience function that combines getGlobalLogger() and createScopedLogger()\n * into a single call, reducing boilerplate in component files.\n *\n * @param componentName - Name of the component (appears in log output)\n * @returns Scoped logger instance\n *\n * @example\n * ```typescript\n * // Instead of:\n * function getLogger(): ILogger {\n *   return createScopedLogger(getGlobalLogger(), 'MyComponent');\n * }\n *\n * // You can use:\n * const logger = createComponentLogger('MyComponent');\n *\n * // Or for lazy initialization:\n * const getLogger = () => createComponentLogger('MyComponent');\n * ```\n */\nexport function createComponentLogger(componentName: string): ILogger {\n  return createScopedLogger(getGlobalLogger(), componentName);\n}\n"]}

package/dist/esm/utils/parsingHelpers.js

@@ -0,0 +1,56 @@
+export function safeParseInt(value, defaultValue = 0) {
+    if (value === undefined || value === null) {
+        return defaultValue;
+    }
+    if (typeof value === 'number') {
+        return isNaN(value) ? defaultValue : Math.floor(value);
+    }
+    const parsed = parseInt(String(value), 10);
+    return isNaN(parsed) ? defaultValue : parsed;
+}
+export function parseOoxmlBoolean(prop, valAttr = '@_w:val') {
+    if (!prop) {
+        return false;
+    }
+    const val = prop[valAttr];
+    if (val === undefined) {
+        return true;
+    }
+    if (typeof val === 'string') {
+        const lowerVal = val.toLowerCase();
+        return lowerVal === '1' || lowerVal === 'true' || lowerVal === 'on';
+    }
+    if (typeof val === 'number') {
+        return val === 1;
+    }
+    if (typeof val === 'boolean') {
+        return val;
+    }
+    return false;
+}
+export function isExplicitlySet(value) {
+    return value !== undefined && value !== null;
+}
+export function parseNumericAttribute(value, defaultValue) {
+    if (!isExplicitlySet(value)) {
+        return defaultValue;
+    }
+    return safeParseInt(value, defaultValue);
+}
+export function parseOnOffAttribute(value, defaultValue = false) {
+    if (!isExplicitlySet(value)) {
+        return defaultValue;
+    }
+    if (typeof value === 'string') {
+        const lowerVal = value.toLowerCase();
+        return lowerVal === '1' || lowerVal === 'true' || lowerVal === 'on';
+    }
+    if (typeof value === 'number') {
+        return value === 1;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    return defaultValue;
+}
+//# sourceMappingURL=parsingHelpers.js.map

package/dist/esm/utils/parsingHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsingHelpers.js","sourceRoot":"","sources":["../../../src/utils/parsingHelpers.ts"],"names":[],"mappings":"AA4BA,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,YAAY,GAAG,CAAC;IAC3D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,YAAY,CAAC;IACtB,CAAC;IAGD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/C,CAAC;AAsCD,MAAM,UAAU,iBAAiB,CAAC,IAAa,EAAE,OAAO,GAAG,SAAS;IAElE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,KAAK,CAAC;IACf,CAAC;IAID,MAAM,GAAG,GAAI,IAAgC,CAAC,OAAO,CAAC,CAAC;IAIvD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAGD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACnC,OAAO,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,IAAI,CAAC;IACtE,CAAC;IAGD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,GAAG,KAAK,CAAC,CAAC;IACnB,CAAC;IAGD,IAAI,OAAO,GAAG,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,GAAG,CAAC;IACb,CAAC;IAGD,OAAO,KAAK,CAAC;AACf,CAAC;AA0BD,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;AAC/C,CAAC;AAkBD,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,YAAoB;IACxE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;AAC3C,CAAC;AAeD,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,YAAY,GAAG,KAAK;IACtE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QACrC,OAAO,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,IAAI,CAAC;IACtE,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,KAAK,CAAC,CAAC;IACrB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC","sourcesContent":["/**\n * Parsing Helper Functions\n *\n * Utility functions for safely parsing OOXML values from XML attributes.\n * These helpers address common parsing issues:\n * - Zero-value handling (0 should not be treated as falsy)\n * - NaN validation (malformed values should fall back to defaults)\n * - ECMA-376 boolean parsing (self-closing tags, val=\"1\", val=\"true\")\n *\n * @see https://ecma-international.org/publications-and-standards/standards/ecma-376/\n */\n\n/**\n * Safely parse an integer value with NaN handling.\n *\n * Addresses the issue where parseInt() can return NaN for malformed input,\n * which then propagates through the document model causing issues.\n *\n * @param value - The value to parse (string, number, or any)\n * @param defaultValue - Default value if parsing fails (default: 0)\n * @returns Parsed integer or default value\n *\n * @example\n * safeParseInt(\"42\")      // 42\n * safeParseInt(\"invalid\") // 0\n * safeParseInt(undefined) // 0\n * safeParseInt(\"\", 100)   // 100\n */\nexport function safeParseInt(value: unknown, defaultValue = 0): number {\n  if (value === undefined || value === null) {\n    return defaultValue;\n  }\n\n  // If already a number, return it (handle NaN case)\n  if (typeof value === 'number') {\n    return isNaN(value) ? defaultValue : Math.floor(value);\n  }\n\n  const parsed = parseInt(String(value), 10);\n  return isNaN(parsed) ? defaultValue : parsed;\n}\n\n/**\n * Parse OOXML boolean value per ECMA-376 specification.\n *\n * OOXML boolean properties follow these rules:\n * - Self-closing tag `<w:bold/>` (no w:val attribute) = true\n * - `<w:bold w:val=\"1\"/>` = true\n * - `<w:bold w:val=\"true\"/>` = true\n * - `<w:bold w:val=\"on\"/>` = true\n * - `<w:bold w:val=\"0\"/>` = false\n * - `<w:bold w:val=\"false\"/>` = false\n * - `<w:bold w:val=\"off\"/>` = false\n * - Absent element = false (handled by caller checking for property existence)\n *\n * @param prop - The parsed XML property object (e.g., pPrObj[\"w:bold\"])\n * @param valAttr - The attribute key that carries the ST_OnOff literal.\n *   Defaults to `\"@_w:val\"` for the main WordprocessingML namespace.\n *   Pass `\"@_w14:val\"` for w14 extension elements such as\n *   `<w14:checked w14:val=\"1\"/>` (CT_OnOff in the Word 2010+ namespace).\n * @returns Boolean value\n *\n * @example\n * // For XML: <w:bold/>\n * parseOoxmlBoolean({}) // true (self-closing, no @_w:val)\n *\n * // For XML: <w:bold w:val=\"1\"/>\n * parseOoxmlBoolean({ \"@_w:val\": \"1\" }) // true\n *\n * // For XML: <w:bold w:val=\"0\"/>\n * parseOoxmlBoolean({ \"@_w:val\": \"0\" }) // false\n *\n * // For XML: <w14:checked w14:val=\"on\"/>\n * parseOoxmlBoolean({ \"@_w14:val\": \"on\" }, \"@_w14:val\") // true\n *\n * // For absent element\n * parseOoxmlBoolean(undefined) // false\n */\nexport function parseOoxmlBoolean(prop: unknown, valAttr = '@_w:val'): boolean {\n  // Absent element = false\n  if (!prop) {\n    return false;\n  }\n\n  // Get the val attribute value (w:val by default, w14:val or similar for\n  // extension namespaces).\n  const val = (prop as Record<string, unknown>)[valAttr];\n\n  // Self-closing tag without w:val attribute = true\n  // Per ECMA-376, presence of element without val means \"on\"\n  if (val === undefined) {\n    return true;\n  }\n\n  // Handle string values\n  if (typeof val === 'string') {\n    const lowerVal = val.toLowerCase();\n    return lowerVal === '1' || lowerVal === 'true' || lowerVal === 'on';\n  }\n\n  // Handle numeric values\n  if (typeof val === 'number') {\n    return val === 1;\n  }\n\n  // Handle boolean values (already parsed by XML parser)\n  if (typeof val === 'boolean') {\n    return val;\n  }\n\n  // Unknown type - default to false\n  return false;\n}\n\n/**\n * Check if a value is explicitly set (not undefined or null).\n *\n * This helper addresses the zero-value handling bug where truthy checks\n * incorrectly treat 0 as falsy:\n *\n * ```typescript\n * // WRONG - treats 0 as falsy\n * const width = val ? parseInt(val) : defaultWidth;\n *\n * // CORRECT - only checks for undefined/null\n * const width = isExplicitlySet(val) ? parseInt(val) : defaultWidth;\n * ```\n *\n * @param value - The value to check\n * @returns true if value is not undefined and not null\n *\n * @example\n * isExplicitlySet(0)         // true\n * isExplicitlySet(\"\")        // true\n * isExplicitlySet(false)     // true\n * isExplicitlySet(undefined) // false\n * isExplicitlySet(null)      // false\n */\nexport function isExplicitlySet(value: unknown): boolean {\n  return value !== undefined && value !== null;\n}\n\n/**\n * Parse an OOXML numeric attribute with proper handling of zero values.\n *\n * Combines isExplicitlySet() and safeParseInt() for common use case\n * of parsing numeric attributes from XML.\n *\n * @param value - The attribute value to parse\n * @param defaultValue - Default value if attribute is not set\n * @returns Parsed integer or default value\n *\n * @example\n * parseNumericAttribute(\"100\", 50)    // 100\n * parseNumericAttribute(\"0\", 50)      // 0 (not 50!)\n * parseNumericAttribute(undefined, 50) // 50\n * parseNumericAttribute(\"invalid\", 50) // 50\n */\nexport function parseNumericAttribute(value: unknown, defaultValue: number): number {\n  if (!isExplicitlySet(value)) {\n    return defaultValue;\n  }\n  return safeParseInt(value, defaultValue);\n}\n\n/**\n * Parse OOXML \"on/off\" attribute (ST_OnOff type).\n *\n * Some OOXML attributes use the ST_OnOff simple type which can be:\n * - \"on\", \"1\", \"true\" = true\n * - \"off\", \"0\", \"false\" = false\n *\n * This is similar to parseOoxmlBoolean but works on attribute values directly.\n *\n * @param value - The attribute value\n * @param defaultValue - Default if value is not set\n * @returns Boolean value\n */\nexport function parseOnOffAttribute(value: unknown, defaultValue = false): boolean {\n  if (!isExplicitlySet(value)) {\n    return defaultValue;\n  }\n\n  if (typeof value === 'string') {\n    const lowerVal = value.toLowerCase();\n    return lowerVal === '1' || lowerVal === 'true' || lowerVal === 'on';\n  }\n\n  if (typeof value === 'number') {\n    return value === 1;\n  }\n\n  if (typeof value === 'boolean') {\n    return value;\n  }\n\n  return defaultValue;\n}\n"]}

package/dist/esm/utils/textDiff.js

@@ -0,0 +1,42 @@
+export function diffText(oldText, newText) {
+    if (oldText === newText) {
+        return oldText.length > 0 ? [{ type: 'equal', text: oldText }] : [];
+    }
+    if (oldText.length === 0) {
+        return newText.length > 0 ? [{ type: 'insert', text: newText }] : [];
+    }
+    if (newText.length === 0) {
+        return [{ type: 'delete', text: oldText }];
+    }
+    let prefixLen = 0;
+    const minLen = Math.min(oldText.length, newText.length);
+    while (prefixLen < minLen && oldText[prefixLen] === newText[prefixLen]) {
+        prefixLen++;
+    }
+    let suffixLen = 0;
+    const maxSuffix = minLen - prefixLen;
+    while (suffixLen < maxSuffix &&
+        oldText[oldText.length - 1 - suffixLen] === newText[newText.length - 1 - suffixLen]) {
+        suffixLen++;
+    }
+    const segments = [];
+    if (prefixLen > 0) {
+        segments.push({ type: 'equal', text: oldText.slice(0, prefixLen) });
+    }
+    const oldMiddle = oldText.slice(prefixLen, oldText.length - suffixLen);
+    const newMiddle = newText.slice(prefixLen, newText.length - suffixLen);
+    if (oldMiddle.length > 0) {
+        segments.push({ type: 'delete', text: oldMiddle });
+    }
+    if (newMiddle.length > 0) {
+        segments.push({ type: 'insert', text: newMiddle });
+    }
+    if (suffixLen > 0) {
+        segments.push({ type: 'equal', text: oldText.slice(oldText.length - suffixLen) });
+    }
+    return segments;
+}
+export function diffHasUnchangedParts(segments) {
+    return segments.some((s) => s.type === 'equal');
+}
+//# sourceMappingURL=textDiff.js.map