@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/security/policy.js

@@ -0,0 +1,102 @@
+/**
+ * DOCX Module - Security Policy
+ *
+ * Defines configurable security policies that control how potentially
+ * dangerous content (VBA, OLE, external targets, etc.) is handled
+ * during document reading and writing.
+ *
+ * **Implementation status of each field (read this before relying on
+ * the strict preset for security guarantees):**
+ *
+ * - `preserveVbaProject` — IMPLEMENTED on the read path. When `false`
+ *   the macro binary is dropped from the returned model.
+ * - `preserveAltChunks` — IMPLEMENTED on the read path. When `false`
+ *   altChunk body items are removed before the document is returned.
+ * - `allowExternalTargets` — IMPLEMENTED on the read path. When `false`
+ *   `Hyperlink.url` is left undefined; only anchor-based hyperlinks
+ *   survive. The link wrapper and its inner runs remain.
+ * - `maxPackageSize`, `maxPartSize`, `maxPartCount`, `maxXmlDepth` —
+ *   IMPLEMENTED. Enforced during ZIP parsing / XML parsing; oversize
+ *   inputs raise `DocxLimitExceededError` instead of being processed.
+ * - `dropSignaturesOnModify` — IMPLEMENTED. Both writers skip any opaque
+ *   parts under `_xmlsignatures/` when `true` (the default). The
+ *   `_rels/.rels` file is rebuilt from scratch by the packager, so any
+ *   sigOrigin relationship pointing at the now-absent signatures is also
+ *   removed automatically. Set `false` to keep the parts; in that case
+ *   downstream verifiers will treat the signatures as broken because the
+ *   document body has been re-emitted.
+ * - `preserveOleObjects` — IMPLEMENTED. On the read path, OLE embedding
+ *   binaries (word/embeddings/*.bin and similar) are excluded from
+ *   `opaqueParts` when `false`. On the write path (both buffered and
+ *   streaming) the same paths are skipped when emitting opaqueParts. The
+ *   relationships that referenced the binary remain in the owning part's
+ *   .rels — strip those manually if you need a fully clean document.
+ * - `rawXmlPolicy` — IMPLEMENTED on the write path. `"preserve"` (default)
+ *   writes opaque rawXml verbatim; `"strip"` skips the offending fragments
+ *   while keeping the surrounding element well-formed; `"reject"` throws
+ *   `DocxRawXmlPolicyError` so the caller can sanitise the model first.
+ *   Sites covered: opaqueRun, opaqueParagraphChild, opaqueDrawing,
+ *   drawingShape rawXml/_advancedFillXml/_advancedEffectsXml,
+ *   settings.mailMergeRawXml, theme.formatScheme.rawXml, theme.extLstXml,
+ *   webSettings.rawXml, numPicBullet.rawVmlXml.
+ *
+ * Pull requests welcome for the not-yet-enforced fields. Until they
+ * arrive, callers needing those guarantees should sanitise the input
+ * model themselves before serialisation.
+ */
+// =============================================================================
+// Default Policies
+// =============================================================================
+/** Default security policy: preserve everything, generous limits. */
+export const DEFAULT_SECURITY_POLICY = {
+    preserveVbaProject: true,
+    preserveOleObjects: true,
+    preserveAltChunks: true,
+    dropSignaturesOnModify: true,
+    maxPackageSize: 500 * 1024 * 1024,
+    maxPartSize: 100 * 1024 * 1024,
+    maxPartCount: 10000,
+    maxXmlDepth: 256,
+    rawXmlPolicy: "preserve",
+    allowExternalTargets: true
+};
+/** Strict security policy: strip dangerous content, tight limits. */
+export const STRICT_SECURITY_POLICY = {
+    preserveVbaProject: false,
+    preserveOleObjects: false,
+    preserveAltChunks: false,
+    dropSignaturesOnModify: true,
+    maxPackageSize: 100 * 1024 * 1024,
+    maxPartSize: 50 * 1024 * 1024,
+    maxPartCount: 1000,
+    maxXmlDepth: 128,
+    rawXmlPolicy: "strip",
+    allowExternalTargets: false
+};
+// =============================================================================
+// Policy Resolution
+// =============================================================================
+/**
+ * Merge a partial security policy with the defaults.
+ * Any unset fields fall back to DEFAULT_SECURITY_POLICY values.
+ *
+ * @param policy - Partial policy overrides (or undefined for full defaults).
+ * @returns A fully resolved security policy.
+ */
+export function resolveSecurityPolicy(policy) {
+    if (!policy) {
+        return DEFAULT_SECURITY_POLICY;
+    }
+    return {
+        preserveVbaProject: policy.preserveVbaProject ?? DEFAULT_SECURITY_POLICY.preserveVbaProject,
+        preserveOleObjects: policy.preserveOleObjects ?? DEFAULT_SECURITY_POLICY.preserveOleObjects,
+        preserveAltChunks: policy.preserveAltChunks ?? DEFAULT_SECURITY_POLICY.preserveAltChunks,
+        dropSignaturesOnModify: policy.dropSignaturesOnModify ?? DEFAULT_SECURITY_POLICY.dropSignaturesOnModify,
+        maxPackageSize: policy.maxPackageSize ?? DEFAULT_SECURITY_POLICY.maxPackageSize,
+        maxPartSize: policy.maxPartSize ?? DEFAULT_SECURITY_POLICY.maxPartSize,
+        maxPartCount: policy.maxPartCount ?? DEFAULT_SECURITY_POLICY.maxPartCount,
+        maxXmlDepth: policy.maxXmlDepth ?? DEFAULT_SECURITY_POLICY.maxXmlDepth,
+        rawXmlPolicy: policy.rawXmlPolicy ?? DEFAULT_SECURITY_POLICY.rawXmlPolicy,
+        allowExternalTargets: policy.allowExternalTargets ?? DEFAULT_SECURITY_POLICY.allowExternalTargets
+    };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * DOCX Module - Template Chart Data Binding
+ *
+ * Extends the template engine with chart data binding support.
+ * Allows replacing series data, categories, and titles in chart
+ * definitions within a DocxDocument.
+ *
+ * @stability experimental
+ */
+import type { DocxDocument } from "../types.js";
+/** Data for a single chart series to bind. */
+export interface ChartSeriesData {
+    /** Series name (legend label). */
+    readonly name: string;
+    /** Numeric data values. */
+    readonly values: number[];
+    /** Optional series color (6-digit hex RGB). */
+    readonly color?: string;
+}
+/** Binding specification mapping a chart reference to new data. */
+export interface ChartBinding {
+    /** Chart index (0-based) or chart name. */
+    readonly chartRef: number | string;
+    /** New series data. */
+    readonly series: ChartSeriesData[];
+    /** New category labels (X-axis). */
+    readonly categories?: string[];
+    /** Chart title override. */
+    readonly title?: string;
+}
+/** Aggregate template data for chart bindings. */
+export interface ChartTemplateData {
+    /** Array of chart bindings to apply. */
+    readonly charts: ChartBinding[];
+}
+/**
+ * Replace chart data in a DocxDocument according to the provided bindings.
+ *
+ * Iterates through the document body, locates `ChartContent` blocks, and
+ * replaces their series data, categories, and titles with the values
+ * specified in each binding.
+ *
+ * Charts are matched by either:
+ * - Numeric index (0-based position among all ChartContent blocks in body)
+ * - String name (matched against `ChartContent.name`)
+ *
+ * Only basic chart types (bar, column, line, pie and their variants) are
+ * supported. Bindings that reference unsupported chart types are skipped.
+ *
+ * @param doc - The DocxDocument to modify.
+ * @param chartBindings - Array of chart bindings to apply.
+ * @returns A new DocxDocument with chart data replaced.
+ *
+ * @stability experimental
+ */
+export declare function bindChartData(doc: DocxDocument, chartBindings: ChartBinding[]): DocxDocument;

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

@@ -0,0 +1,167 @@
+/**
+ * DOCX Module - Template Chart Data Binding
+ *
+ * Extends the template engine with chart data binding support.
+ * Allows replacing series data, categories, and titles in chart
+ * definitions within a DocxDocument.
+ *
+ * @stability experimental
+ */
+import { DocxError } from "../errors.js";
+// =============================================================================
+// Supported chart type set (for validation)
+// =============================================================================
+const BASIC_CHART_TYPES = new Set([
+    "bar",
+    "barStacked",
+    "barPercentStacked",
+    "column",
+    "columnStacked",
+    "columnPercentStacked",
+    "line",
+    "lineStacked",
+    "lineMarked",
+    "pie",
+    "pie3D",
+    "doughnut"
+]);
+// =============================================================================
+// Core: bindChartData
+// =============================================================================
+/**
+ * Replace chart data in a DocxDocument according to the provided bindings.
+ *
+ * Iterates through the document body, locates `ChartContent` blocks, and
+ * replaces their series data, categories, and titles with the values
+ * specified in each binding.
+ *
+ * Charts are matched by either:
+ * - Numeric index (0-based position among all ChartContent blocks in body)
+ * - String name (matched against `ChartContent.name`)
+ *
+ * Only basic chart types (bar, column, line, pie and their variants) are
+ * supported. Bindings that reference unsupported chart types are skipped.
+ *
+ * @param doc - The DocxDocument to modify.
+ * @param chartBindings - Array of chart bindings to apply.
+ * @returns A new DocxDocument with chart data replaced.
+ *
+ * @stability experimental
+ */
+export function bindChartData(doc, chartBindings) {
+    if (chartBindings.length === 0) {
+        return doc;
+    }
+    // Validate bindings: series values length must match categories length when both provided
+    for (const binding of chartBindings) {
+        if (binding.categories && binding.categories.length > 0) {
+            for (const series of binding.series) {
+                if (series.values.length !== binding.categories.length) {
+                    throw new DocxError(`Chart binding "${String(binding.chartRef)}": series "${series.name}" has ${series.values.length} values but ${binding.categories.length} categories were provided. Lengths must match.`);
+                }
+            }
+        }
+    }
+    // Build a map of chart index -> binding and name -> binding for fast lookup
+    const indexBindings = new Map();
+    const nameBindings = new Map();
+    for (const binding of chartBindings) {
+        if (typeof binding.chartRef === "number") {
+            indexBindings.set(binding.chartRef, binding);
+        }
+        else {
+            nameBindings.set(binding.chartRef, binding);
+        }
+    }
+    // Walk through body content, track chart index, and apply bindings
+    let chartIndex = 0;
+    const newBody = [];
+    for (const block of doc.body) {
+        if (block.type === "chart") {
+            const chartContent = block;
+            const binding = resolveBinding(chartContent, chartIndex, indexBindings, nameBindings);
+            if (binding && isSupportedChartType(chartContent.chart.type)) {
+                newBody.push(applyBinding(chartContent, binding));
+            }
+            else {
+                newBody.push(block);
+            }
+            chartIndex++;
+        }
+        else {
+            newBody.push(block);
+        }
+    }
+    return { ...doc, body: newBody };
+}
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+/**
+ * Resolve which binding (if any) applies to a given chart content block.
+ */
+function resolveBinding(chartContent, index, indexBindings, nameBindings) {
+    // Index-based binding takes priority
+    const byIndex = indexBindings.get(index);
+    if (byIndex) {
+        return byIndex;
+    }
+    // Try name-based binding
+    if (chartContent.name) {
+        const byName = nameBindings.get(chartContent.name);
+        if (byName) {
+            return byName;
+        }
+    }
+    return undefined;
+}
+/**
+ * Check whether the chart type is in the supported set.
+ */
+function isSupportedChartType(chartType) {
+    return BASIC_CHART_TYPES.has(chartType);
+}
+/**
+ * Apply a binding to a ChartContent block, producing a new ChartContent
+ * with updated series, categories, and title.
+ */
+function applyBinding(chartContent, binding) {
+    const originalChart = chartContent.chart;
+    const categories = binding.categories ?? extractOriginalCategories(originalChart);
+    const newSeries = [];
+    for (const seriesData of binding.series) {
+        newSeries.push(buildChartSeries(seriesData, categories));
+    }
+    const newChart = {
+        ...originalChart,
+        series: newSeries,
+        title: binding.title !== undefined ? binding.title : originalChart.title
+    };
+    return {
+        ...chartContent,
+        chart: newChart
+    };
+}
+/**
+ * Extract categories from the original chart's first series (fallback).
+ */
+function extractOriginalCategories(chart) {
+    if (chart.series.length > 0) {
+        return [...chart.series[0].categories];
+    }
+    return [];
+}
+/**
+ * Build a ChartSeries from binding data and resolved categories.
+ */
+function buildChartSeries(data, categories) {
+    const series = {
+        name: data.name,
+        categories: categories,
+        values: data.values
+    };
+    if (data.color) {
+        return { ...series, color: data.color };
+    }
+    return series;
+}

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

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