docxmlater 10.0.2 → 10.0.4

package/src/types/styleConfig.ts

@@ -0,0 +1,189 @@
+/**
+ * Configuration interfaces for customizable style formatting
+ * Used by Document.applyCustomFormattingToExistingStyles()
+ */
+
+/**
+ * Run (character) formatting configuration for styles
+ */
+export interface StyleRunFormatting {
+  /** Font family name (e.g., 'Verdana', 'Arial', 'Times New Roman') */
+  font?: string;
+
+  /** Font size in points (e.g., 12, 14, 18) */
+  size?: number;
+
+  /** Whether text should be bold */
+  bold?: boolean;
+
+  /** Whether text should be italic */
+  italic?: boolean;
+
+  /** Whether text should be underlined */
+  underline?: boolean;
+
+  /** Text color as hex without # (e.g., '000000', 'FF0000') */
+  color?: string;
+
+  /** If true, preserve existing bold formatting (don't apply bold property) */
+  preserveBold?: boolean;
+
+  /** If true, preserve existing italic formatting (don't apply italic property) */
+  preserveItalic?: boolean;
+
+  /** If true, preserve existing underline formatting (don't apply underline property) */
+  preserveUnderline?: boolean;
+}
+
+/**
+ * Paragraph formatting configuration for styles
+ */
+export interface StyleParagraphFormatting {
+  /** Text alignment */
+  alignment?: "left" | "center" | "right" | "justify";
+
+  /** Spacing configuration */
+  spacing?: {
+    /** Spacing before paragraph in twips (20 twips = 1 point) */
+    before?: number;
+
+    /** Spacing after paragraph in twips (20 twips = 1 point) */
+    after?: number;
+
+    /** Line spacing in twips (240 = single spacing when lineRule is 'auto') */
+    line?: number;
+
+    /** How to interpret the line spacing value */
+    lineRule?: "auto" | "exact" | "atLeast";
+  };
+
+  /** Indentation configuration */
+  indentation?: {
+    /** Left indent in twips (1440 twips = 1 inch) */
+    left?: number;
+
+    /** Right indent in twips */
+    right?: number;
+
+    /** First line indent in twips (positive = indent, negative = outdent) */
+    firstLine?: number;
+
+    /** Hanging indent in twips (typically used for lists) */
+    hanging?: number;
+  };
+
+  /**
+   * Whether to remove spacing between consecutive paragraphs of the same style
+   * Per ECMA-376 Part 1 §17.3.1.8
+   */
+  contextualSpacing?: boolean;
+}
+
+/**
+ * Table appearance options for Heading2 wrapping
+ * Heading2 paragraphs are always wrapped in 1x1 tables with these settings
+ */
+export interface Heading2TableOptions {
+  /** Cell background color as hex without # (e.g., 'BFBFBF' for gray) */
+  shading?: string;
+
+  /** Top cell margin in twips */
+  marginTop?: number;
+
+  /** Bottom cell margin in twips */
+  marginBottom?: number;
+
+  /** Left cell margin in twips (115 twips = 0.08 inches) */
+  marginLeft?: number;
+
+  /** Right cell margin in twips (115 twips = 0.08 inches) */
+  marginRight?: number;
+
+  /** Table width as percentage (5000 = 100%) */
+  tableWidthPercent?: number;
+}
+
+/**
+ * Base style configuration combining run and paragraph formatting
+ */
+export interface StyleConfig {
+  /** Character formatting for the style */
+  run?: StyleRunFormatting;
+
+  /** Paragraph formatting for the style */
+  paragraph?: StyleParagraphFormatting;
+}
+
+/**
+ * Extended configuration for Heading2 style including table options
+ * Heading2 paragraphs are always wrapped in tables
+ */
+export interface Heading2Config extends StyleConfig {
+  /** Table appearance options for wrapping Heading2 paragraphs */
+  tableOptions?: Heading2TableOptions;
+}
+
+/**
+ * Extended configuration for Normal style with alignment preservation options
+ */
+export interface NormalConfig extends StyleConfig {
+  /**
+   * Whether to preserve center alignment during style application.
+   * When true, paragraphs that are center-aligned will retain their center alignment
+   * instead of being changed to the Normal style's alignment (typically 'left').
+   * This is useful for preserving intentional centering like image captions or table headers.
+   * @default false
+   */
+  preserveCenterAlignment?: boolean;
+}
+
+/**
+ * Complete configuration for applyStyles()
+ * All properties are optional - defaults will be used if not provided
+ */
+export interface ApplyStylesOptions {
+  /** Heading1 style configuration */
+  heading1?: StyleConfig;
+
+  /** Heading2 style configuration with table options */
+  heading2?: Heading2Config;
+
+  /** Heading3 style configuration */
+  heading3?: StyleConfig;
+
+  /** Normal style configuration with alignment preservation options */
+  normal?: NormalConfig;
+
+  /** List Paragraph style configuration */
+  listParagraph?: StyleConfig;
+
+  /**
+   * Whether to preserve blank lines added after 1x1 Heading 2 tables.
+   * When true, blank paragraphs added after Heading 2 tables are marked as preserved
+   * to prevent accidental removal by document processing operations (e.g., removing extra blank lines).
+   * @default true
+   */
+  preserveBlankLinesAfterHeading2Tables?: boolean;
+
+  /**
+   * Whether to preserve white font (FFFFFF) color during style application.
+   * When true, runs with white color will not have their color changed.
+   * This is useful for preserving hidden text like ID tags or overlay text.
+   * @default false
+   */
+  preserveWhiteFont?: boolean;
+
+  /**
+   * Whether to apply Normal style changes to NormalWeb (Normal (Web)) style as well.
+   * When true (default), if NormalWeb style exists in the document,
+   * it will receive the same formatting changes applied to Normal.
+   * This ensures consistency between Normal and Normal (Web) styles.
+   * @default true
+   */
+  linkNormalWebToNormal?: boolean;
+}
+
+/**
+ * @deprecated Use {@link ApplyStylesOptions} instead (renamed in v4.0.0)
+ */
+export type ApplyCustomFormattingOptions = ApplyStylesOptions;

package/src/utils/CLAUDE.md

@@ -0,0 +1,153 @@
+# Utils Module
+
+`src/utils/` — Standalone utilities (22 TypeScript files) for unit conversions, revision processing, validation, logging, and helpers.
+
+## Unit Conversions (`units.ts`)
+
+40+ conversion functions between twips, EMUs, points, half-points, pixels, inches, centimeters.
+
+Key constants: 1 inch = 1440 twips = 914400 EMUs = 72 points. 1 point = 20 twips. Font sizes use half-points.
+
+## Validation (`validation.ts`)
+
+- `validateRunText(text)` — Detects XML patterns accidentally passed as text
+- `cleanXmlFromText(text)` — Removes XML patterns from text
+- `isValidDocxStructure(files)` — Validates DOCX file structure
+
+## Corruption Detection (`corruptionDetection.ts`)
+
+```typescript
+const report = detectCorruptionInDocument(doc);
+// report: { isCorrupted, summary, locations: [{ suggestedFix }] }
+```
+
+Detects XML markup in text, invalid characters, malformed structures.
+
+## XML Sanitization (`xmlSanitization.ts`)
+
+XML 1.0 control character validation. Auto-applied by `XMLBuilder.escapeXmlText()`.
+
+- `removeInvalidXmlChars(text)` — Strips 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F
+- `hasInvalidXmlChars(text)` / `findInvalidXmlChars(text)`
+- Tab (0x09), newline (0x0A), CR (0x0D) are preserved
+
+## Parsing Helpers (`parsingHelpers.ts`)
+
+Safe OOXML attribute parsing with zero-value edge case handling:
+
+- `safeParseInt(value, default?)` — NaN-safe integer parsing
+- `parseOoxmlBoolean(prop)` — Handles self-closing tags, `val="1"`, `val="true"`, `val="on"`
+- `isExplicitlySet(value)` — Handles 0 correctly (common bug: treating 0 as falsy)
+- `parseNumericAttribute(value, default?)` — Zero-safe numeric parsing
+
+## Formatting Utilities (`formatting.ts`)
+
+- `normalizeColor(color)` — Uppercase 6-char hex
+
+## Deep Clone (`deepClone.ts`)
+
+- `deepClone<T>(obj)` — Safe deep cloning
+
+## Date Formatting (`dateFormatting.ts`)
+
+- `formatDateForXml(date)` — ISO 8601 without milliseconds (Word rejects dates with ms in `w:date`)
+
+## Revision Processing
+
+### acceptRevisions (`acceptRevisions.ts`)
+
+Main entry point for accepting tracked changes via raw XML:
+```typescript
+await acceptAllRevisions(zipHandler, options?)
+// Options: acceptInsertions, acceptDeletions, acceptMoves, acceptPropertyChanges, useDomParser
+```
+Processes document.xml + all headers/footers, remaps image relationship IDs, cleans metadata.
+
+### RevisionWalker (`RevisionWalker.ts`)
+
+DOM-based tree walker for revision acceptance. Handles nested revisions, preserves element order via `_orderedChildren`. ReDoS-safe.
+
+### ChangelogGenerator (`ChangelogGenerator.ts`)
+
+Converts revisions to structured changelog data:
+```typescript
+const entries = ChangelogGenerator.fromDocument(doc, options?);
+ChangelogGenerator.toMarkdown(entries)  // Also: toJSON, toHTML, toCSV
+ChangelogGenerator.getSummary(entries)
+ChangelogGenerator.consolidate(entries)
+```
+Options: `includeFormattingChanges`, `consolidate`, `filterAuthors`, `filterCategories`, `sortBy`, `sortOrder`.
+
+### SelectiveRevisionAcceptor (`SelectiveRevisionAcceptor.ts`)
+
+Accept/reject revisions by criteria (authors, types, date range, categories).
+
+### MoveOperationHelper (`MoveOperationHelper.ts`)
+
+Creates complete move operations with ECMA-376 range markers. See `src/elements/CLAUDE.md` for usage.
+
+### stripTrackedChanges (`stripTrackedChanges.ts`)
+
+Removes all revision markup: `await stripTrackedChanges(zipHandler)`.
+
+## Text Diff (`textDiff.ts`)
+
+Character-level diff for granular tracking in `Run.setText()`:
+```typescript
+const segments = diffText('Hello World', 'Hello Earth');
+// [{ type: 'equal', text: 'Hello ' }, { type: 'delete', text: 'World' }, { type: 'insert', text: 'Earth' }]
+if (diffHasUnchangedParts(segments)) { /* granular tracking */ }
+```
+
+## Compatibility Utilities
+
+### CompatibilityUpgrader (`CompatibilityUpgrader.ts`)
+
+Upgrades `w:compat` blocks to modern Word 2013+ format. Used by `Document.upgradeToModernFormat()`.
+
+Related constants in `src/constants/legacyCompatFlags.ts`:
+- `LEGACY_COMPAT_ELEMENTS` — 65 legacy boolean flags
+- `MODERN_COMPAT_SETTINGS` — 5 default modern settings
+- `MS_WORD_COMPAT_URI` — Microsoft namespace URI
+
+## Logging (`logger.ts`)
+
+**Levels:** `DEBUG`, `INFO`, `WARN`, `ERROR`
+
+**Implementations:** `ConsoleLogger` (timestamps), `SilentLogger` (no output), `CollectingLogger` (in-memory).
+
+**Environment:**
+```bash
+DOCXMLATER_LOG_LEVEL=info npm test    # info/debug/silent
+DEBUG=docxmlater npm test
+```
+
+**Programmatic:**
+```typescript
+import { setGlobalLogger, ConsoleLogger, LogLevel } from 'docxmlater';
+setGlobalLogger(new ConsoleLogger(LogLevel.INFO));
+```
+
+**Scoped:**
+```typescript
+const logger = createScopedLogger(getGlobalLogger(), 'MyComponent');
+logger.info('Done', { count: 10 });
+// Output: 12:34:56.789 [INFO ] [MyComponent] Done count=10
+```
+
+| Component | INFO | DEBUG |
+|-----------|------|-------|
+| Document | Load/save ops | + details |
+| ZipHandler | File ops, validation | + counts, sizes |
+| DocumentParser | Completion, warnings | + element counts |
+| DocumentGenerator | Generation steps | + XML sizes |
+| RevisionManager | Clear, summary | + each registration |
+
+## Error Handling (`errorHandling.ts`)
+
+`DocXMLaterError` → `InvalidDocxError`, `ParseError`, `ValidationError`.
+
+## Diagnostics (`diagnostics.ts`)
+
+- `debugXmlStructure(xml)` — Debug XML structure
+- `inspectElement(element)` — Element inspection