/**
 * DOCX Module - Template Engine
 *
 * A template engine for DOCX documents supporting:
 * - Variable interpolation: {{name}}, {{user.name}}
 * - Conditionals: {{#if cond}}...{{/if}}, {{#if cond}}...{{else}}...{{/if}}
 * - Loops: {{#each items}}...{{/each}} with {{.}}, {{.prop}}, {{@index}}
 * - Table row loops: auto-duplicates table rows when {{#each}} is in a row
 * - Table column loops: {{#cols items}}...{{/cols}} duplicates columns
 * - Image placeholders: {{%image}} resolves to an inline image
 * - RichText placeholders: {{&richText}} resolves to paragraph children
 * - Sub-document insertion: {{>subDoc}} resolves to body content blocks
 * - Chart placeholders: {{^chart}} resolves to chart content
 *
 * Handles cross-run placeholders (Word often splits {{name}} across runs).
 */
import type { BaseErrorOptions } from "../../../utils/errors.js";
import { DocxError } from "../errors.js";
import type { DocxDocument, BodyContent, Run, ImageDef, Chart } from "../types.js";
/** Options for the template engine. */
export interface TemplateOptions {
    /** Custom delimiters (default: ["{{", "}}"]). */
    readonly delimiters?: readonly [string, string];
    /**
     * If true (default), throw `TemplateError` when a placeholder cannot be
     * resolved. If false, unresolved variables render as the empty string and
     * unresolved control directives are skipped silently.
     */
    readonly strict?: boolean;
}
/** An image value to be inserted by the template engine. */
export interface TemplateImage {
    /** Image definition (data, fileName, mediaType). */
    readonly image: ImageDef;
    /** Width in EMU. */
    readonly width: number;
    /** Height in EMU. */
    readonly height: number;
    /** Optional alt text. */
    readonly altText?: string;
}
/** Rich text value: an array of runs to insert. */
export type TemplateRichText = readonly Run[];
/** Sub-document content: body blocks to insert. */
export type TemplateSubDocument = readonly BodyContent[];
/** Chart value to be inserted by the template engine. */
export interface TemplateChart {
    readonly chart: Chart;
    readonly altText?: string;
    readonly name?: string;
}
/** HTML chunk value to be inserted as an altChunk body content. */
export interface TemplateHtmlChunk {
    /** HTML content string. */
    readonly html: string;
    /** Optional content type (default: "text/html"). */
    readonly contentType?: string;
}
/** Information about a template tag found in the document. */
export interface TemplateTag {
    /** The raw tag expression (e.g. "name", "#each items", "%image"). */
    readonly expression: string;
    /** Tag type. */
    readonly type: "variable" | "image" | "richText" | "subDocument" | "chart" | "htmlChunk" | "ifOpen" | "ifClose" | "else" | "eachOpen" | "eachClose" | "colsOpen" | "colsClose";
    /** Location hint (e.g. "body paragraph 3", "header"). */
    readonly location: string;
}
/** Error thrown when template processing fails. */
export declare class TemplateError extends DocxError {
    readonly name = "TemplateError";
    /** The placeholder that caused the error. */
    readonly placeholder: string;
    /** Location hint (e.g. "body paragraph 3", "header"). */
    readonly location: string;
    /** The tag name/expression that caused the error. */
    readonly tagName?: string;
    /** The paragraph index within the current block where the error occurred. */
    readonly paragraphIndex?: number;
    /** The section path (e.g. "body", "header:default", "footer:first"). */
    readonly sectionPath?: string;
    constructor(message: string, placeholder: string, location: string, options?: BaseErrorOptions & {
        tagName?: string;
        paragraphIndex?: number;
        sectionPath?: string;
    });
}
/**
 * Fill a DOCX template document with data.
 *
 * Processes all body content, headers, footers, footnotes, and endnotes.
 * Operates on the document model in-place and returns it.
 *
 * @param doc - The parsed DocxDocument model.
 * @param data - Data to fill into the template.
 * @param options - Optional template settings.
 * @returns The same DocxDocument with placeholders resolved.
 */
export declare function fillTemplate(doc: DocxDocument, data: Record<string, unknown>, options?: TemplateOptions): DocxDocument;
/**
 * List all template tags found in a document.
 *
 * Scans body, headers, footers, footnotes, and endnotes for template
 * placeholders. Useful for validating data objects against templates.
 *
 * @param doc - The parsed DocxDocument model.
 * @param options - Optional settings (custom delimiters).
 * @returns Array of all discovered template tags.
 */
export declare function listTemplateTags(doc: DocxDocument, options?: Pick<TemplateOptions, "delimiters">): TemplateTag[];
export declare function isTemplateChart(v: unknown): v is TemplateChart;
/**
 * Enhanced fillTemplate that supports image (%img), richText (&rt),
 * subDocument (>sub), and chart (^chart) placeholders in addition to the
 * standard variable, conditional, and loop directives.
 *
 * Image placeholder: {{%imagePath}} — value must be a TemplateImage object.
 * RichText placeholder: {{&richPath}} — value must be TemplateRichText (Run[]).
 * SubDocument placeholder: {{>subPath}} — value must be TemplateSubDocument (BodyContent[]).
 * Chart placeholder: {{^chartPath}} — value must be a TemplateChart object.
 */
export declare function fillTemplateEnhanced(doc: DocxDocument, data: Record<string, unknown>, options?: TemplateOptions): DocxDocument;