docxmlater 10.0.2 → 10.0.4

package/src/elements/Endnote.ts

@@ -0,0 +1,217 @@
+/**
+ * Endnote - Represents an endnote in a Word document
+ *
+ * Endnotes appear at the end of the document or section and are referenced
+ * within the document text via endnote references.
+ */
+
+import { Paragraph } from './Paragraph';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+
+/**
+ * Endnote type
+ */
+export enum EndnoteType {
+  /** Normal endnote */
+  Normal = 'normal',
+  /** Separator between document text and endnotes */
+  Separator = 'separator',
+  /** Continuation separator for endnotes that continue to next page */
+  ContinuationSeparator = 'continuationSeparator',
+  /** Continuation notice at bottom of page when endnotes continue */
+  ContinuationNotice = 'continuationNotice',
+}
+
+/**
+ * Endnote properties
+ */
+export interface EndnoteProperties {
+  /** Endnote ID (required, must be unique) */
+  id: number;
+  /** Type of endnote */
+  type?: EndnoteType;
+  /** Custom mark/symbol (optional, otherwise uses numbering) */
+  customMark?: string;
+}
+
+/**
+ * Represents an endnote in a document
+ */
+export class Endnote {
+  private id: number;
+  private type: EndnoteType;
+  private customMark?: string;
+  private paragraphs: Paragraph[] = [];
+
+  /**
+   * Creates a new endnote
+   * @param properties Endnote properties
+   */
+  constructor(properties: EndnoteProperties) {
+    this.id = properties.id;
+    this.type = properties.type || EndnoteType.Normal;
+    this.customMark = properties.customMark;
+  }
+
+  /**
+   * Gets the endnote ID
+   */
+  getId(): number {
+    return this.id;
+  }
+
+  /**
+   * Gets the endnote type
+   */
+  getType(): EndnoteType {
+    return this.type;
+  }
+
+  /**
+   * Gets the custom mark
+   */
+  getCustomMark(): string | undefined {
+    return this.customMark;
+  }
+
+  /**
+   * Sets the custom mark
+   * @param mark Custom mark/symbol
+   */
+  setCustomMark(mark: string): this {
+    this.customMark = mark;
+    return this;
+  }
+
+  /**
+   * Adds a paragraph to the endnote
+   * @param paragraph Paragraph to add
+   */
+  addParagraph(paragraph: Paragraph): this {
+    this.paragraphs.push(paragraph);
+    return this;
+  }
+
+  /**
+   * Creates and adds a new paragraph
+   * @param text Optional text content
+   * @returns The created paragraph
+   */
+  createParagraph(text?: string): Paragraph {
+    const para = new Paragraph();
+    if (text) {
+      para.addText(text);
+    }
+    this.paragraphs.push(para);
+    return para;
+  }
+
+  /**
+   * Gets all paragraphs in the endnote
+   */
+  getParagraphs(): Paragraph[] {
+    return [...this.paragraphs];
+  }
+
+  /**
+   * Gets the text content of the endnote
+   */
+  getText(): string {
+    return this.paragraphs.map(p => p.getText()).join('\n');
+  }
+
+  /**
+   * Generates the XML for this endnote
+   */
+  toXML(): XMLElement {
+    const attrs: Record<string, any> = {
+      'w:id': this.id.toString(),
+    };
+
+    if (this.type !== EndnoteType.Normal) {
+      attrs['w:type'] = this.type;
+    }
+
+    const children: XMLElement[] = [];
+
+    // Separator types require specific child elements per ECMA-376
+    if (this.type === EndnoteType.Separator) {
+      // <w:p><w:r><w:separator/></w:r></w:p>
+      children.push(XMLBuilder.w('p', undefined, [
+        XMLBuilder.w('r', undefined, [XMLBuilder.wSelf('separator')])
+      ]));
+    } else if (this.type === EndnoteType.ContinuationSeparator) {
+      // <w:p><w:r><w:continuationSeparator/></w:r></w:p>
+      children.push(XMLBuilder.w('p', undefined, [
+        XMLBuilder.w('r', undefined, [XMLBuilder.wSelf('continuationSeparator')])
+      ]));
+    } else {
+      // Add paragraphs
+      for (const para of this.paragraphs) {
+        children.push(para.toXML());
+      }
+
+      // If no paragraphs, add an empty one (required)
+      if (children.length === 0) {
+        children.push(XMLBuilder.w('p'));
+      }
+    }
+
+    return XMLBuilder.w('endnote', attrs, children);
+  }
+
+  /**
+   * Creates an endnote from text
+   * @param id Endnote ID
+   * @param text Text content
+   * @returns New endnote instance
+   */
+  static fromText(id: number, text: string): Endnote {
+    const endnote = new Endnote({ id });
+    endnote.createParagraph(text);
+    return endnote;
+  }
+
+  /**
+   * Creates a separator endnote
+   * @param id Endnote ID
+   * @returns New separator endnote
+   */
+  static createSeparator(id: number): Endnote {
+    const endnote = new Endnote({
+      id,
+      type: EndnoteType.Separator
+    });
+    // Separator typically has a horizontal line
+    endnote.createParagraph();
+    // Add separator formatting if needed
+    return endnote;
+  }
+
+  /**
+   * Creates a continuation separator endnote
+   * @param id Endnote ID
+   * @returns New continuation separator endnote
+   */
+  static createContinuationSeparator(id: number): Endnote {
+    return new Endnote({
+      id,
+      type: EndnoteType.ContinuationSeparator
+    });
+  }
+
+  /**
+   * Creates a continuation notice endnote
+   * @param id Endnote ID
+   * @param text Notice text (e.g., "Continued on next page...")
+   * @returns New continuation notice endnote
+   */
+  static createContinuationNotice(id: number, text = 'Continued...'): Endnote {
+    const endnote = new Endnote({
+      id,
+      type: EndnoteType.ContinuationNotice
+    });
+    endnote.createParagraph(text);
+    return endnote;
+  }
+}

package/src/elements/EndnoteManager.ts

@@ -0,0 +1,249 @@
+/**
+ * EndnoteManager - Manages endnotes in a document
+ *
+ * Handles creation, registration, and XML generation for endnotes.
+ * Maintains unique IDs and proper ordering.
+ */
+
+import { Endnote, EndnoteType } from './Endnote';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+import { XMLParser } from '../xml/XMLParser';
+
+/**
+ * Manages endnotes in a document
+ */
+export class EndnoteManager {
+  private endnotes = new Map<number, Endnote>();
+  private nextId = 1;
+
+  /**
+   * Creates a new EndnoteManager
+   * @private Use static factory method
+   */
+  private constructor() {
+    // Add special endnotes (separators) with negative IDs
+    this.addSpecialEndnotes();
+  }
+
+  /**
+   * Adds special endnotes (separator, continuation)
+   * These use negative IDs as per OOXML specification
+   */
+  private addSpecialEndnotes(): void {
+    // Separator endnote (ID -1)
+    const separator = Endnote.createSeparator(-1);
+    this.endnotes.set(-1, separator);
+
+    // Continuation separator (ID 0)
+    const continuationSep = Endnote.createContinuationSeparator(0);
+    this.endnotes.set(0, continuationSep);
+  }
+
+  /**
+   * Checks if an endnote is a special/system type (separator, continuationSeparator,
+   * continuationNotice) that should be preserved across clear() operations.
+   * Uses type-based detection rather than ID-based, because continuationNotice
+   * has a positive ID (typically 1) but is still a system endnote.
+   */
+  private isSpecialEndnote(endnote: Endnote): boolean {
+    const type = endnote.getType();
+    return type === EndnoteType.Separator ||
+           type === EndnoteType.ContinuationSeparator ||
+           type === EndnoteType.ContinuationNotice;
+  }
+
+  /**
+   * Creates a new EndnoteManager instance
+   */
+  static create(): EndnoteManager {
+    return new EndnoteManager();
+  }
+
+  /**
+   * Registers an endnote
+   * @param endnote Endnote to register
+   * @returns The registered endnote
+   */
+  register(endnote: Endnote): Endnote {
+    const id = endnote.getId();
+
+    // Ensure ID is not already used (except for special endnotes)
+    if (id > 0 && this.endnotes.has(id)) {
+      throw new Error(`Endnote with ID ${id} already exists`);
+    }
+
+    this.endnotes.set(id, endnote);
+
+    // Update next ID if needed
+    if (id >= this.nextId) {
+      this.nextId = id + 1;
+    }
+
+    return endnote;
+  }
+
+  /**
+   * Creates and registers a new endnote
+   * @param text Endnote text
+   * @returns The created endnote
+   */
+  createEndnote(text: string): Endnote {
+    const endnote = Endnote.fromText(this.nextId++, text);
+    this.endnotes.set(endnote.getId(), endnote);
+    return endnote;
+  }
+
+  /**
+   * Gets an endnote by ID
+   * @param id Endnote ID
+   * @returns The endnote, or undefined if not found
+   */
+  getEndnote(id: number): Endnote | undefined {
+    return this.endnotes.get(id);
+  }
+
+  /**
+   * Gets all user endnotes (excluding special system types: separator,
+   * continuationSeparator, continuationNotice)
+   */
+  getAllEndnotes(): Endnote[] {
+    return Array.from(this.endnotes.values())
+      .filter(e => !this.isSpecialEndnote(e))
+      .sort((a, b) => a.getId() - b.getId());
+  }
+
+  /**
+   * Gets all endnotes including special ones
+   */
+  getAllEndnotesWithSpecial(): Endnote[] {
+    return Array.from(this.endnotes.values())
+      .sort((a, b) => a.getId() - b.getId());
+  }
+
+  /**
+   * Checks if an endnote exists
+   * @param id Endnote ID
+   */
+  hasEndnote(id: number): boolean {
+    return this.endnotes.has(id);
+  }
+
+  /**
+   * Removes an endnote
+   * @param id Endnote ID
+   * @returns True if removed, false if not found or if it's a special type
+   */
+  removeEndnote(id: number): boolean {
+    const endnote = this.endnotes.get(id);
+    if (!endnote || this.isSpecialEndnote(endnote)) {
+      return false;
+    }
+    return this.endnotes.delete(id);
+  }
+
+  /**
+   * Gets the next available ID
+   */
+  getNextId(): number {
+    return this.nextId;
+  }
+
+  /**
+   * Gets the count of endnotes (excluding special ones)
+   */
+  getCount(): number {
+    return this.getAllEndnotes().length;
+  }
+
+  /**
+   * Checks if there are any endnotes (excluding special ones)
+   */
+  isEmpty(): boolean {
+    return this.getCount() === 0;
+  }
+
+  /**
+   * Clears all user endnotes (preserves special system types: separator,
+   * continuationSeparator, continuationNotice)
+   */
+  clear(): void {
+    const specialEndnotes = new Map<number, Endnote>();
+    let maxSpecialId = 0;
+
+    for (const [id, endnote] of this.endnotes) {
+      if (this.isSpecialEndnote(endnote)) {
+        specialEndnotes.set(id, endnote);
+        if (id > maxSpecialId) {
+          maxSpecialId = id;
+        }
+      }
+    }
+
+    this.endnotes = specialEndnotes;
+    // Ensure nextId doesn't collide with special endnotes that have positive IDs
+    this.nextId = Math.max(maxSpecialId + 1, 1);
+  }
+
+  /**
+   * Gets statistics about endnotes
+   */
+  getStats(): {
+    total: number;
+    nextId: number;
+  } {
+    return {
+      total: this.getCount(),
+      nextId: this.nextId,
+    };
+  }
+
+  /**
+   * Generates the endnotes.xml content
+   */
+  generateEndnotesXml(): string {
+    const endnotes = this.getAllEndnotesWithSpecial();
+
+    // Build endnotes element
+    const endnotesElement: XMLElement = {
+      name: 'w:endnotes',
+      attributes: {
+        'xmlns:w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
+        'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
+      },
+      children: endnotes.map(e => e.toXML())
+    };
+
+    // Build XML using XMLBuilder
+    const builder = new XMLBuilder();
+    builder.element(
+      endnotesElement.name,
+      endnotesElement.attributes,
+      endnotesElement.children
+    );
+    return builder.build(true);
+  }
+
+  /**
+   * Validates endnotes XML
+   * @param xml XML string to validate
+   * @returns True if valid
+   */
+  static validate(xml: string): boolean {
+    // Use XMLParser to extract root element
+    if (!xml) {
+      return false;
+    }
+
+    const endnotesContent = XMLParser.extractBetweenTags(xml, '<w:endnotes', '</w:endnotes>');
+    if (!endnotesContent) {
+      return false;
+    }
+
+    // Check for proper structure - namespace declaration
+    if (!xml.includes('xmlns:w=')) {
+      return false;
+    }
+
+    return true;
+  }
+}