@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/template/template-datasource.js

@@ -0,0 +1,541 @@
+/**
+ * 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 { parseXml } from "../../xml/dom.js";
+import { DocxError } from "../errors.js";
+import { fillTemplate } from "./template-engine.js";
+// =============================================================================
+// JsonDataSource
+// =============================================================================
+/**
+ * Data source that reads from a JSON string or object.
+ *
+ * @stability experimental
+ */
+export class JsonDataSource {
+    /**
+     * @param input - A JSON string or an existing object.
+     */
+    constructor(input) {
+        if (typeof input === "string") {
+            let parsed;
+            try {
+                parsed = JSON.parse(input);
+            }
+            catch (cause) {
+                throw new DocxError(`JsonDataSource: failed to parse input as JSON (${cause.message})`, { cause });
+            }
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new DocxError("JsonDataSource: input must parse to a JSON object (not array or null)");
+            }
+            this.data = parsed;
+        }
+        else {
+            this.data = input;
+        }
+    }
+    getData() {
+        return this.data;
+    }
+    getArray(key) {
+        const value = this.resolvePath(key);
+        if (Array.isArray(value)) {
+            return value;
+        }
+        return [];
+    }
+    getValue(path) {
+        return this.resolvePath(path);
+    }
+    resolvePath(path) {
+        const parts = path.split(".");
+        let current = this.data;
+        for (const part of parts) {
+            if (current === null || current === undefined || typeof current !== "object") {
+                return undefined;
+            }
+            current = current[part];
+        }
+        return current;
+    }
+}
+// =============================================================================
+// XmlDataSource
+// =============================================================================
+/**
+ * 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 class XmlDataSource {
+    /**
+     * @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, rootTag) {
+        this.data = parseXmlToRecord(xml, rootTag);
+    }
+    getData() {
+        return this.data;
+    }
+    getArray(key) {
+        const value = this.resolvePath(key);
+        if (Array.isArray(value)) {
+            return value;
+        }
+        return [];
+    }
+    getValue(path) {
+        return this.resolvePath(path);
+    }
+    resolvePath(path) {
+        const parts = path.split(".");
+        let current = this.data;
+        for (const part of parts) {
+            if (current === null || current === undefined || typeof current !== "object") {
+                return undefined;
+            }
+            current = current[part];
+        }
+        return current;
+    }
+}
+// =============================================================================
+// CsvDataSource
+// =============================================================================
+/**
+ * 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 class CsvDataSource {
+    /**
+     * @param csv - A CSV string.
+     * @param options - Optional parsing configuration.
+     */
+    constructor(csv, options) {
+        const delimiter = options?.delimiter ?? ",";
+        const rowsKey = options?.rowsKey ?? "rows";
+        this.data = parseCsvToRecord(csv, delimiter, rowsKey);
+    }
+    getData() {
+        return this.data;
+    }
+    getArray(key) {
+        const value = this.data[key];
+        if (Array.isArray(value)) {
+            return value;
+        }
+        return [];
+    }
+    getValue(path) {
+        const parts = path.split(".");
+        let current = this.data;
+        for (const part of parts) {
+            if (current === null || current === undefined || typeof current !== "object") {
+                return undefined;
+            }
+            current = current[part];
+        }
+        return current;
+    }
+}
+// =============================================================================
+// CompositeDataSource
+// =============================================================================
+/**
+ * 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 class CompositeDataSource {
+    /**
+     * @param sources - Data sources to combine (later sources take precedence).
+     * @param options - Configuration options.
+     */
+    constructor(sources, options) {
+        this.sources = sources;
+        this.mergeArrays = options?.mergeArrays ?? false;
+    }
+    getData() {
+        const result = {};
+        for (const source of this.sources) {
+            const data = source.getData();
+            for (const key of Object.keys(data)) {
+                if (this.mergeArrays && Array.isArray(result[key]) && Array.isArray(data[key])) {
+                    result[key] = [...result[key], ...data[key]];
+                }
+                else {
+                    result[key] = data[key];
+                }
+            }
+        }
+        return result;
+    }
+    getArray(key) {
+        if (this.mergeArrays) {
+            const merged = [];
+            for (const source of this.sources) {
+                const arr = source.getArray(key);
+                merged.push(...arr);
+            }
+            return merged;
+        }
+        // Last source with a non-empty array wins
+        for (let i = this.sources.length - 1; i >= 0; i--) {
+            const arr = this.sources[i].getArray(key);
+            if (arr.length > 0) {
+                return arr;
+            }
+        }
+        return [];
+    }
+    getValue(path) {
+        // Last source with a defined value wins
+        for (let i = this.sources.length - 1; i >= 0; i--) {
+            const value = this.sources[i].getValue(path);
+            if (value !== undefined) {
+                return value;
+            }
+        }
+        return undefined;
+    }
+}
+// =============================================================================
+// fillTemplateFromSource
+// =============================================================================
+/**
+ * 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 function fillTemplateFromSource(doc, source, options) {
+    const data = source.getData();
+    return fillTemplate(doc, data, options);
+}
+/**
+ * Parse an XML string into a flat Record using the project's hardened
+ * SAX-backed DOM parser. The parser enforces the standard `maxDepth` and
+ * `maxEntityExpansions` limits, so this helper is safe to call on
+ * untrusted input — earlier versions used a hand-rolled regex parser
+ * with no depth limit and no protection against billion-laughs / nested
+ * element bombs.
+ */
+function parseXmlToRecord(xml, rootTag) {
+    let parsed;
+    try {
+        parsed = parseXml(xml);
+    }
+    catch {
+        return {};
+    }
+    const root = parsed.root;
+    if (!root) {
+        return {};
+    }
+    // The previous regex parser ignored rootTag too; we keep that behaviour
+    // for compatibility — converting from `root` directly works regardless
+    // of whether the caller named the expected root.
+    void rootTag;
+    return xmlElementToRecord(root);
+}
+/** Adapter from XmlElement (DOM) to the legacy XmlNode shape. */
+function elementToXmlNode(el) {
+    const children = [];
+    let text = "";
+    for (const child of el.children) {
+        if (child.type === "element") {
+            children.push(elementToXmlNode(child));
+        }
+        else if (child.type === "text" || child.type === "cdata") {
+            text += child.value;
+        }
+    }
+    return {
+        tag: el.local ?? el.name.replace(/^.*:/, ""),
+        attributes: { ...el.attributes },
+        children,
+        text
+    };
+}
+function xmlElementToRecord(el) {
+    return xmlNodeToRecord(elementToXmlNode(el));
+}
+/** Stub for the legacy entrypoint kept for tests / external callers. */
+function parseXmlElement(xml) {
+    try {
+        return elementToXmlNode(parseXml(xml).root);
+    }
+    catch {
+        return null;
+    }
+}
+// Suppress no-unused-vars lint — kept for binary compat with prior internal API.
+void parseXmlElement;
+/** Convert an XmlNode tree into a flat Record. */
+function xmlNodeToRecord(node) {
+    const result = {};
+    // Add attributes with @ prefix
+    for (const key of Object.keys(node.attributes)) {
+        result[`@${key}`] = node.attributes[key];
+    }
+    // Group children by tag name
+    const childGroups = new Map();
+    for (const child of node.children) {
+        const existing = childGroups.get(child.tag);
+        if (existing) {
+            existing.push(child);
+        }
+        else {
+            childGroups.set(child.tag, [child]);
+        }
+    }
+    // Convert child groups
+    for (const [tag, group] of childGroups) {
+        if (group.length === 1) {
+            const child = group[0];
+            if (child.children.length === 0) {
+                // Leaf node — use text value
+                result[tag] = child.text || "";
+            }
+            else {
+                // Nested object
+                result[tag] = xmlNodeToRecord(child);
+            }
+        }
+        else {
+            // Multiple elements with same tag — array
+            result[tag] = group.map(child => {
+                if (child.children.length === 0) {
+                    return child.text || "";
+                }
+                return xmlNodeToRecord(child);
+            });
+        }
+    }
+    // If node has text and no children, include it
+    if (node.children.length === 0 && node.text) {
+        result["#text"] = node.text;
+    }
+    return result;
+}
+// =============================================================================
+// Internal: CSV Parser (minimal, zero-dependency)
+// =============================================================================
+/**
+ * Parse a CSV string into a Record with column arrays and a rows array.
+ * Handles quoted fields (RFC 4180 style).
+ */
+function parseCsvToRecord(csv, delimiter, rowsKey) {
+    const lines = parseCsvLines(csv, delimiter);
+    if (lines.length === 0) {
+        return { [rowsKey]: [] };
+    }
+    const headers = lines[0];
+    const rows = [];
+    const columns = {};
+    // Initialize column arrays
+    for (const header of headers) {
+        columns[header] = [];
+    }
+    // Parse data rows
+    for (let i = 1; i < lines.length; i++) {
+        const fields = lines[i];
+        const row = {};
+        for (let j = 0; j < headers.length; j++) {
+            const value = j < fields.length ? fields[j] : "";
+            row[headers[j]] = value;
+            columns[headers[j]].push(value);
+        }
+        rows.push(row);
+    }
+    const result = { [rowsKey]: rows };
+    for (const header of headers) {
+        result[header] = columns[header];
+    }
+    return result;
+}
+/**
+ * Parse CSV text into an array of rows, where each row is an array of fields.
+ * Supports quoted fields with embedded delimiters, newlines, and escaped quotes.
+ */
+function parseCsvLines(csv, delimiter) {
+    const rows = [];
+    const len = csv.length;
+    let pos = 0;
+    while (pos < len) {
+        const { fields, nextPos } = parseCsvRow(csv, pos, delimiter);
+        // Skip completely empty trailing lines
+        if (nextPos >= len && fields.length === 1 && fields[0] === "") {
+            break;
+        }
+        rows.push(fields);
+        pos = nextPos;
+    }
+    return rows;
+}
+/**
+ * Parse a single CSV row starting at the given position.
+ * Returns the parsed fields and the position after the row terminator.
+ */
+function parseCsvRow(csv, startPos, delimiter) {
+    const fields = [];
+    const len = csv.length;
+    let pos = startPos;
+    while (pos <= len) {
+        if (pos === len) {
+            // End of input — add empty field only if we just saw a delimiter
+            if (fields.length > 0 && pos > startPos && csv[pos - 1] === delimiter) {
+                fields.push("");
+            }
+            else if (fields.length === 0) {
+                fields.push("");
+            }
+            break;
+        }
+        const char = csv[pos];
+        // Check for line terminator at start of field (empty row remainder)
+        if (char === "\r" || char === "\n") {
+            if (fields.length === 0) {
+                // Empty line
+                fields.push("");
+            }
+            // Skip line terminator
+            if (char === "\r" && pos + 1 < len && csv[pos + 1] === "\n") {
+                pos += 2;
+            }
+            else {
+                pos += 1;
+            }
+            return { fields, nextPos: pos };
+        }
+        if (char === '"') {
+            // Quoted field
+            const { value, nextPos: fieldEnd } = parseQuotedField(csv, pos);
+            fields.push(value);
+            pos = fieldEnd;
+            // After quoted field, expect delimiter or line end
+            if (pos < len && csv[pos] === delimiter) {
+                pos++; // skip delimiter
+            }
+            else if (pos < len && (csv[pos] === "\r" || csv[pos] === "\n")) {
+                if (csv[pos] === "\r" && pos + 1 < len && csv[pos + 1] === "\n") {
+                    pos += 2;
+                }
+                else {
+                    pos += 1;
+                }
+                return { fields, nextPos: pos };
+            }
+        }
+        else {
+            // Unquoted field
+            let fieldEnd = pos;
+            while (fieldEnd < len &&
+                csv[fieldEnd] !== delimiter &&
+                csv[fieldEnd] !== "\r" &&
+                csv[fieldEnd] !== "\n") {
+                fieldEnd++;
+            }
+            fields.push(csv.slice(pos, fieldEnd));
+            pos = fieldEnd;
+            if (pos < len && csv[pos] === delimiter) {
+                pos++; // skip delimiter
+                // If delimiter is at end of input, add empty trailing field
+                if (pos >= len) {
+                    fields.push("");
+                }
+            }
+            else if (pos < len && (csv[pos] === "\r" || csv[pos] === "\n")) {
+                if (csv[pos] === "\r" && pos + 1 < len && csv[pos + 1] === "\n") {
+                    pos += 2;
+                }
+                else {
+                    pos += 1;
+                }
+                return { fields, nextPos: pos };
+            }
+        }
+    }
+    return { fields, nextPos: pos };
+}
+/**
+ * Parse a quoted CSV field starting at the given position (which must be a `"`).
+ * Handles escaped quotes (`""`) inside the field.
+ */
+function parseQuotedField(csv, startPos) {
+    const len = csv.length;
+    let pos = startPos + 1; // skip opening quote
+    let value = "";
+    while (pos < len) {
+        if (csv[pos] === '"') {
+            if (pos + 1 < len && csv[pos + 1] === '"') {
+                // Escaped quote
+                value += '"';
+                pos += 2;
+            }
+            else {
+                // End of quoted field
+                pos++; // skip closing quote
+                return { value, nextPos: pos };
+            }
+        }
+        else {
+            value += csv[pos];
+            pos++;
+        }
+    }
+    // Unterminated quote — return what we have
+    return { value, nextPos: pos };
+}

package/dist/browser/modules/word/template/template-engine.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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;