@betteroffice/docx 0.0.1

package/dist/colorResolver-n0o7H7ep.d.mts

@@ -0,0 +1,290 @@
+import { Document } from './types/document.mjs';
+import { C as ColorValue, a as Theme, z as ThemeColorSlot } from './formatting-DoL7KBSL.mjs';
+
+/**
+ * Template Processing Utility
+ *
+ * Uses docxtemplater to substitute template variables in DOCX documents:
+ * - Processes {variable_name} patterns (docxtemplater default syntax)
+ * - Preserves all formatting (fonts, styles, colors, tables)
+ * - Error handling with useful messages
+ */
+/**
+ * Options for template processing
+ */
+interface ProcessTemplateOptions {
+    /** How to handle undefined variables */
+    nullGetter?: 'keep' | 'empty' | 'error';
+    /** Custom parser for variable names */
+    parser?: (tag: string) => {
+        get: (scope: Record<string, unknown>) => unknown;
+    };
+    /** Line breaks: keep raw \n or convert to w:br */
+    linebreaks?: boolean;
+    /** Delimiter settings */
+    delimiters?: {
+        start?: string;
+        end?: string;
+    };
+}
+/**
+ * Result of template processing
+ */
+interface ProcessTemplateResult {
+    /** The processed document buffer */
+    buffer: ArrayBuffer;
+    /** Variables that were found and replaced */
+    replacedVariables: string[];
+    /** Variables that were not replaced (no value provided) */
+    unreplacedVariables: string[];
+    /** Any warnings during processing */
+    warnings: string[];
+}
+/**
+ * Error details from template processing
+ */
+interface TemplateError {
+    /** Error message */
+    message: string;
+    /** Variable name that caused the error (if applicable) */
+    variable?: string;
+    /** Error type */
+    type: 'parse' | 'render' | 'undefined' | 'unknown';
+    /** Original error */
+    originalError?: Error;
+}
+/**
+ * Process a DOCX template with variable substitution
+ *
+ * @param buffer - The DOCX file as ArrayBuffer
+ * @param variables - Map of variable names to values
+ * @param options - Processing options
+ * @returns Processed DOCX as ArrayBuffer
+ */
+declare function processTemplate(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): ArrayBuffer;
+/**
+ * Process template with detailed result
+ *
+ * @param buffer - The DOCX file as ArrayBuffer
+ * @param variables - Map of variable names to values
+ * @param options - Processing options
+ * @returns Detailed processing result
+ */
+declare function processTemplateDetailed(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): ProcessTemplateResult;
+/**
+ * Process template and return as Blob
+ *
+ * @param buffer - The DOCX file as ArrayBuffer
+ * @param variables - Map of variable names to values
+ * @param options - Processing options
+ * @returns Processed DOCX as Blob
+ */
+declare function processTemplateAsBlob(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): Blob;
+/**
+ * Process template and trigger download
+ *
+ * @param buffer - The DOCX file as ArrayBuffer
+ * @param variables - Map of variable names to values
+ * @param filename - Output filename (without extension)
+ * @param options - Processing options
+ */
+declare function processTemplateAndDownload(buffer: ArrayBuffer, variables: Record<string, string>, filename?: string, options?: ProcessTemplateOptions): void;
+/**
+ * Get all template tags in a document without processing
+ *
+ * @param buffer - The DOCX file as ArrayBuffer
+ * @returns List of tag names found
+ */
+declare function getTemplateTags(buffer: ArrayBuffer): string[];
+/**
+ * Validate that a document is a valid docxtemplater template
+ *
+ * @param buffer - The DOCX file as ArrayBuffer
+ * @returns Validation result
+ */
+declare function validateTemplate(buffer: ArrayBuffer): {
+    valid: boolean;
+    errors: TemplateError[];
+    tags: string[];
+};
+/**
+ * Check if all required variables have values
+ *
+ * @param tags - List of template tags
+ * @param variables - Provided variable values
+ * @returns Missing variable names
+ */
+declare function getMissingVariables(tags: string[], variables: Record<string, string>): string[];
+/**
+ * Preview what the document will look like after processing
+ * Returns the document text with variables replaced (for preview purposes)
+ *
+ * @param buffer - The DOCX file as ArrayBuffer
+ * @param variables - Map of variable names to values
+ * @returns Preview text
+ */
+declare function previewTemplate(buffer: ArrayBuffer, variables: Record<string, string>): string;
+/**
+ * Process template with conditional sections
+ * Supports #if, #unless, #each loops
+ *
+ * @param buffer - The DOCX file as ArrayBuffer
+ * @param data - Full data object (can include arrays, nested objects)
+ * @param options - Processing options
+ * @returns Processed DOCX as ArrayBuffer
+ */
+declare function processTemplateAdvanced(buffer: ArrayBuffer, data: Record<string, unknown>, options?: ProcessTemplateOptions): ArrayBuffer;
+/**
+ * Create a template processor with preset options
+ */
+declare function createTemplateProcessor(defaultOptions?: ProcessTemplateOptions): (buffer: ArrayBuffer, variables: Record<string, string>) => ArrayBuffer;
+
+/**
+ * Create Document Utility
+ *
+ * Provides functions to create new documents programmatically.
+ */
+
+/**
+ * Options for creating an empty document
+ */
+interface CreateEmptyDocumentOptions {
+    /** Page width in twips (default: 12240 = 8.5 inches) */
+    pageWidth?: number;
+    /** Page height in twips (default: 15840 = 11 inches) */
+    pageHeight?: number;
+    /** Page orientation (default: 'portrait') */
+    orientation?: 'portrait' | 'landscape';
+    /** Top margin in twips (default: 1440 = 1 inch) */
+    marginTop?: number;
+    /** Bottom margin in twips (default: 1440 = 1 inch) */
+    marginBottom?: number;
+    /** Left margin in twips (default: 1440 = 1 inch) */
+    marginLeft?: number;
+    /** Right margin in twips (default: 1440 = 1 inch) */
+    marginRight?: number;
+    /** Initial text content (default: empty string) */
+    initialText?: string;
+}
+/**
+ * Create an empty document with a single paragraph
+ *
+ * @param options - Optional configuration for the document
+ * @returns A new empty Document object
+ *
+ * @example
+ * ```ts
+ * // Create a blank document
+ * const doc = createEmptyDocument();
+ *
+ * // Create with custom margins
+ * const doc = createEmptyDocument({
+ *   marginTop: 720,  // 0.5 inch
+ *   marginBottom: 720,
+ * });
+ *
+ * // Create with initial text
+ * const doc = createEmptyDocument({
+ *   initialText: 'Hello, World!'
+ * });
+ * ```
+ */
+declare function createEmptyDocument(options?: CreateEmptyDocumentOptions): Document;
+/**
+ * Create a document with a single paragraph containing the given text
+ *
+ * @param text - The text content for the document
+ * @param options - Optional configuration for the document
+ * @returns A new Document object with the specified text
+ */
+declare function createDocumentWithText(text: string, options?: Omit<CreateEmptyDocumentOptions, 'initialText'>): Document;
+
+/**
+ * Color Resolver - Convert OOXML colors to CSS
+ *
+ * The generic color machinery (theme slots, tint/shade math, blending, the
+ * picker matrix) is re-exported here. This module keeps the WordprocessingML-
+ * specific pieces: w:highlight named colors, w:shd shading semantics, and
+ * ColorValue construction helpers.
+ *
+ * OOXML Color References:
+ * - w:color/@w:val - RGB hex or "auto"
+ * - w:color/@w:themeColor - Theme color slot
+ * - w:color/@w:themeTint - Tint modifier (0-255, hex)
+ * - w:color/@w:themeShade - Shade modifier (0-255, hex)
+ */
+
+/**
+ * Resolve a highlight color name to CSS
+ *
+ * @param highlight - Highlight color name (e.g., "yellow", "cyan")
+ * @returns CSS color string or empty string for "none"
+ */
+declare function resolveHighlightColor(highlight: string | undefined): string;
+/**
+ * Resolve a shading fill or pattern color to CSS
+ *
+ * @param color - ColorValue for fill
+ * @param theme - Theme for resolving theme colors
+ * @returns CSS color string
+ */
+declare function resolveShadingColor(color: ColorValue | undefined | null, theme: Theme | null | undefined): string;
+/**
+ * Check if a color is effectively black
+ *
+ * @param color - ColorValue object
+ * @param theme - Theme for resolving theme colors
+ * @returns True if color resolves to black or very dark
+ */
+declare function isBlack(color: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;
+/**
+ * Check if a color is effectively white
+ *
+ * @param color - ColorValue object
+ * @param theme - Theme for resolving theme colors
+ * @returns True if color resolves to white or very light
+ */
+declare function isWhite(color: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;
+/**
+ * Parse a color string (various formats) to ColorValue
+ *
+ * @param colorString - Color string like "FF0000", "auto", or theme color name
+ * @returns ColorValue object
+ */
+declare function parseColorString(colorString: string | undefined): ColorValue | undefined;
+/**
+ * Create a ColorValue from theme color reference
+ *
+ * @param themeColor - Theme color slot name
+ * @param tint - Optional tint modifier
+ * @param shade - Optional shade modifier
+ * @returns ColorValue object
+ */
+declare function createThemeColor(themeColor: ThemeColorSlot, tint?: number, shade?: number): ColorValue;
+/**
+ * Create a ColorValue from RGB hex
+ *
+ * @param hex - 6-character hex color (no #)
+ * @returns ColorValue object
+ */
+declare function createRgbColor(hex: string): ColorValue;
+/**
+ * Ensure a hex color string has a '#' prefix.
+ */
+declare function ensureHexPrefix(hex: string): string;
+/**
+ * Resolve a highlight color value to a CSS-ready string.
+ * Tries OOXML named highlight first, then ensures hex prefix.
+ */
+declare function resolveHighlightToCss(value: string): string;
+/**
+ * Check if two colors are equal
+ *
+ * @param color1 - First color
+ * @param color2 - Second color
+ * @param theme - Theme for resolving
+ * @returns True if colors resolve to the same value
+ */
+declare function colorsEqual(color1: ColorValue | undefined | null, color2: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;
+
+export { type CreateEmptyDocumentOptions as C, type ProcessTemplateOptions as P, type TemplateError as T, type ProcessTemplateResult as a, createDocumentWithText as b, colorsEqual as c, createEmptyDocument as d, createRgbColor as e, createTemplateProcessor as f, createThemeColor as g, getMissingVariables as h, getTemplateTags as i, isBlack as j, isWhite as k, previewTemplate as l, processTemplate as m, processTemplateAdvanced as n, processTemplateAsBlob as o, parseColorString as p, processTemplateDetailed as q, resolveHighlightColor as r, resolveShadingColor as s, ensureHexPrefix as t, resolveHighlightToCss as u, validateTemplate as v, processTemplateAndDownload as w };