docxmlater 10.0.1 → 10.0.3

package/src/elements/BookmarkManager.ts

@@ -0,0 +1,250 @@
+/**
+ * BookmarkManager - Manages bookmarks in a document
+ *
+ * Tracks all bookmarks, assigns unique IDs, and ensures name uniqueness.
+ *
+ * Per ECMA-376, bookmark IDs must be unique across ALL annotation types
+ * in a document. Use setIdProvider() to connect to a centralized ID allocator.
+ */
+
+import { Bookmark } from './Bookmark';
+
+/**
+ * Type for the centralized ID provider callback.
+ * Returns the next available annotation ID from a shared counter.
+ */
+export type IdProviderCallback = () => number;
+
+/**
+ * Type for callback to notify of existing IDs (for synchronization).
+ * Called when registering an existing bookmark to keep the central counter in sync.
+ */
+export type IdExistsCallback = (existingId: number) => void;
+
+/**
+ * Manages document bookmarks
+ */
+export class BookmarkManager {
+  private bookmarks = new Map<string, Bookmark>();
+  private nextId = 0;
+  private idProvider: IdProviderCallback | null = null;
+  private idExistsNotifier: IdExistsCallback | null = null;
+
+  /**
+   * Sets the centralized ID provider callback.
+   * When set, IDs will be allocated from the centralized DocumentIdManager
+   * instead of the local nextId counter.
+   *
+   * @param provider - Callback that returns the next available ID
+   * @param existsNotifier - Optional callback to notify when existing IDs are found
+   */
+  setIdProvider(provider: IdProviderCallback, existsNotifier?: IdExistsCallback): void {
+    this.idProvider = provider;
+    this.idExistsNotifier = existsNotifier || null;
+  }
+
+  /**
+   * Registers a bookmark with the manager
+   * Assigns a unique ID and ensures name uniqueness
+   * @param bookmark - Bookmark to register
+   * @returns The registered bookmark (same instance)
+   * @throws Error if a bookmark with the same name already exists
+   */
+  register(bookmark: Bookmark): Bookmark {
+    const name = bookmark.getName();
+
+    // Check for duplicate names
+    if (this.bookmarks.has(name)) {
+      throw new Error(
+        `Bookmark with name "${name}" already exists. Bookmark names must be unique within a document.`
+      );
+    }
+
+    // Assign unique ID - use centralized provider if available
+    const id = this.idProvider ? this.idProvider() : this.nextId++;
+    bookmark.setId(id);
+
+    // Store bookmark
+    this.bookmarks.set(name, bookmark);
+
+    return bookmark;
+  }
+
+  /**
+   * Registers an existing bookmark, preserving its ID
+   * Used when loading documents to preserve original bookmark IDs and avoid collisions
+   * @param bookmark - Bookmark with existing ID to register
+   * @returns The registered bookmark (same instance)
+   * @throws Error if a bookmark with the same name already exists
+   */
+  registerExisting(bookmark: Bookmark): Bookmark {
+    const name = bookmark.getName();
+    const existingId = bookmark.getId();
+
+    // Check for duplicate names
+    if (this.bookmarks.has(name)) {
+      throw new Error(
+        `Bookmark with name "${name}" already exists. Bookmark names must be unique within a document.`
+      );
+    }
+
+    // Notify centralized ID manager about this existing ID
+    if (this.idExistsNotifier) {
+      this.idExistsNotifier(existingId);
+    }
+
+    // Also update local nextId to avoid collisions (for fallback)
+    if (existingId >= this.nextId) {
+      this.nextId = existingId + 1;
+    }
+
+    // Store bookmark (keep its existing ID)
+    this.bookmarks.set(name, bookmark);
+
+    return bookmark;
+  }
+
+  /**
+   * Gets a bookmark by name
+   * @param name - Bookmark name
+   * @returns The bookmark, or undefined if not found
+   */
+  getBookmark(name: string): Bookmark | undefined {
+    return this.bookmarks.get(name);
+  }
+
+  /**
+   * Checks if a bookmark exists
+   * @param name - Bookmark name
+   * @returns True if the bookmark exists
+   */
+  hasBookmark(name: string): boolean {
+    return this.bookmarks.has(name);
+  }
+
+  /**
+   * Gets all bookmarks
+   * @returns Array of all bookmarks
+   */
+  getAllBookmarks(): Bookmark[] {
+    return Array.from(this.bookmarks.values());
+  }
+
+  /**
+   * Gets the number of bookmarks
+   * @returns Number of bookmarks
+   */
+  getCount(): number {
+    return this.bookmarks.size;
+  }
+
+  /**
+   * Removes a bookmark
+   * @param name - Bookmark name
+   * @returns True if the bookmark was removed
+   */
+  removeBookmark(name: string): boolean {
+    return this.bookmarks.delete(name);
+  }
+
+  /**
+   * Clears all bookmarks
+   */
+  clear(): void {
+    this.bookmarks.clear();
+    this.nextId = 0;
+  }
+
+  /**
+   * Sets the next ID to be assigned
+   * Used when loading documents to avoid ID collisions with existing bookmarks
+   * @param id - The next ID value to use
+   */
+  setNextId(id: number): void {
+    this.nextId = id;
+  }
+
+  /**
+   * Gets a unique bookmark name by adding a suffix if needed
+   * Ensures the returned name is always within the 40-character limit
+   * @param baseName - Base name for the bookmark
+   * @returns A unique bookmark name (max 40 characters)
+   */
+  getUniqueName(baseName: string): string {
+    const maxLength = 40;
+
+    if (!this.hasBookmark(baseName)) {
+      return baseName;
+    }
+
+    // Try adding numbers until we find a unique name
+    let counter = 1;
+    while (counter <= 1000) {
+      const suffix = `_${counter}`;
+
+      // Truncate base name to leave room for suffix within 40-char limit
+      const maxBase = maxLength - suffix.length;
+      const truncatedBase =
+        baseName.length > maxBase ? baseName.substring(0, maxBase) : baseName;
+
+      const uniqueName = `${truncatedBase}${suffix}`;
+
+      if (!this.hasBookmark(uniqueName)) {
+        return uniqueName;
+      }
+      counter++;
+    }
+
+    throw new Error(
+      `Could not generate unique bookmark name from base "${baseName}"`
+    );
+  }
+
+  /**
+   * Creates and registers a new bookmark with a unique name
+   * @param name - Desired bookmark name
+   * @returns The created and registered bookmark
+   */
+  createBookmark(name: string): Bookmark {
+    const uniqueName = this.getUniqueName(name);
+    const bookmark = Bookmark.create(uniqueName);
+    return this.register(bookmark);
+  }
+
+  /**
+   * Creates and registers a bookmark for a heading
+   * Automatically generates a unique name from the heading text
+   * @param headingText - The text of the heading
+   * @returns The created and registered bookmark
+   */
+  createHeadingBookmark(headingText: string): Bookmark {
+    const bookmark = Bookmark.createForHeading(headingText);
+    const uniqueName = this.getUniqueName(bookmark.getName());
+    bookmark.setName(uniqueName);
+    return this.register(bookmark);
+  }
+
+  /**
+   * Gets statistics about bookmarks
+   * @returns Object with bookmark statistics
+   */
+  getStats(): {
+    total: number;
+    nextId: number;
+    names: string[];
+  } {
+    return {
+      total: this.bookmarks.size,
+      nextId: this.nextId,
+      names: Array.from(this.bookmarks.keys()),
+    };
+  }
+
+  /**
+   * Creates a new BookmarkManager
+   * @returns New BookmarkManager instance
+   */
+  static create(): BookmarkManager {
+    return new BookmarkManager();
+  }
+}

package/src/elements/CLAUDE.md

@@ -0,0 +1,126 @@
+# Elements Module
+
+`src/elements/` — All document element classes (40 TypeScript files).
+
+## Element Hierarchy
+
+```
+Body Elements (added to document body)
+├── Paragraph
+├── Table
+├── TableOfContents / TableOfContentsElement
+├── StructuredDocumentTag
+├── AlternateContent          # mc:AlternateContent raw XML passthrough
+├── MathParagraph              # m:oMathPara raw XML passthrough
+├── CustomXmlBlock             # w:customXml raw XML passthrough
+└── PreservedElement           # Generic XML passthrough (block context)
+
+Inline Elements (within paragraphs)
+├── Run (formatted text span)
+├── ImageRun (inline image)
+├── Hyperlink
+├── Bookmark / RangeMarker
+├── Field
+├── Comment (anchor)
+├── Footnote/Endnote (reference)
+├── StructuredDocumentTag (inline)
+├── MathExpression             # m:oMath inline raw XML passthrough
+└── PreservedElement (inline)
+
+Header/Footer Elements
+├── Header / Footer
+└── Section (page setup, header/footer references)
+```
+
+## Core Elements
+
+### Paragraph (`Paragraph.ts`)
+
+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`.
+
+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.
+
+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.
+
+### 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).
+
+Navigation: `getFirstParagraph()`, `getLastParagraph()`.
+Layout: `getLayout()` returns `'fixed'` or `'auto'`.
+Legacy merge: `setHorizontalMerge()` / `getHorizontalMerge()` (hMerge).
+
+**Nested Tables:** Raw XML passthrough via `TableCell.rawNestedContent[]`.
+```typescript
+cell.addRawNestedContent(position, xml, "table")
+cell.getRawNestedContent()
+cell.hasNestedTables()
+```
+
+**Inter-Row Content:** Per ECMA-376, elements like bookmarkEnd can appear between rows.
+```typescript
+table.addInterRowContent(afterRowIndex, xml, type)
+table.getInterRowContent()
+```
+
+### Image (`Image.ts`, `ImageRun.ts`)
+
+PNG/JPEG/GIF/SVG/EMF/WMF with buffer-based format detection. Inline and floating positioning. Full ECMA-376 attribute coverage: presetGeometry, compressionState, bwMode, picLocks, inline dist, transparency (`a:alphaModFix`), enhanced border model (`ImageBorder`), 9 raw XML passthrough slots, linked images (`r:link`), SVG dual-relationship (`asvg:svgBlip`).
+
+## Revision System
+
+### Revision (`Revision.ts`)
+
+Types: `insert`, `delete`, `moveFrom`, `moveTo`, `runPropertiesChange`, `paragraphPropertiesChange`, `tablePropertiesChange`, `tableCellInsert`, `tableCellDelete`, `tableCellMerge`, `numberingChange`, `sectionPropertiesChange`.
+
+### RevisionManager (`RevisionManager.ts`)
+
+Registration, retrieval, category/author/date filtering, location-aware queries, statistics, validation (duplicate IDs, orphaned moves).
+
+### MoveOperationHelper (`../utils/MoveOperationHelper.ts`)
+
+Creates complete move operations with all required ECMA-376 range markers (`moveFromRangeStart/End`, `moveToRangeStart/End`). Without range markers, Word displays moves as separate delete+insert pairs.
+
+```typescript
+MoveOperationHelper.addMoveOperation(sourcePara, destPara, {
+  author: 'John Doe',
+  content: new Run('moved text'),
+});
+```
+
+## Other Elements
+
+- **Hyperlink**: Internal/external URLs, tooltip, relationship management
+- **Bookmark / BookmarkManager**: Named locations, cross-references, unique ID assignment
+- **Field / FieldHelpers**: MERGEFIELD, DATE, TIME, PAGE, NUMPAGES, TOC, REF
+- **Comment / CommentManager**: Author/date, reply threading, anchor positioning
+- **Header / Footer / HeaderFooterManager**: Default, first page, even pages
+- **Section**: Page size, margins, orientation, columns, page numbering
+- **Footnote / Endnote / FootnoteManager / EndnoteManager**: Note content, numbering, separators
+- **StructuredDocumentTag**: Rich/plain text, date pickers, dropdowns, checkboxes
+- **Shape / TextBox**: Basic shapes, text boxes with content
+- **FontManager**: Font table and declarations
+- **ImageManager**: Image collection with relationship handling
+
+## Preserved Element Classes
+
+Store elements as raw XML for round-trip fidelity (internal structure not modified by framework):
+- **AlternateContent**: `mc:AlternateContent` — Word 2010+ drawing with VML fallback
+- **MathParagraph / MathExpression**: `m:oMathPara` / `m:oMath` — math content
+- **CustomXmlBlock**: `w:customXml` — embedded custom XML
+- **PreservedElement**: Generic wrapper for `w:proofErr`, `w:permStart`, `w:permEnd`, `w:altChunk`, `w:ruby`
+
+All share the same API pattern: `constructor(rawXml)`, `toXML()`, `getRawXml()`, `getType()`.
+
+## Serialization
+
+Every element has `toXML()` returning `XMLElement { name, attributes, children }`. Elements don't hold references to their parent document.