docxmlater 10.0.1 → 10.0.3

package/src/elements/FootnoteManager.ts

@@ -0,0 +1,249 @@
+/**
+ * FootnoteManager - Manages footnotes in a document
+ *
+ * Handles creation, registration, and XML generation for footnotes.
+ * Maintains unique IDs and proper ordering.
+ */
+
+import { Footnote, FootnoteType } from './Footnote';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+import { XMLParser } from '../xml/XMLParser';
+
+/**
+ * Manages footnotes in a document
+ */
+export class FootnoteManager {
+  private footnotes = new Map<number, Footnote>();
+  private nextId = 1;
+
+  /**
+   * Creates a new FootnoteManager
+   * @private Use static factory method
+   */
+  private constructor() {
+    // Add special footnotes (separators) with negative IDs
+    this.addSpecialFootnotes();
+  }
+
+  /**
+   * Adds special footnotes (separator, continuation)
+   * These use negative IDs as per OOXML specification
+   */
+  private addSpecialFootnotes(): void {
+    // Separator footnote (ID -1)
+    const separator = Footnote.createSeparator(-1);
+    this.footnotes.set(-1, separator);
+
+    // Continuation separator (ID 0)
+    const continuationSep = Footnote.createContinuationSeparator(0);
+    this.footnotes.set(0, continuationSep);
+  }
+
+  /**
+   * Checks if a footnote 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 footnote.
+   */
+  private isSpecialFootnote(footnote: Footnote): boolean {
+    const type = footnote.getType();
+    return type === FootnoteType.Separator ||
+           type === FootnoteType.ContinuationSeparator ||
+           type === FootnoteType.ContinuationNotice;
+  }
+
+  /**
+   * Creates a new FootnoteManager instance
+   */
+  static create(): FootnoteManager {
+    return new FootnoteManager();
+  }
+
+  /**
+   * Registers a footnote
+   * @param footnote Footnote to register
+   * @returns The registered footnote
+   */
+  register(footnote: Footnote): Footnote {
+    const id = footnote.getId();
+
+    // Ensure ID is not already used (except for special footnotes)
+    if (id > 0 && this.footnotes.has(id)) {
+      throw new Error(`Footnote with ID ${id} already exists`);
+    }
+
+    this.footnotes.set(id, footnote);
+
+    // Update next ID if needed
+    if (id >= this.nextId) {
+      this.nextId = id + 1;
+    }
+
+    return footnote;
+  }
+
+  /**
+   * Creates and registers a new footnote
+   * @param text Footnote text
+   * @returns The created footnote
+   */
+  createFootnote(text: string): Footnote {
+    const footnote = Footnote.fromText(this.nextId++, text);
+    this.footnotes.set(footnote.getId(), footnote);
+    return footnote;
+  }
+
+  /**
+   * Gets a footnote by ID
+   * @param id Footnote ID
+   * @returns The footnote, or undefined if not found
+   */
+  getFootnote(id: number): Footnote | undefined {
+    return this.footnotes.get(id);
+  }
+
+  /**
+   * Gets all user footnotes (excluding special system types: separator,
+   * continuationSeparator, continuationNotice)
+   */
+  getAllFootnotes(): Footnote[] {
+    return Array.from(this.footnotes.values())
+      .filter(f => !this.isSpecialFootnote(f))
+      .sort((a, b) => a.getId() - b.getId());
+  }
+
+  /**
+   * Gets all footnotes including special ones
+   */
+  getAllFootnotesWithSpecial(): Footnote[] {
+    return Array.from(this.footnotes.values())
+      .sort((a, b) => a.getId() - b.getId());
+  }
+
+  /**
+   * Checks if a footnote exists
+   * @param id Footnote ID
+   */
+  hasFootnote(id: number): boolean {
+    return this.footnotes.has(id);
+  }
+
+  /**
+   * Removes a footnote
+   * @param id Footnote ID
+   * @returns True if removed, false if not found or if it's a special type
+   */
+  removeFootnote(id: number): boolean {
+    const footnote = this.footnotes.get(id);
+    if (!footnote || this.isSpecialFootnote(footnote)) {
+      return false;
+    }
+    return this.footnotes.delete(id);
+  }
+
+  /**
+   * Gets the next available ID
+   */
+  getNextId(): number {
+    return this.nextId;
+  }
+
+  /**
+   * Gets the count of footnotes (excluding special ones)
+   */
+  getCount(): number {
+    return this.getAllFootnotes().length;
+  }
+
+  /**
+   * Checks if there are any footnotes (excluding special ones)
+   */
+  isEmpty(): boolean {
+    return this.getCount() === 0;
+  }
+
+  /**
+   * Clears all user footnotes (preserves special system types: separator,
+   * continuationSeparator, continuationNotice)
+   */
+  clear(): void {
+    const specialFootnotes = new Map<number, Footnote>();
+    let maxSpecialId = 0;
+
+    for (const [id, footnote] of this.footnotes) {
+      if (this.isSpecialFootnote(footnote)) {
+        specialFootnotes.set(id, footnote);
+        if (id > maxSpecialId) {
+          maxSpecialId = id;
+        }
+      }
+    }
+
+    this.footnotes = specialFootnotes;
+    // Ensure nextId doesn't collide with special footnotes that have positive IDs
+    this.nextId = Math.max(maxSpecialId + 1, 1);
+  }
+
+  /**
+   * Gets statistics about footnotes
+   */
+  getStats(): {
+    total: number;
+    nextId: number;
+  } {
+    return {
+      total: this.getCount(),
+      nextId: this.nextId,
+    };
+  }
+
+  /**
+   * Generates the footnotes.xml content
+   */
+  generateFootnotesXml(): string {
+    const footnotes = this.getAllFootnotesWithSpecial();
+
+    // Build footnotes element
+    const footnotesElement: XMLElement = {
+      name: 'w:footnotes',
+      attributes: {
+        'xmlns:w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
+        'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
+      },
+      children: footnotes.map(f => f.toXML())
+    };
+
+    // Build XML using XMLBuilder
+    const builder = new XMLBuilder();
+    builder.element(
+      footnotesElement.name,
+      footnotesElement.attributes,
+      footnotesElement.children
+    );
+    return builder.build(true);
+  }
+
+  /**
+   * Validates footnotes 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 footnotesContent = XMLParser.extractBetweenTags(xml, '<w:footnotes', '</w:footnotes>');
+    if (!footnotesContent) {
+      return false;
+    }
+
+    // Check for proper structure - namespace declaration
+    if (!xml.includes('xmlns:w=')) {
+      return false;
+    }
+
+    return true;
+  }
+}

package/src/elements/Header.ts

@@ -0,0 +1,269 @@
+/**
+ * Header - Represents a document header
+ *
+ * Headers appear at the top of pages and can contain text, tables, images, and fields.
+ * Different headers can be defined for first page, odd pages, and even pages.
+ */
+
+import { XMLElement } from '../xml/XMLBuilder';
+import { Paragraph } from './Paragraph';
+import { Table } from './Table';
+
+/**
+ * Header type
+ */
+export type HeaderType = 'default' | 'first' | 'even';
+
+/**
+ * Header content element
+ */
+type HeaderElement = Paragraph | Table;
+
+/**
+ * Header properties
+ */
+export interface HeaderProperties {
+  /** Header type (default, first page, or even page) */
+  type?: HeaderType;
+}
+
+/**
+ * Represents a document header
+ */
+export class Header {
+  private elements: HeaderElement[] = [];
+  private type: HeaderType;
+  private headerId?: string;
+  private rawXML?: string; // Store original XML for preservation
+
+  /**
+   * Creates a new header
+   * @param properties Header properties
+   */
+  constructor(properties: HeaderProperties = {}) {
+    this.type = properties.type || 'default';
+  }
+
+  /**
+   * Sets the raw XML content (used when loading existing headers)
+   * @param xml Raw XML content
+   */
+  setRawXML(xml: string): this {
+    this.rawXML = xml;
+    return this;
+  }
+
+  /**
+   * Gets the raw XML content if available
+   */
+  getRawXML(): string | undefined {
+    return this.rawXML;
+  }
+
+  /**
+   * Gets the header type
+   */
+  getType(): HeaderType {
+    return this.type;
+  }
+
+  /**
+   * Sets the header ID (used for relationships)
+   * @param id Header ID
+   */
+  setHeaderId(id: string): this {
+    this.headerId = id;
+    return this;
+  }
+
+  /**
+   * Gets the header ID
+   */
+  getHeaderId(): string | undefined {
+    return this.headerId;
+  }
+
+  /**
+   * Adds a paragraph to the header
+   * @param paragraph Paragraph to add
+   */
+  addParagraph(paragraph: Paragraph): this {
+    this.elements.push(paragraph);
+    return this;
+  }
+
+  /**
+   * Creates and adds a new paragraph
+   * @param text Optional text content
+   */
+  createParagraph(text?: string): Paragraph {
+    const para = new Paragraph();
+    if (text) {
+      para.addText(text);
+    }
+    this.elements.push(para);
+    return para;
+  }
+
+  /**
+   * Adds a table to the header
+   * @param table Table to add
+   */
+  addTable(table: Table): this {
+    this.elements.push(table);
+    return this;
+  }
+
+  /**
+   * Creates and adds a new table
+   * @param rows Number of rows
+   * @param columns Number of columns
+   */
+  createTable(rows: number, columns: number): Table {
+    const table = new Table(rows, columns);
+    this.elements.push(table);
+    return table;
+  }
+
+  /**
+   * Gets all elements in the header
+   */
+  getElements(): HeaderElement[] {
+    return [...this.elements];
+  }
+
+  /**
+   * Gets the number of elements
+   */
+  getElementCount(): number {
+    return this.elements.length;
+  }
+
+  /**
+   * Clears all elements and resets raw XML so toXML() regenerates an empty header
+   */
+  clear(): this {
+    this.elements = [];
+    this.rawXML = undefined;
+    return this;
+  }
+
+  /**
+   * Generates the complete header XML file content
+   * This creates a complete header document (header1.xml, etc.)
+   */
+  toXML(): string {
+    // If we have raw XML preserved from loading, use it
+    if (this.rawXML) {
+      return this.rawXML;
+    }
+
+    // Otherwise generate from elements
+    const elementXmls = this.elements.map(el => el.toXML());
+
+    let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+    xml += '<w:hdr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" ';
+    xml += 'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">\n';
+
+    // Add elements
+    for (const element of elementXmls) {
+      xml += this.renderElement(element, 1);
+    }
+
+    // If no elements, add an empty paragraph
+    if (this.elements.length === 0) {
+      xml += '  <w:p/>\n';
+    }
+
+    xml += '</w:hdr>';
+
+    return xml;
+  }
+
+  /**
+   * Renders an XML element to string with indentation
+   */
+  private renderElement(element: XMLElement, indent: number): string {
+    const spaces = '  '.repeat(indent);
+    let xml = '';
+
+    if (element.selfClosing) {
+      xml += `${spaces}<${element.name}`;
+      if (element.attributes) {
+        for (const [key, value] of Object.entries(element.attributes)) {
+          xml += ` ${key}="${value}"`;
+        }
+      }
+      xml += '/>\n';
+    } else {
+      xml += `${spaces}<${element.name}`;
+      if (element.attributes) {
+        for (const [key, value] of Object.entries(element.attributes)) {
+          xml += ` ${key}="${value}"`;
+        }
+      }
+      xml += '>';
+
+      if (element.children && element.children.length > 0) {
+        const hasOnlyText = element.children.every(c => typeof c === 'string');
+
+        if (hasOnlyText) {
+          // Inline text content
+          xml += element.children.join('');
+        } else {
+          // Block-level children
+          xml += '\n';
+          for (const child of element.children) {
+            if (typeof child === 'string') {
+              xml += spaces + '  ' + child + '\n';
+            } else {
+              xml += this.renderElement(child, indent + 1);
+            }
+          }
+          xml += spaces;
+        }
+      }
+
+      xml += `</${element.name}>\n`;
+    }
+
+    return xml;
+  }
+
+  /**
+   * Gets the filename for this header
+   * @param number Header number (1, 2, 3, etc.)
+   */
+  getFilename(number: number): string {
+    return `header${number}.xml`;
+  }
+
+  /**
+   * Creates a default header
+   */
+  static createDefault(): Header {
+    return new Header({ type: 'default' });
+  }
+
+  /**
+   * Creates a first page header
+   */
+  static createFirst(): Header {
+    return new Header({ type: 'first' });
+  }
+
+  /**
+   * Creates an even page header
+   */
+  static createEven(): Header {
+    return new Header({ type: 'even' });
+  }
+
+  /**
+   * Creates a header with properties
+   * @param properties Header properties
+   */
+  static create(properties?: HeaderProperties): Header {
+    return new Header(properties);
+  }
+}