/**
 * DOCX Module - Template Data Source
 *
 * An abstraction layer for providing data to the template engine from
 * various sources (JSON, XML, CSV) with composition support.
 *
 * @stability experimental
 */
import type { DocxDocument } from "../types.js";
import type { TemplateOptions } from "./template-engine.js";
/**
 * Abstract data provider for the template engine.
 *
 * Implementations transform various data formats into the flat
 * `Record<string, unknown>` structure consumed by `fillTemplate`.
 */
export interface DataSource {
    /** Retrieve all data as a flat record. */
    readonly getData: () => Record<string, unknown>;
    /** Retrieve an array value by key. Returns empty array if not found or not an array. */
    readonly getArray: (key: string) => unknown[];
    /** Retrieve a single value by dot-separated path. Returns undefined if not found. */
    readonly getValue: (path: string) => unknown;
}
/** Options for `fillTemplateFromSource`. */
export interface FillFromSourceOptions extends TemplateOptions {
    /** If true, merge arrays with the same key across composite sources (default: false). */
    readonly mergeArrays?: boolean;
}
/**
 * Data source that reads from a JSON string or object.
 *
 * @stability experimental
 */
export declare class JsonDataSource implements DataSource {
    private readonly data;
    /**
     * @param input - A JSON string or an existing object.
     */
    constructor(input: string | Record<string, unknown>);
    getData(): Record<string, unknown>;
    getArray(key: string): unknown[];
    getValue(path: string): unknown;
    private resolvePath;
}
/**
 * Data source that reads from an XML string.
 *
 * Flattens the XML structure into dot-separated key-value pairs.
 * Repeated elements with the same tag are collected into arrays.
 *
 * Example XML:
 * ```xml
 * <root>
 *   <name>John</name>
 *   <address><city>NY</city></address>
 *   <item>A</item>
 *   <item>B</item>
 * </root>
 * ```
 * Produces: `{ name: "John", "address.city": "NY", address: { city: "NY" }, item: ["A", "B"] }`
 *
 * @stability experimental
 */
export declare class XmlDataSource implements DataSource {
    private readonly data;
    /**
     * @param xml - An XML string to parse.
     * @param rootTag - Optional root element name to skip. If not provided, the first element is used.
     */
    constructor(xml: string, rootTag?: string);
    getData(): Record<string, unknown>;
    getArray(key: string): unknown[];
    getValue(path: string): unknown;
    private resolvePath;
}
/**
 * Data source that reads from a CSV string.
 *
 * The first row is treated as headers (column names become keys).
 * Each subsequent row becomes an object. The entire dataset is available
 * as an array under the `rows` key (or a custom key).
 *
 * Individual columns are also available as arrays under their header name.
 *
 * Example CSV:
 * ```
 * name,age
 * Alice,30
 * Bob,25
 * ```
 * Produces:
 * ```
 * {
 *   rows: [{ name: "Alice", age: "30" }, { name: "Bob", age: "25" }],
 *   name: ["Alice", "Bob"],
 *   age: ["30", "25"]
 * }
 * ```
 *
 * @stability experimental
 */
export declare class CsvDataSource implements DataSource {
    private readonly data;
    /**
     * @param csv - A CSV string.
     * @param options - Optional parsing configuration.
     */
    constructor(csv: string, options?: {
        /** Delimiter character (default: ","). */
        readonly delimiter?: string;
        /** Key for the rows array (default: "rows"). */
        readonly rowsKey?: string;
    });
    getData(): Record<string, unknown>;
    getArray(key: string): unknown[];
    getValue(path: string): unknown;
}
/**
 * Combines multiple data sources into one.
 *
 * Sources added later take precedence over earlier ones for conflicting keys.
 * Arrays can optionally be merged instead of overwritten.
 *
 * @stability experimental
 */
export declare class CompositeDataSource implements DataSource {
    private readonly sources;
    private readonly mergeArrays;
    /**
     * @param sources - Data sources to combine (later sources take precedence).
     * @param options - Configuration options.
     */
    constructor(sources: readonly DataSource[], options?: {
        readonly mergeArrays?: boolean;
    });
    getData(): Record<string, unknown>;
    getArray(key: string): unknown[];
    getValue(path: string): unknown;
}
/**
 * Fill a DOCX template using a DataSource instead of a raw data record.
 *
 * This is a convenience function that extracts data from the source and
 * delegates to the core `fillTemplate` function.
 *
 * @param doc - The parsed DocxDocument model.
 * @param source - A DataSource implementation.
 * @param options - Optional template settings.
 * @returns The same DocxDocument with placeholders resolved.
 *
 * @stability experimental
 */
export declare function fillTemplateFromSource(doc: DocxDocument, source: DataSource, options?: FillFromSourceOptions): DocxDocument;