docxmlater 10.0.2 → 10.0.3

package/src/elements/FieldHelpers.ts

@@ -0,0 +1,333 @@
+/**
+ * Helper functions for creating complex and nested fields
+ */
+
+import { ComplexField } from './Field';
+import { defaultLogger } from '../utils/logger';
+
+/**
+ * Parsed components of a HYPERLINK field instruction
+ */
+export interface ParsedHyperlinkInstruction {
+  /** Base URL (with encoded characters decoded) */
+  url: string;
+  /** Anchor/fragment from \l switch (decoded) */
+  anchor?: string;
+  /** Tooltip text from \o switch */
+  tooltip?: string;
+  /** Whether \h switch is present (creates hyperlink) */
+  hasHSwitch: boolean;
+  /** Combined full URL (url + "#" + anchor if both present) */
+  fullUrl: string;
+  /** Original raw instruction string */
+  rawInstruction: string;
+}
+
+/**
+ * Parses a HYPERLINK field instruction string into its components
+ *
+ * HYPERLINK field syntax per ECMA-376:
+ * - HYPERLINK "url" - basic external hyperlink
+ * - HYPERLINK \l "anchor" - anchor-only internal hyperlink (no URL)
+ * - \l "anchor" - specifies a location (anchor/fragment) within the target
+ * - \o "tooltip" - specifies the tooltip/screentip text
+ * - \h - creates a hyperlink (always present for clickable links)
+ * - \n - opens link in new window
+ * - \t "target" - specifies target frame
+ *
+ * @param instruction The raw field instruction string (e.g., 'HYPERLINK "url" \l "anchor" \h')
+ * @returns Parsed components or null if not a valid HYPERLINK instruction
+ *
+ * @example
+ * ```typescript
+ * // External hyperlink with anchor
+ * const result = parseHyperlinkInstruction('HYPERLINK "https://example.com/" \\l "section1" \\h');
+ * // result.url = "https://example.com/"
+ * // result.anchor = "section1"
+ * // result.fullUrl = "https://example.com/#section1"
+ *
+ * // Anchor-only internal hyperlink (e.g., "Top of the Document")
+ * const result2 = parseHyperlinkInstruction('HYPERLINK \\l "_top" \\h');
+ * // result2.url = ""
+ * // result2.anchor = "_top"
+ * // result2.fullUrl = "#_top"
+ * ```
+ */
+export function parseHyperlinkInstruction(instruction: string): ParsedHyperlinkInstruction | null {
+  if (!instruction) {
+    return null;
+  }
+
+  // Normalize whitespace and trim
+  const normalized = instruction.trim();
+
+  // Check if this is a HYPERLINK instruction
+  if (!normalized.toUpperCase().startsWith('HYPERLINK')) {
+    return null;
+  }
+
+  // Extract the URL (first quoted string after HYPERLINK, before any switches)
+  // URL is optional - anchor-only hyperlinks like 'HYPERLINK \l "_top"' are valid
+  let url = '';
+  const urlMatch = /HYPERLINK\s+"([^"]*)"/i.exec(normalized);
+  if (urlMatch?.[1] !== undefined) {
+    url = urlMatch[1];
+    // Decode URL-encoded characters
+    try {
+      url = decodeURIComponent(url);
+    } catch (e) {
+      defaultLogger.debug(`[FieldHelpers] Failed to decode URL: ${url}`);
+    }
+  }
+
+  // Extract \l switch (anchor/fragment)
+  let anchor: string | undefined;
+  const anchorMatch = /\\l\s+"([^"]*)"/i.exec(normalized);
+  if (anchorMatch?.[1] !== undefined) {
+    anchor = anchorMatch[1];
+    // Decode anchor as well
+    try {
+      anchor = decodeURIComponent(anchor);
+    } catch (e) {
+      defaultLogger.debug(`[FieldHelpers] Failed to decode anchor: ${anchor}`);
+    }
+  }
+
+  // Must have either URL or anchor to be valid
+  if (!url && !anchor) {
+    return null;
+  }
+
+  // Extract \o switch (tooltip)
+  let tooltip: string | undefined;
+  const tooltipMatch = /\\o\s+"([^"]*)"/i.exec(normalized);
+  if (tooltipMatch?.[1] !== undefined) {
+    tooltip = tooltipMatch[1];
+  }
+
+  // Check for \h switch
+  const hasHSwitch = /\\h(?:\s|$)/i.test(normalized);
+
+  // Build full URL by combining base URL and anchor
+  let fullUrl: string = url;
+  if (anchor) {
+    // If URL already has a fragment, replace it; otherwise append
+    const hashIndex = url.indexOf('#');
+    if (hashIndex >= 0) {
+      fullUrl = url.substring(0, hashIndex) + '#' + anchor;
+    } else if (url) {
+      fullUrl = url + '#' + anchor;
+    } else {
+      // Anchor-only: just use #anchor
+      fullUrl = '#' + anchor;
+    }
+  }
+
+  return {
+    url,
+    anchor,
+    tooltip,
+    hasHSwitch,
+    fullUrl,
+    rawInstruction: instruction,
+  };
+}
+
+/**
+ * Creates a HYPERLINK field instruction string from components
+ *
+ * @param url The target URL
+ * @param anchor Optional anchor/fragment (will use \l switch)
+ * @param tooltip Optional tooltip text (will use \o switch)
+ * @returns Properly formatted HYPERLINK instruction string
+ *
+ * @example
+ * ```typescript
+ * const instr = buildHyperlinkInstruction('https://example.com/', 'section1', 'Click here');
+ * // Returns: 'HYPERLINK "https://example.com/" \\l "section1" \\o "Click here" \\h'
+ * ```
+ */
+export function buildHyperlinkInstruction(
+  url: string,
+  anchor?: string,
+  tooltip?: string
+): string {
+  let instruction = `HYPERLINK "${url}"`;
+
+  if (anchor) {
+    instruction += ` \\l "${anchor}"`;
+  }
+
+  if (tooltip) {
+    instruction += ` \\o "${tooltip}"`;
+  }
+
+  // Always add \h switch for clickable hyperlinks
+  instruction += ' \\h';
+
+  return instruction;
+}
+
+/**
+ * Checks if a field instruction is a HYPERLINK field
+ *
+ * @param instruction The field instruction to check
+ * @returns True if the instruction is a HYPERLINK field
+ */
+export function isHyperlinkInstruction(instruction: string): boolean {
+  if (!instruction) {
+    return false;
+  }
+  return instruction.trim().toUpperCase().startsWith('HYPERLINK');
+}
+
+/**
+ * Creates a nested IF field containing a MERGEFIELD
+ * This is a common pattern for conditional mail merge
+ *
+ * @param condition The IF condition (e.g., 'Status = "Active"')
+ * @param mergeFieldName The merge field name to include
+ * @param trueText Text to show when condition is true
+ * @param falseText Text to show when condition is false
+ * @returns ComplexField with nested MERGEFIELD
+ *
+ * @example
+ * ```typescript
+ * const field = createNestedIFMergeField('Status = "Active"', 'Name', 'Active: ', 'Inactive');
+ * // Result: IF field that shows "Active: [Name]" if Status is Active, otherwise "Inactive"
+ * ```
+ */
+export function createNestedIFMergeField(
+  condition: string,
+  mergeFieldName: string,
+  trueText = '',
+  falseText = ''
+): ComplexField {
+  // Create the nested MERGEFIELD
+  const mergeField = new ComplexField({
+    instruction: ` MERGEFIELD ${mergeFieldName} `,
+    result: `[${mergeFieldName}]`,
+  });
+
+  // Create the IF field with nested MERGEFIELD
+  const ifField = new ComplexField({
+    instruction: ` IF ${condition} "${trueText}" "${falseText}" `,
+    result: trueText || falseText,
+  });
+
+  ifField.addNestedField(mergeField);
+
+  return ifField;
+}
+
+/**
+ * Creates a MERGEFIELD with custom formatting
+ *
+ * @param fieldName The merge field name
+ * @param format Optional format switches
+ * @returns ComplexField for MERGEFIELD
+ *
+ * @example
+ * ```typescript
+ * const field = createMergeField('Date', '\\@ "MMMM d, yyyy"');
+ * ```
+ */
+export function createMergeField(fieldName: string, format?: string): ComplexField {
+  let instruction = ` MERGEFIELD ${fieldName}`;
+
+  if (format) {
+    instruction += ` ${format}`;
+  }
+
+  instruction += ' \\* MERGEFORMAT ';
+
+  return new ComplexField({
+    instruction,
+    result: `[${fieldName}]`,
+  });
+}
+
+/**
+ * Creates a REF field with a nested field in the bookmark reference
+ * Used for complex cross-references
+ *
+ * @param bookmarkName The bookmark to reference
+ * @param format Optional format switches
+ * @returns ComplexField for REF
+ *
+ * @example
+ * ```typescript
+ * const field = createRefField('Chapter1', '\\h');
+ * ```
+ */
+export function createRefField(bookmarkName: string, format?: string): ComplexField {
+  let instruction = ` REF ${bookmarkName}`;
+
+  if (format) {
+    instruction += ` ${format}`;
+  } else {
+    instruction += ' \\h'; // Hyperlink by default
+  }
+
+  instruction += ' \\* MERGEFORMAT ';
+
+  return new ComplexField({
+    instruction,
+    result: `[${bookmarkName}]`,
+  });
+}
+
+/**
+ * Creates an IF field with custom true/false branches
+ *
+ * @param condition The condition to evaluate
+ * @param trueContent Content to show when true
+ * @param falseContent Content to show when false
+ * @returns ComplexField for IF
+ *
+ * @example
+ * ```typescript
+ * const field = createIFField('Amount > 1000', 'High Value', 'Normal');
+ * ```
+ */
+export function createIFField(
+  condition: string,
+  trueContent: string,
+  falseContent = ''
+): ComplexField {
+  const instruction = ` IF ${condition} "${trueContent}" "${falseContent}" `;
+
+  return new ComplexField({
+    instruction,
+    result: trueContent,
+  });
+}
+
+/**
+ * Creates a complex nested field structure with multiple levels
+ * Useful for advanced scenarios like nested IF statements
+ *
+ * @param outerInstruction The outer field instruction
+ * @param nestedFields Array of nested fields to include
+ * @returns ComplexField with nested structure
+ *
+ * @example
+ * ```typescript
+ * const innerField = createMergeField('Amount');
+ * const field = createNestedField('IF Amount > 0', [innerField]);
+ * ```
+ */
+export function createNestedField(
+  outerInstruction: string,
+  nestedFields: ComplexField[]
+): ComplexField {
+  const field = new ComplexField({
+    instruction: outerInstruction,
+  });
+
+  for (const nested of nestedFields) {
+    field.addNestedField(nested);
+  }
+
+  return field;
+}

package/src/elements/FontManager.ts

@@ -0,0 +1,339 @@
+/**
+ * FontManager - Manages embedded fonts in DOCX documents
+ * Handles font registration and Content_Types.xml updates
+ */
+
+/**
+ * Font format types supported in DOCX
+ */
+export type FontFormat = 'ttf' | 'otf' | 'woff' | 'woff2';
+
+/**
+ * Font entry information
+ */
+export interface FontEntry {
+  /** Font file name (e.g., 'arial.ttf') */
+  filename: string;
+  /** Font format */
+  format: FontFormat;
+  /** Font family name (e.g., 'Arial') */
+  fontFamily: string;
+  /** Font data (Buffer) */
+  data: Buffer;
+  /** Path in DOCX archive (e.g., 'word/fonts/arial.ttf') */
+  path: string;
+}
+
+/**
+ * FontManager handles embedded fonts in documents
+ * Ensures fonts are properly registered in [Content_Types].xml
+ */
+export class FontManager {
+  private fonts = new Map<string, FontEntry>();
+  private static fontCounter = 1;
+
+  /**
+   * Creates a new FontManager
+   */
+  constructor() {
+    // Empty constructor
+  }
+
+  /**
+   * Factory method to create a new FontManager
+   */
+  static create(): FontManager {
+    return new FontManager();
+  }
+
+  /**
+   * Adds a font to the document
+   * @param fontFamily - Font family name (e.g., 'Arial', 'Times New Roman')
+   * @param data - Font file data as Buffer
+   * @param format - Font format (ttf, otf, woff, woff2)
+   * @returns Font path in the archive
+   */
+  addFont(fontFamily: string, data: Buffer, format: FontFormat = 'ttf'): string {
+    // Generate unique filename
+    const sanitizedFamily = this.sanitizeFontName(fontFamily);
+    const filename = `${sanitizedFamily}_${FontManager.fontCounter++}.${format}`;
+    const path = `word/fonts/${filename}`;
+
+    // Create font entry
+    const entry: FontEntry = {
+      filename,
+      format,
+      fontFamily,
+      data,
+      path,
+    };
+
+    // Store with path as key for easy lookup
+    this.fonts.set(path, entry);
+
+    return path;
+  }
+
+  /**
+   * Adds a font from a file path
+   * @param fontFamily - Font family name
+   * @param filePath - Path to font file
+   * @param format - Font format (optional, detected from extension)
+   * @returns Font path in the archive
+   */
+  async addFontFromFile(
+    fontFamily: string,
+    filePath: string,
+    format?: FontFormat
+  ): Promise<string> {
+    const fs = require('fs').promises;
+
+    // Detect format from extension if not provided
+    if (!format) {
+      const ext = filePath.split('.').pop()?.toLowerCase();
+      if (ext === 'ttf' || ext === 'otf' || ext === 'woff' || ext === 'woff2') {
+        format = ext as FontFormat;
+      } else {
+        throw new Error(`Unable to detect font format from file: ${filePath}`);
+      }
+    }
+
+    // Read font file
+    const data = await fs.readFile(filePath);
+
+    return this.addFont(fontFamily, data, format);
+  }
+
+  /**
+   * Checks if a font exists
+   * @param fontFamily - Font family name
+   * @returns True if font is registered
+   */
+  hasFont(fontFamily: string): boolean {
+    for (const entry of this.fonts.values()) {
+      if (entry.fontFamily === fontFamily) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Gets all registered fonts
+   * @returns Array of font entries
+   */
+  getAllFonts(): FontEntry[] {
+    return Array.from(this.fonts.values());
+  }
+
+  /**
+   * Gets font count
+   * @returns Number of fonts
+   */
+  getCount(): number {
+    return this.fonts.size;
+  }
+
+  /**
+   * Gets MIME type for font format
+   * @param format - Font format
+   * @returns MIME type string
+   */
+  static getMimeType(format: FontFormat): string {
+    const mimeTypes: Record<FontFormat, string> = {
+      ttf: 'application/x-font-ttf',
+      otf: 'application/x-font-opentype',
+      woff: 'application/font-woff',
+      woff2: 'font/woff2',
+    };
+
+    return mimeTypes[format] || 'application/octet-stream';
+  }
+
+  /**
+   * Gets all unique font extensions
+   * @returns Set of extensions (e.g., 'ttf', 'otf')
+   */
+  getExtensions(): Set<string> {
+    const extensions = new Set<string>();
+    for (const entry of this.fonts.values()) {
+      extensions.add(entry.format);
+    }
+    return extensions;
+  }
+
+  /**
+   * Generates Content_Types.xml entries for fonts
+   * @returns Array of XML strings
+   */
+  generateContentTypeEntries(): string[] {
+    const entries: string[] = [];
+    const extensions = this.getExtensions();
+
+    // Add Default entries for each extension
+    for (const ext of extensions) {
+      const mimeType = FontManager.getMimeType(ext as FontFormat);
+      entries.push(`  <Default Extension="${ext}" ContentType="${mimeType}"/>`);
+    }
+
+    return entries;
+  }
+
+  /**
+   * Sanitizes font name for use in filename
+   * @param fontName - Font family name
+   * @returns Sanitized name safe for filename
+   */
+  private sanitizeFontName(fontName: string): string {
+    // Remove spaces and special characters
+    return fontName
+      .toLowerCase()
+      .replace(/\s+/g, '_')
+      .replace(/[^a-z0-9_-]/g, '')
+      .substring(0, 50); // Limit length
+  }
+
+  /**
+   * Clears all fonts
+   */
+  clear(): void {
+    this.fonts.clear();
+  }
+
+  /**
+   * Removes a specific font
+   * @param path - Font path in archive
+   * @returns True if font was removed
+   */
+  removeFont(path: string): boolean {
+    return this.fonts.delete(path);
+  }
+
+  /**
+   * Gets font by path
+   * @param path - Font path in archive
+   * @returns Font entry or undefined
+   */
+  getFontByPath(path: string): FontEntry | undefined {
+    return this.fonts.get(path);
+  }
+
+  /**
+   * Gets font by family name
+   * @param fontFamily - Font family name
+   * @returns Font entry or undefined
+   */
+  getFontByFamily(fontFamily: string): FontEntry | undefined {
+    for (const entry of this.fonts.values()) {
+      if (entry.fontFamily === fontFamily) {
+        return entry;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Parses Content_Types.xml to detect font extensions
+   * @param contentTypesXml - Content_Types.xml content
+   * @returns Array of font extensions found
+   */
+  static parseFontExtensionsFromContentTypes(contentTypesXml: string): string[] {
+    const fontExtensions: string[] = [];
+    const fontMimeTypes = [
+      'application/x-font-ttf',
+      'application/x-font-opentype',
+      'application/font-woff',
+      'font/woff2',
+    ];
+
+    // Parse XML to find Default elements with font MIME types
+    const defaultPattern = /<Default\s+Extension="([^"]+)"\s+ContentType="([^"]+)"/g;
+    let match;
+
+    while ((match = defaultPattern.exec(contentTypesXml)) !== null) {
+      const extension = match[1];
+      const mimeType = match[2];
+
+      if (extension && mimeType && fontMimeTypes.includes(mimeType)) {
+        fontExtensions.push(extension);
+      }
+    }
+
+    return fontExtensions;
+  }
+
+  /**
+   * Detects font format from extension
+   * @param extension - File extension
+   * @returns FontFormat or undefined
+   */
+  static detectFormatFromExtension(extension: string): FontFormat | undefined {
+    const ext = extension.toLowerCase().replace('.', '');
+    if (ext === 'ttf' || ext === 'otf' || ext === 'woff' || ext === 'woff2') {
+      return ext as FontFormat;
+    }
+    return undefined;
+  }
+
+  /**
+   * Loads fonts from a ZIP archive
+   * Reads fonts from word/fonts/ directory and registers them
+   * @param zipFiles - Map of file paths to content (from ZipHandler)
+   * @param contentTypesXml - Content of [Content_Types].xml
+   */
+  loadFontsFromArchive(
+    zipFiles: Map<string, Buffer | string>,
+    contentTypesXml: string
+  ): void {
+    // First, detect which font formats are registered in Content_Types.xml
+    const registeredExtensions = FontManager.parseFontExtensionsFromContentTypes(contentTypesXml);
+
+    // Then, scan word/fonts/ directory for font files
+    for (const [path, content] of zipFiles.entries()) {
+      if (path.startsWith('word/fonts/') && content instanceof Buffer) {
+        const filename = path.split('/').pop() || '';
+        const extension = filename.split('.').pop()?.toLowerCase();
+
+        // Check if this extension is registered
+        if (extension && registeredExtensions.includes(extension)) {
+          const format = FontManager.detectFormatFromExtension(extension);
+
+          if (format) {
+            // Extract font family from filename (sanitize back)
+            const familyName = this.extractFontFamilyFromFilename(filename);
+
+            // Create font entry
+            const entry: FontEntry = {
+              filename,
+              format,
+              fontFamily: familyName,
+              data: content,
+              path,
+            };
+
+            this.fonts.set(path, entry);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Extracts font family name from filename
+   * @param filename - Font filename
+   * @returns Inferred font family name
+   */
+  private extractFontFamilyFromFilename(filename: string): string {
+    // Remove extension
+    const nameWithoutExt = filename.replace(/\.(ttf|otf|woff|woff2)$/i, '');
+
+    // Remove counter suffix (e.g., _1, _2)
+    const nameWithoutCounter = nameWithoutExt.replace(/_\d+$/, '');
+
+    // Replace underscores with spaces and title case
+    return nameWithoutCounter
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+}