docxmlater 10.0.1 → 10.0.3

package/src/core/RelationshipManager.ts

@@ -0,0 +1,428 @@
+/**
+ * RelationshipManager - Manages collections of relationships
+ *
+ * Handles relationship creation, tracking, and XML generation for various
+ * document parts (document.xml, header.xml, footer.xml, etc.)
+ */
+
+import { Relationship, RelationshipType } from './Relationship';
+import { XMLParser } from '../xml/XMLParser';
+
+/**
+ * Manages relationships for a document or document part
+ */
+export class RelationshipManager {
+  private relationships: Map<string, Relationship>;
+  private nextId: number;
+
+  /**
+   * Creates a new relationship manager
+   */
+  constructor() {
+    this.relationships = new Map();
+    this.nextId = 1;
+  }
+
+  /**
+   * Adds a relationship
+   * @param relationship The relationship to add
+   * @returns The relationship that was added
+   */
+  addRelationship(relationship: Relationship): Relationship {
+    this.relationships.set(relationship.getId(), relationship);
+
+    // Update next ID if necessary
+    const idMatch = /^rId(\d+)$/.exec(relationship.getId());
+    if (idMatch?.[1]) {
+      const idNum = parseInt(idMatch[1], 10);
+      if (idNum >= this.nextId) {
+        this.nextId = idNum + 1;
+      }
+    }
+
+    return relationship;
+  }
+
+  /**
+   * Gets a relationship by ID
+   * @param id The relationship ID
+   */
+  getRelationship(id: string): Relationship | undefined {
+    return this.relationships.get(id);
+  }
+
+  /**
+   * Gets all relationships
+   */
+  getAllRelationships(): Relationship[] {
+    return Array.from(this.relationships.values());
+  }
+
+  /**
+   * Gets relationships of a specific type
+   * @param type The relationship type
+   */
+  getRelationshipsByType(type: string | RelationshipType): Relationship[] {
+    return this.getAllRelationships().filter(rel => rel.getType() === type);
+  }
+
+  /**
+   * Checks if a relationship exists
+   * @param id The relationship ID
+   */
+  hasRelationship(id: string): boolean {
+    return this.relationships.has(id);
+  }
+
+  /**
+   * Removes a relationship
+   * @param id The relationship ID
+   * @returns True if removed, false if not found
+   */
+  removeRelationship(id: string): boolean {
+    return this.relationships.delete(id);
+  }
+
+  /**
+   * Gets the number of relationships
+   */
+  getCount(): number {
+    return this.relationships.size;
+  }
+
+  /**
+   * Clears all relationships
+   */
+  clear(): this {
+    this.relationships.clear();
+    this.nextId = 1;
+    return this;
+  }
+
+  /**
+   * Generates a new unique relationship ID
+   * @returns New relationship ID (e.g., 'rId1', 'rId2')
+   */
+  generateId(): string {
+    return `rId${this.nextId++}`;
+  }
+
+  /**
+   * Adds a styles relationship
+   * @returns The created relationship
+   */
+  addStyles(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createStyles(id));
+  }
+
+  /**
+   * Adds a numbering relationship
+   * @returns The created relationship
+   */
+  addNumbering(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createNumbering(id));
+  }
+
+  /**
+   * Adds a fontTable relationship
+   * @returns The created relationship
+   */
+  addFontTable(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createFontTable(id));
+  }
+
+  /**
+   * Adds a settings relationship
+   * @returns The created relationship
+   */
+  addSettings(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createSettings(id));
+  }
+
+  /**
+   * Adds a webSettings relationship
+   * @returns The created relationship
+   */
+  addWebSettings(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createWebSettings(id));
+  }
+
+  /**
+   * Adds a theme relationship
+   * @returns The created relationship
+   */
+  addTheme(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createTheme(id));
+  }
+
+  /**
+   * Adds an image relationship
+   * @param target Image path relative to the part (e.g., 'media/image1.png')
+   * @returns The created relationship
+   */
+  addImage(target: string): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createImage(id, target));
+  }
+
+  /**
+   * Adds a header relationship
+   * @param target Header file path (e.g., 'header1.xml')
+   * @returns The created relationship
+   */
+  addHeader(target: string): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createHeader(id, target));
+  }
+
+  /**
+   * Adds a footer relationship
+   * @param target Footer file path (e.g., 'footer1.xml')
+   * @returns The created relationship
+   */
+  addFooter(target: string): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createFooter(id, target));
+  }
+
+  /**
+   * Adds a hyperlink relationship
+   * @param url The hyperlink URL
+   * @returns The created relationship
+   */
+  addHyperlink(url: string): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createHyperlink(id, url));
+  }
+
+  /**
+   * Updates the target URL of an existing hyperlink relationship
+   *
+   * This method modifies an existing relationship's target in-place, maintaining
+   * the same relationship ID. This is crucial for proper OpenXML compliance
+   * per ECMA-376 §17.16.22, as it prevents orphaned relationships.
+   *
+   * @param relationshipId The ID of the relationship to update
+   * @param newUrl The new URL to set
+   * @returns True if updated, false if relationship not found
+   */
+  updateHyperlinkTarget(relationshipId: string, newUrl: string): boolean {
+    const relationship = this.getRelationship(relationshipId);
+    if (!relationship) {
+      return false;
+    }
+
+    // Verify this is a hyperlink relationship
+    if (relationship.getType() !== RelationshipType.HYPERLINK) {
+      throw new Error(
+        `Relationship ${relationshipId} is not a hyperlink relationship. ` +
+        `Type is ${relationship.getType()}, expected ${RelationshipType.HYPERLINK}`
+      );
+    }
+
+    // Update the target URL
+    relationship.setTarget(newUrl);
+    return true;
+  }
+
+  /**
+   * Finds a hyperlink relationship by its target URL
+   *
+   * @param targetUrl The URL to search for
+   * @returns The matching relationship, or undefined if not found
+   */
+  findHyperlinkByTarget(targetUrl: string): Relationship | undefined {
+    return this.getAllRelationships().find(
+      rel => rel.getType() === RelationshipType.HYPERLINK && rel.getTarget() === targetUrl
+    );
+  }
+
+  /**
+   * Gets or creates a hyperlink relationship for the given URL
+   *
+   * This method ensures we don't create duplicate relationships for the same URL.
+   * If a relationship already exists for the URL, it returns the existing one.
+   * Otherwise, it creates a new relationship.
+   *
+   * @param url The hyperlink URL
+   * @returns The existing or newly created relationship
+   */
+  getOrCreateHyperlink(url: string): Relationship {
+    // Check if relationship already exists for this URL
+    const existing = this.findHyperlinkByTarget(url);
+    if (existing) {
+      return existing;
+    }
+
+    // Create new relationship
+    return this.addHyperlink(url);
+  }
+
+  /**
+   * Removes orphaned hyperlink relationships
+   *
+   * This method removes hyperlink relationships that are no longer referenced
+   * by any hyperlink in the document. Call this after updating URLs to clean
+   * up any orphaned relationships.
+   *
+   * @param referencedIds Set of relationship IDs that are still in use
+   * @returns Number of relationships removed
+   */
+  removeOrphanedHyperlinks(referencedIds: Set<string>): number {
+    let removed = 0;
+    const toRemove: string[] = [];
+
+    // Find orphaned relationships
+    for (const rel of this.getAllRelationships()) {
+      if (rel.getType() === RelationshipType.HYPERLINK && !referencedIds.has(rel.getId())) {
+        toRemove.push(rel.getId());
+      }
+    }
+
+    // Remove orphaned relationships
+    for (const id of toRemove) {
+      if (this.removeRelationship(id)) {
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+
+  /**
+   * Adds a comments relationship
+   * @returns The created relationship
+   */
+  addComments(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createComments(id));
+  }
+
+  /**
+   * Adds a footnotes relationship
+   * @returns The created relationship
+   */
+  addFootnotes(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createFootnotes(id));
+  }
+
+  /**
+   * Adds an endnotes relationship
+   * @returns The created relationship
+   */
+  addEndnotes(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createEndnotes(id));
+  }
+
+  /**
+   * Adds a people relationship (track changes authors)
+   * @returns The created relationship
+   */
+  addPeople(): Relationship {
+    const id = this.generateId();
+    return this.addRelationship(Relationship.createPeople(id));
+  }
+
+  /**
+   * Generates the relationships XML file content
+   * @returns Complete XML string for .rels file
+   */
+  generateXml(): string {
+    const relationships = this.getAllRelationships();
+
+    let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+    xml += '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">\n';
+
+    for (const rel of relationships) {
+      xml += rel.toXML() + '\n';
+    }
+
+    xml += '</Relationships>';
+
+    return xml;
+  }
+
+  /**
+   * Creates a new relationship manager with common document relationships
+   * @returns RelationshipManager with styles, numbering, fontTable, settings, and theme relationships
+   */
+  static createForDocument(): RelationshipManager {
+    const manager = new RelationshipManager();
+    manager.addStyles();
+    manager.addNumbering();
+    manager.addFontTable();
+    manager.addSettings();
+    manager.addWebSettings();
+    manager.addTheme();
+    return manager;
+  }
+
+  /**
+   * Creates an empty relationship manager
+   * @returns Empty RelationshipManager
+   */
+  static create(): RelationshipManager {
+    return new RelationshipManager();
+  }
+
+  /**
+   * Parses relationships from XML string and creates a populated manager
+   * @param xml The relationships XML content (.rels file)
+   * @returns RelationshipManager with parsed relationships
+   */
+  static fromXml(xml: string): RelationshipManager {
+    const manager = new RelationshipManager();
+
+    // Prevent ReDoS: validate input size (typical .rels files are < 10KB)
+    if (xml.length > 100000) {
+      throw new Error('Relationships XML file too large (>100KB). Possible malicious input or corrupted file.');
+    }
+
+    // Use XMLParser to extract all Relationship elements
+    const relationshipElements = XMLParser.extractElements(xml, 'Relationship');
+
+    // Prevent infinite loops: check relationship count
+    if (relationshipElements.length > 1000) {
+      throw new Error('Too many relationships in XML file (>1000). Possible malicious input.');
+    }
+
+    // Process each relationship element
+    for (const relationshipElement of relationshipElements) {
+      // Extract attributes using XMLParser
+      const id = XMLParser.extractAttribute(relationshipElement, 'Id');
+      const type = XMLParser.extractAttribute(relationshipElement, 'Type');
+      const target = XMLParser.extractAttribute(relationshipElement, 'Target');
+      const targetMode = XMLParser.extractAttribute(relationshipElement, 'TargetMode');
+
+      // Only create relationship if all required attributes present
+      if (id && type && target) {
+        // Validate targetMode before type assertion
+        const validatedTargetMode =
+          targetMode === 'Internal' || targetMode === 'External' || targetMode === undefined
+            ? (targetMode)
+            : undefined;
+
+        // Create and add relationship
+        const relationship = Relationship.create({
+          id,
+          type,
+          target,
+          targetMode: validatedTargetMode || 'Internal',
+        });
+
+        manager.addRelationship(relationship);
+      }
+    }
+
+    return manager;
+  }
+
+}

package/src/elements/AlternateContent.ts

@@ -0,0 +1,42 @@
+/**
+ * AlternateContent - Represents mc:AlternateContent block element
+ *
+ * Per ECMA-376 Part 3 §11.4, mc:AlternateContent provides markup compatibility.
+ * Word uses this for newer features (Word 2010+ shapes as Choice, VML as Fallback).
+ *
+ * Stored as raw XML for round-trip fidelity since the internal structure varies widely.
+ */
+
+import { XMLElement } from '../xml/XMLBuilder';
+
+export class AlternateContent {
+  private rawXml: string;
+
+  constructor(rawXml: string) {
+    this.rawXml = rawXml;
+  }
+
+  /**
+   * Returns the raw XML for round-trip serialization
+   */
+  toXML(): XMLElement {
+    return {
+      name: '__rawXml',
+      rawXml: this.rawXml,
+    } as XMLElement;
+  }
+
+  /**
+   * Gets the raw XML string
+   */
+  getRawXml(): string {
+    return this.rawXml;
+  }
+
+  /**
+   * Returns the element type identifier
+   */
+  getType(): string {
+    return 'alternateContent';
+  }
+}

package/src/elements/Bookmark.ts

@@ -0,0 +1,210 @@
+/**
+ * Bookmark - Represents a bookmark in a Word document
+ *
+ * Bookmarks mark specific locations in a document for internal navigation.
+ * They consist of a start marker and an end marker with matching IDs.
+ */
+
+import { XMLElement } from '../xml/XMLBuilder';
+
+/**
+ * Bookmark properties
+ */
+export interface BookmarkProperties {
+  /** Unique bookmark ID (generated automatically if not provided) */
+  id?: number;
+  /** Bookmark name (must be unique within document) */
+  name: string;
+  /** Skip name normalization (used when loading from existing documents) */
+  skipNormalization?: boolean;
+}
+
+/**
+ * Represents a bookmark location in a document
+ */
+export class Bookmark {
+  private id: number;
+  private name: string;
+
+  /**
+   * Creates a new Bookmark
+   * @param properties - Bookmark properties
+   */
+  constructor(properties: BookmarkProperties) {
+    this.id = properties.id ?? 0; // ID will be assigned by BookmarkManager
+    // Preserve exact bookmark names when loading from documents (Word allows =, ., etc.)
+    // Only normalize when creating new bookmarks programmatically
+    this.name = properties.skipNormalization ? properties.name : this.normalizeName(properties.name);
+  }
+
+  /**
+   * Normalizes a bookmark name to be valid
+   * - Must start with a letter or underscore
+   * - Can only contain letters, numbers, and underscores
+   * - Maximum 40 characters
+   * - Case-insensitive (Word converts to lowercase)
+   * @param name - Raw bookmark name
+   * @returns Normalized bookmark name
+   */
+  private normalizeName(name: string): string {
+    // Remove invalid characters
+    let normalized = name.replace(/[^a-zA-Z0-9_]/g, '_');
+
+    // Ensure it starts with a letter or underscore
+    if (normalized.length > 0 && /^\d/.test(normalized)) {
+      normalized = '_' + normalized;
+    }
+
+    // Limit to 40 characters
+    if (normalized.length > 40) {
+      normalized = normalized.substring(0, 40);
+    }
+
+    // Default if empty
+    if (normalized.length === 0) {
+      normalized = '_bookmark';
+    }
+
+    return normalized;
+  }
+
+  /**
+   * Gets the bookmark ID
+   */
+  getId(): number {
+    return this.id;
+  }
+
+  /**
+   * Sets the bookmark ID (used by BookmarkManager)
+   * @internal
+   */
+  setId(id: number): void {
+    this.id = id;
+  }
+
+  /**
+   * Gets the bookmark name
+   */
+  getName(): string {
+    return this.name;
+  }
+
+  /**
+   * Sets the bookmark name (normalizes the name)
+   *
+   * The name will be normalized:
+   * - Invalid characters replaced with underscores
+   * - Leading digits prefixed with underscore
+   * - Limited to 40 characters
+   *
+   * @param name - New bookmark name
+   * @returns This bookmark for chaining
+   */
+  setName(name: string): this {
+    this.name = this.normalizeName(name);
+    return this;
+  }
+
+  /**
+   * Sets the bookmark name without normalization
+   *
+   * Use this method when:
+   * - Preserving exact names from imported documents
+   * - Setting names with special characters that Word allows (=, ., etc.)
+   * - Round-trip fidelity is required
+   *
+   * **Warning:** Setting invalid bookmark names may cause issues in Word.
+   * Only use this if you know the name is valid or needs to match an existing document.
+   *
+   * @param name - Raw bookmark name (not normalized)
+   * @returns This bookmark for chaining
+   *
+   * @example
+   * ```typescript
+   * // Preserve exact name from Word document
+   * bookmark.setRawName('SECTION=II.MNKE7E8NA385_');
+   *
+   * // For new bookmarks, prefer setName() which normalizes
+   * bookmark.setName('My Heading'); // Becomes 'My_Heading'
+   * ```
+   */
+  setRawName(name: string): this {
+    this.name = name;
+    return this;
+  }
+
+  /**
+   * Generates XML for the bookmark start marker
+   * @returns XMLElement for bookmarkStart
+   */
+  toStartXML(): XMLElement {
+    return {
+      name: 'w:bookmarkStart',
+      attributes: {
+        'w:id': this.id.toString(),
+        'w:name': this.name,
+      },
+      selfClosing: true,
+    };
+  }
+
+  /**
+   * Generates XML for the bookmark end marker
+   * @returns XMLElement for bookmarkEnd
+   */
+  toEndXML(): XMLElement {
+    return {
+      name: 'w:bookmarkEnd',
+      attributes: {
+        'w:id': this.id.toString(),
+      },
+      selfClosing: true,
+    };
+  }
+
+  /**
+   * Generates both start and end XML elements as an array
+   * @returns Array of XMLElements [start, end]
+   */
+  toXML(): [XMLElement, XMLElement] {
+    return [this.toStartXML(), this.toEndXML()];
+  }
+
+  /**
+   * Creates a new Bookmark
+   * @param name - Bookmark name
+   * @returns New Bookmark instance
+   */
+  static create(name: string): Bookmark {
+    return new Bookmark({ name });
+  }
+
+  /**
+   * Creates a bookmark for a heading
+   * Useful for table of contents internal links
+   * @param headingText - The text of the heading
+   * @returns New Bookmark instance with normalized name
+   */
+  static createForHeading(headingText: string): Bookmark {
+    // Create a bookmark name from heading text
+    // Example: "Chapter 1: Introduction" -> "_Chapter_1_Introduction"
+    const name = headingText
+      .trim()
+      .replace(/[^a-zA-Z0-9]+/g, '_')
+      .substring(0, 40);
+    return new Bookmark({ name: name || '_heading' });
+  }
+
+  /**
+   * Creates a bookmark with an auto-generated unique name
+   * @param prefix - Optional prefix for the name (default: 'bookmark')
+   * @returns New Bookmark instance
+   */
+  static createAuto(prefix = 'bookmark'): Bookmark {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 7);
+    const name = `${prefix}_${timestamp}_${random}`;
+    return new Bookmark({ name });
+  }
+}