docxmlater 10.3.5 → 10.4.0

package/src/core/RelationshipManager.ts

@@ -8,6 +8,7 @@
 import { Relationship, RelationshipType } from './Relationship';
 import { XMLParser } from '../xml/XMLParser';
 import { sanitizeHyperlinkUrl } from '../utils/validation';
+import { InvalidDocxError, CorruptedArchiveError } from '../zip/errors';
 
 /**
  * Manages relationships for a document or document part
@@ -221,7 +222,7 @@ export class RelationshipManager {
 
     // Verify this is a hyperlink relationship
     if (relationship.getType() !== RelationshipType.HYPERLINK) {
-      throw new Error(
+      throw new InvalidDocxError(
         `Relationship ${relationshipId} is not a hyperlink relationship. ` +
           `Type is ${relationship.getType()}, expected ${RelationshipType.HYPERLINK}`
       );
@@ -384,7 +385,7 @@ export class RelationshipManager {
 
     // Prevent ReDoS: validate input size (typical .rels files are < 10KB, max 10MB)
     if (xml.length > 10000000) {
-      throw new Error(
+      throw new CorruptedArchiveError(
         'Relationships XML file too large (>10MB). Possible malicious input or corrupted file.'
       );
     }
@@ -394,7 +395,9 @@ export class RelationshipManager {
 
     // Prevent infinite loops: check relationship count
     if (relationshipElements.length > 1000) {
-      throw new Error('Too many relationships in XML file (>1000). Possible malicious input.');
+      throw new CorruptedArchiveError(
+        'Too many relationships in XML file (>1000). Possible malicious input.'
+      );
     }
 
     // Process each relationship element

package/src/elements/Bookmark.ts

@@ -17,6 +17,10 @@ export interface BookmarkProperties {
   name: string;
   /** Skip name normalization (used when loading from existing documents) */
   skipNormalization?: boolean;
+  /** First column in table bookmark range (ECMA-376 §17.16.5) */
+  colFirst?: number;
+  /** Last column in table bookmark range (ECMA-376 §17.16.5) */
+  colLast?: number;
 }
 
 /**
@@ -25,6 +29,8 @@ export interface BookmarkProperties {
 export class Bookmark {
   private id: number;
   private name: string;
+  private colFirst?: number;
+  private colLast?: number;
 
   /**
    * Creates a new Bookmark
@@ -37,6 +43,8 @@ export class Bookmark {
     this.name = properties.skipNormalization
       ? properties.name
       : this.normalizeName(properties.name);
+    this.colFirst = properties.colFirst;
+    this.colLast = properties.colLast;
   }
 
   /**
@@ -136,17 +144,44 @@ export class Bookmark {
     return this;
   }
 
+  /**
+   * Gets the first column in a table bookmark range
+   */
+  getColFirst(): number | undefined {
+    return this.colFirst;
+  }
+
+  /**
+   * Gets the last column in a table bookmark range
+   */
+  getColLast(): number | undefined {
+    return this.colLast;
+  }
+
+  /**
+   * Sets the column range for a table bookmark (ECMA-376 §17.16.5)
+   */
+  setColumnRange(colFirst: number, colLast: number): this {
+    this.colFirst = colFirst;
+    this.colLast = colLast;
+    return this;
+  }
+
   /**
    * Generates XML for the bookmark start marker
    * @returns XMLElement for bookmarkStart
    */
   toStartXML(): XMLElement {
+    const attrs: Record<string, string | number> = {
+      'w:id': this.id.toString(),
+      'w:name': this.name,
+    };
+    // Table bookmark column range per ECMA-376 §17.16.5
+    if (this.colFirst !== undefined) attrs['w:colFirst'] = this.colFirst.toString();
+    if (this.colLast !== undefined) attrs['w:colLast'] = this.colLast.toString();
     return {
       name: 'w:bookmarkStart',
-      attributes: {
-        'w:id': this.id.toString(),
-        'w:name': this.name,
-      },
+      attributes: attrs,
       selfClosing: true,
     };
   }

package/src/elements/BookmarkManager.ts

@@ -8,6 +8,7 @@
  */
 
 import { Bookmark } from './Bookmark';
+import { InvalidDocxError } from '../zip/errors';
 
 /**
  * Type for the centralized ID provider callback.
@@ -55,7 +56,7 @@ export class BookmarkManager {
 
     // Check for duplicate names
     if (this.bookmarks.has(name)) {
-      throw new Error(
+      throw new InvalidDocxError(
         `Bookmark with name "${name}" already exists. Bookmark names must be unique within a document.`
       );
     }
@@ -83,7 +84,7 @@ export class BookmarkManager {
 
     // Check for duplicate names
     if (this.bookmarks.has(name)) {
-      throw new Error(
+      throw new InvalidDocxError(
         `Bookmark with name "${name}" already exists. Bookmark names must be unique within a document.`
       );
     }
@@ -194,7 +195,7 @@ export class BookmarkManager {
       counter++;
     }
 
-    throw new Error(`Could not generate unique bookmark name from base "${baseName}"`);
+    throw new InvalidDocxError(`Could not generate unique bookmark name from base "${baseName}"`);
   }
 
   /**

package/src/elements/CLAUDE.md

@@ -38,19 +38,31 @@ Header/Footer Elements
 
 Container for text and inline content. Key formatting: `alignment`, `spacing`, `indentation`, `pPrChange` (revision tracking), `keepNext`/`keepLines`/`pageBreakBefore` (pagination).
 
-**Rule:** `setKeepNext(true)` / `setKeepLines(true)` auto-clears `pageBreakBefore`.
+**CT_OnOff properties:** `keepNext`, `keepLines`, `pageBreakBefore`, `suppressLineNumbers`, `suppressAutoHyphens`, `contextualSpacing`, `mirrorIndents`, `suppressOverlap` all use `!== undefined` semantics with `w:val` attribute, supporting explicit `false` to override style inheritance.
+
+**Rule:** `setKeepNext(true)` / `setKeepLines(true)` auto-clears `pageBreakBefore` to `undefined` (absent, not explicit false).
+
+**Alignment:** `ParagraphAlignment` includes bidi-aware values (`start`, `end`), CJK (`distribute`), Arabic kashida (`mediumKashida`, `highKashida`, `lowKashida`), and Thai (`thaiDistribute`).
+
+**w14 attributes:** `paraId` and `textId` (Word 2010+) are auto-generated for new paragraphs during `prepareSave()`. Values are 8-char hex, must be < `0x80000000`.
 
 CJK methods: `setKinsoku()`, `setWordWrap()`, `setOverflowPunct()`, `setTopLinePunct()`, `setAutoSpaceDE()`, `setAutoSpaceDN()`.
 
 ### Run (`Run.ts`)
 
-Formatted text span. Character formatting (bold, italic, underline, strikethrough), font properties, color (normalized to uppercase 6-char hex), highlight, special chars (tabs, breaks, symbols), complex script support.
+Formatted text span. Character formatting (bold, italic, underline, strikethrough), font properties, color (hex or `'auto'`), highlight, special chars (tabs, breaks, symbols), complex script support.
+
+**CT_OnOff properties:** Boolean properties use `!== undefined` semantics: `undefined` = inherit from style, `true` = on, `false` = explicitly off (`w:val="0"`). This applies to: bold, bCs, italic, iCs, caps, smallCaps, strike, dstrike, snapToGrid.
+
+**Vertical alignment:** `setSubscript()`, `setSuperscript()`, and `vertAlignBaseline` field for explicit baseline reset per ST_VerticalAlignRun.
 
 Theme fonts: `setFontAsciiTheme()`, `setFontHAnsiTheme()`, `setFontEastAsiaTheme()`, `setFontCsTheme()`.
 Underline: `setUnderlineColor()`, `setUnderlineThemeColor()`.
 w14 effects: `addRawW14Property(xml)` for Word 2010+ ligatures, numForm, textOutline.
 Form fields: `FormFieldData`, `FormFieldTextInput`, `FormFieldCheckBox`, `FormFieldDropDownList` interfaces.
 
+**Static helper:** `Run.generateRunPropertiesXML(formatting)` — generates `w:rPr` with all 38+ CT_RPr elements in strict ECMA-376 order. Used by both Run and Style serialization.
+
 ### Table (`Table.ts`, `TableRow.ts`, `TableCell.ts`)
 
 Row/column management, cell merging (horizontal + vertical), border styling, property change tracking (`w:tblPrChange`), inter-row content preservation (bookmarks, comments between rows).
@@ -59,6 +71,10 @@ Navigation: `getFirstParagraph()`, `getLastParagraph()`.
 Layout: `getLayout()` returns `'fixed'` or `'auto'`.
 Legacy merge: `setHorizontalMerge()` / `getHorizontalMerge()` (hMerge).
 
+**Constraints:** `removeRow()` prevents removing the last row (ECMA-376 requires >= 1 row). `insertRow()`/`insertRows()` use grid span count for correct column count with merged cells. `tblPrEx` is serialized before `trPr` in `w:tr` per CT_Row.
+
+**TableRow:** `setHeightRule(rule)` sets height rule independently. When `w:hRule` is absent, the spec default is `"auto"` (not `"atLeast"`).
+
 **Nested Tables:** Raw XML passthrough via `TableCell.rawNestedContent[]`.
 ```typescript
 cell.addRawNestedContent(position, xml, "table")

package/src/elements/CommonTypes.ts

@@ -223,19 +223,33 @@ export type PageVerticalAlignment = 'top' | 'center' | 'bottom' | 'both';
 export type CellVerticalAlignment = 'top' | 'center' | 'bottom';
 
 /**
- * Paragraph text alignment
+ * Paragraph text alignment per ECMA-376 §17.18.44 (ST_Jc)
  *
  * From: Paragraph.ts (ParagraphAlignment)
- * Note: 'both' is an alias for 'justify' in some contexts
+ * Note: 'both' is the OOXML name for justified text; 'justify' is accepted as an alias.
+ * 'start'/'end' are bidi-aware alternatives to 'left'/'right'.
  */
-export type ParagraphAlignment = 'left' | 'center' | 'right' | 'justify' | 'both';
-
-/**
- * Table alignment (horizontal positioning)
+export type ParagraphAlignment =
+  | 'left'
+  | 'center'
+  | 'right'
+  | 'justify'
+  | 'both'
+  | 'start'
+  | 'end'
+  | 'distribute'
+  | 'mediumKashida'
+  | 'highKashida'
+  | 'lowKashida'
+  | 'thaiDistribute';
+
+/**
+ * Table alignment (horizontal positioning) per ECMA-376 §17.18.45 (ST_JcTable)
  *
  * From: Table.ts (TableAlignment)
+ * 'start'/'end' are bidi-aware alternatives to 'left'/'right'.
  */
-export type TableAlignment = 'left' | 'center' | 'right';
+export type TableAlignment = 'left' | 'center' | 'right' | 'start' | 'end';
 
 /**
  * Row justification/alignment options
@@ -466,7 +480,20 @@ export function isVerticalAlignment(value: string): value is VerticalAlignment {
  * Check if a value is a valid ParagraphAlignment
  */
 export function isParagraphAlignment(value: string): value is ParagraphAlignment {
-  return ['left', 'center', 'right', 'justify', 'both'].includes(value);
+  return [
+    'left',
+    'center',
+    'right',
+    'justify',
+    'both',
+    'start',
+    'end',
+    'distribute',
+    'mediumKashida',
+    'highKashida',
+    'lowKashida',
+    'thaiDistribute',
+  ].includes(value);
 }
 
 /**

package/src/elements/Field.ts

@@ -447,7 +447,7 @@ export class Field {
    */
   static createHyperlink(
     url: string,
-    displayText: string = url,
+    _displayText: string = url,
     tooltip?: string,
     formatting?: RunFormatting
   ): Field {

package/src/elements/Footer.ts

@@ -7,6 +7,7 @@
 
 import { XMLElement } from '../xml/XMLBuilder';
 import { Paragraph } from './Paragraph';
+import { RunFormatting } from './Run';
 import { Table } from './Table';
 
 /**
@@ -105,6 +106,28 @@ export class Footer {
     return para;
   }
 
+  /**
+   * Adds formatted text to the footer as a new paragraph
+   *
+   * Convenience method that creates a paragraph with a single formatted run.
+   *
+   * @param text - Text content
+   * @param formatting - Optional run formatting (bold, font, size, etc.)
+   * @returns The created Paragraph for further customization
+   *
+   * @example
+   * ```typescript
+   * footer.addText('Page ', { size: 8 });
+   * footer.addText('Confidential', { italic: true, color: '888888' });
+   * ```
+   */
+  addText(text: string, formatting?: RunFormatting): Paragraph {
+    const para = new Paragraph();
+    para.addText(text, formatting);
+    this.elements.push(para);
+    return para;
+  }
+
   /**
    * Adds a table to the footer
    * @param table Table to add

package/src/elements/Header.ts

@@ -7,6 +7,7 @@
 
 import { XMLElement } from '../xml/XMLBuilder';
 import { Paragraph } from './Paragraph';
+import { RunFormatting } from './Run';
 import { Table } from './Table';
 
 /**
@@ -105,6 +106,30 @@ export class Header {
     return para;
   }
 
+  /**
+   * Adds formatted text to the header as a new paragraph
+   *
+   * Convenience method that creates a paragraph with a single formatted run.
+   * For headers with multiple runs or complex content, use `createParagraph()`
+   * and build content manually.
+   *
+   * @param text - Text content
+   * @param formatting - Optional run formatting (bold, font, size, etc.)
+   * @returns The created Paragraph for further customization
+   *
+   * @example
+   * ```typescript
+   * header.addText('Company Name', { bold: true, font: 'Arial', size: 10 });
+   * header.addText('Confidential', { italic: true, color: 'FF0000' });
+   * ```
+   */
+  addText(text: string, formatting?: RunFormatting): Paragraph {
+    const para = new Paragraph();
+    para.addText(text, formatting);
+    this.elements.push(para);
+    return para;
+  }
+
   /**
    * Adds a table to the header
    * @param table Table to add

package/src/elements/Image.ts

@@ -80,6 +80,8 @@ export interface ImageBorder {
   headEnd?: { type?: string; width?: string; length?: string };
   /** Tail end decoration */
   tailEnd?: { type?: string; width?: string; length?: string };
+  /** @internal Set by parser to suppress default fill in generator */
+  _fromParsed?: boolean;
 }
 
 /**
@@ -1486,9 +1488,14 @@ export class Image {
     if (typeof thicknessOrOptions === 'number') {
       this.border = { width: thicknessOrOptions };
     } else {
-      this.border = thicknessOrOptions;
+      this.border = { ...thicknessOrOptions };
+      delete this.border._fromParsed;
     }
 
+    // Clear passthrough slots that conflict with explicit border
+    this._rawPassthrough.delete('zero-width-ln');
+    this._rawPassthrough.delete('spPr-noFill');
+
     // Calculate space needed for border (half-width on each side)
     // Border is drawn centered on the edge
     const borderEmu = this.border.width * UNITS.EMUS_PER_POINT;
@@ -1512,6 +1519,7 @@ export class Image {
    */
   removeBorder(): this {
     this.border = undefined;
+    this._rawPassthrough.delete('zero-width-ln');
     return this;
   }
 
@@ -1626,11 +1634,17 @@ export class Image {
       );
     }
 
-    // Border (a:ln) - full model (Group C)
+    // Fill group: a:noFill (before a:ln per ECMA-376 CT_ShapeProperties ordering)
     if (this.border) {
-      // Add noFill element before the border line (required by Word)
+      // Bordered images use noFill for shape fill
+      spPrChildren.push(XMLBuilder.a('noFill'));
+    } else if (this._rawPassthrough.has('spPr-noFill')) {
+      // Preserve spPr-level a:noFill from loaded document (Bug C fix)
       spPrChildren.push(XMLBuilder.a('noFill'));
+    }
 
+    // Border (a:ln) - full model (Group C)
+    if (this.border) {
       const ptToEmu = 12700;
       const widthEmu = this.border.width * ptToEmu;
       const lnAttrs: Record<string, string> = { w: widthEmu.toString() };
@@ -1655,8 +1669,9 @@ export class Image {
             ? XMLBuilder.a(this.border.fill.type, { val: this.border.fill.value }, colorChildren)
             : XMLBuilder.a(this.border.fill.type, { val: this.border.fill.value });
         lnChildren.push(XMLBuilder.a('solidFill', undefined, [colorEl]));
-      } else {
-        // Default: scheme color tx1 (backward compat)
+      } else if (!this.border._fromParsed) {
+        // Default fill for programmatic borders only (setBorder API backward compat).
+        // Parsed borders without fill are intentionally left as-is.
         lnChildren.push(
           XMLBuilder.a('solidFill', undefined, [XMLBuilder.a('schemeClr', { val: 'tx1' })])
         );
@@ -1689,6 +1704,14 @@ export class Image {
       spPrChildren.push(XMLBuilder.a('ln', lnAttrs, lnChildren));
     }
 
+    // Zero-width a:ln passthrough (e.g., <a:ln><a:noFill/></a:ln>) (BUG 8 fix)
+    if (!this.border && this._rawPassthrough.has('zero-width-ln')) {
+      spPrChildren.push({
+        name: '__rawXml',
+        rawXml: this._rawPassthrough.get('zero-width-ln')!,
+      } as XMLElement);
+    }
+
     // Group B: Inject raw spPr effects passthrough (effectLst, scene3d, sp3d, etc.)
     if (this._rawPassthrough.has('spPr-effects')) {
       spPrChildren.push({