@cj-tech-master/excelts 3.1.0 → 4.0.0-canary.20260103013222.0e5d37f

package/dist/browser/modules/excel/defined-names.js

@@ -0,0 +1,214 @@
+import { colCache } from "./utils/col-cache.js";
+import { CellMatrix } from "./utils/cell-matrix.js";
+import { Range } from "./range.js";
+const rangeRegexp = /[$](\w+)[$](\d+)(:[$](\w+)[$](\d+))?/;
+class DefinedNames {
+    constructor() {
+        this.matrixMap = {};
+    }
+    getMatrix(name) {
+        const matrix = this.matrixMap[name] || (this.matrixMap[name] = new CellMatrix());
+        return matrix;
+    }
+    // add a name to a cell. locStr in the form SheetName!$col$row or SheetName!$c1$r1:$c2:$r2
+    add(locStr, name) {
+        const location = colCache.decodeEx(locStr);
+        if ("error" in location) {
+            return; // Invalid reference, skip
+        }
+        this.addEx(location, name);
+    }
+    addEx(location, name) {
+        const matrix = this.getMatrix(name);
+        if ("top" in location) {
+            // It's a range (DecodedRange has top/left/bottom/right from Location)
+            for (let col = location.left; col <= location.right; col++) {
+                for (let row = location.top; row <= location.bottom; row++) {
+                    const address = {
+                        sheetName: location.sheetName,
+                        address: colCache.n2l(col) + row,
+                        row,
+                        col
+                    };
+                    matrix.addCellEx(address);
+                }
+            }
+        }
+        else {
+            // It's a single cell address
+            matrix.addCellEx(location);
+        }
+    }
+    remove(locStr, name) {
+        const location = colCache.decodeEx(locStr);
+        if ("error" in location) {
+            return; // Invalid reference, skip
+        }
+        this.removeEx(location, name);
+    }
+    removeEx(location, name) {
+        const matrix = this.getMatrix(name);
+        if ("top" in location) {
+            // Range - remove each cell
+            for (let col = location.left; col <= location.right; col++) {
+                for (let row = location.top; row <= location.bottom; row++) {
+                    matrix.removeCellEx({
+                        sheetName: location.sheetName,
+                        address: colCache.n2l(col) + row,
+                        row,
+                        col
+                    });
+                }
+            }
+        }
+        else {
+            matrix.removeCellEx(location);
+        }
+    }
+    removeAllNames(location) {
+        Object.values(this.matrixMap).forEach((matrix) => {
+            if ("top" in location) {
+                // Range - remove each cell
+                for (let col = location.left; col <= location.right; col++) {
+                    for (let row = location.top; row <= location.bottom; row++) {
+                        matrix.removeCellEx({
+                            sheetName: location.sheetName,
+                            address: colCache.n2l(col) + row,
+                            row,
+                            col
+                        });
+                    }
+                }
+            }
+            else {
+                matrix.removeCellEx(location);
+            }
+        });
+    }
+    forEach(callback) {
+        Object.entries(this.matrixMap).forEach(([name, matrix]) => {
+            matrix.forEach((cell) => {
+                callback(name, cell);
+            });
+        });
+    }
+    // get all the names of a cell
+    getNames(addressStr) {
+        const location = colCache.decodeEx(addressStr);
+        if ("error" in location || "top" in location) {
+            return []; // Invalid reference or range not supported
+        }
+        return this.getNamesEx(location);
+    }
+    getNamesEx(address) {
+        return Object.entries(this.matrixMap)
+            .map(([name, matrix]) => matrix.findCellEx(address, false) && name)
+            .filter((name) => Boolean(name));
+    }
+    _explore(matrix, cell) {
+        cell.mark = false;
+        const { sheetName } = cell;
+        const range = new Range(cell.row, cell.col, cell.row, cell.col, sheetName);
+        let x;
+        let y;
+        // Helper to get cell with proper type
+        const getCell = (row, col) => {
+            return matrix.findCellAt(sheetName, row, col);
+        };
+        // grow vertical - only one col to worry about
+        function vGrow(yy, edge) {
+            const c = getCell(yy, cell.col);
+            if (!c || !c.mark) {
+                return false;
+            }
+            range[edge] = yy;
+            c.mark = false;
+            return true;
+        }
+        for (y = cell.row - 1; vGrow(y, "top"); y--) { }
+        for (y = cell.row + 1; vGrow(y, "bottom"); y++) { }
+        // grow horizontal - ensure all rows can grow
+        function hGrow(xx, edge) {
+            const cells = [];
+            for (y = range.top; y <= range.bottom; y++) {
+                const c = getCell(y, xx);
+                if (c && c.mark) {
+                    cells.push(c);
+                }
+                else {
+                    return false;
+                }
+            }
+            range[edge] = xx;
+            for (let i = 0; i < cells.length; i++) {
+                cells[i].mark = false;
+            }
+            return true;
+        }
+        for (x = cell.col - 1; hGrow(x, "left"); x--) { }
+        for (x = cell.col + 1; hGrow(x, "right"); x++) { }
+        return range;
+    }
+    getRanges(name, matrix) {
+        matrix = matrix || this.matrixMap[name];
+        if (!matrix) {
+            return { name, ranges: [] };
+        }
+        // mark and sweep!
+        matrix.forEach((cell) => {
+            cell.mark = true;
+        });
+        const ranges = matrix
+            .map((cell) => cell.mark && this._explore(matrix, cell))
+            .filter(Boolean)
+            .map((range) => range.$shortRange);
+        return {
+            name,
+            ranges
+        };
+    }
+    normaliseMatrix(matrix, sheetName) {
+        // some of the cells might have shifted on specified sheet
+        // need to reassign rows, cols
+        matrix.forEachInSheet(sheetName, (cell, row, col) => {
+            if (cell) {
+                if (cell.row !== row || cell.col !== col) {
+                    cell.row = row;
+                    cell.col = col;
+                    cell.address = colCache.n2l(col) + row;
+                }
+            }
+        });
+    }
+    spliceRows(sheetName, start, numDelete, numInsert) {
+        Object.values(this.matrixMap).forEach((matrix) => {
+            matrix.spliceRows(sheetName, start, numDelete, numInsert);
+            this.normaliseMatrix(matrix, sheetName);
+        });
+    }
+    spliceColumns(sheetName, start, numDelete, numInsert) {
+        Object.values(this.matrixMap).forEach((matrix) => {
+            matrix.spliceColumns(sheetName, start, numDelete, numInsert);
+            this.normaliseMatrix(matrix, sheetName);
+        });
+    }
+    get model() {
+        // To get names per cell - just iterate over all names finding cells if they exist
+        return Object.entries(this.matrixMap)
+            .map(([name, matrix]) => this.getRanges(name, matrix))
+            .filter((definedName) => definedName.ranges.length);
+    }
+    set model(value) {
+        // value is [ { name, ranges }, ... ]
+        const matrixMap = (this.matrixMap = {});
+        value.forEach(definedName => {
+            const matrix = (matrixMap[definedName.name] = new CellMatrix());
+            definedName.ranges.forEach(rangeStr => {
+                if (rangeRegexp.test(rangeStr.split("!").pop() || "")) {
+                    matrix.addCell(rangeStr);
+                }
+            });
+        });
+    }
+}
+export { DefinedNames };

package/dist/browser/modules/excel/image.d.ts

@@ -0,0 +1,64 @@
+import { Anchor, type AnchorModel } from "@excel/anchor";
+import type { Worksheet } from "@excel/worksheet";
+interface ImageHyperlinks {
+    hyperlink?: string;
+    tooltip?: string;
+}
+interface ImageExt {
+    width?: number;
+    height?: number;
+}
+interface ImageRange {
+    tl: Anchor;
+    br?: Anchor;
+    ext?: ImageExt;
+    editAs?: string;
+    hyperlinks?: ImageHyperlinks;
+}
+interface BackgroundModel {
+    type: "background";
+    imageId: string;
+}
+interface ImageRangeModel {
+    tl: AnchorModel;
+    br?: AnchorModel;
+    ext?: ImageExt;
+    editAs?: string;
+}
+interface ImageModel {
+    type: "image";
+    imageId: string;
+    hyperlinks?: ImageHyperlinks;
+    range: ImageRangeModel;
+}
+type Model = BackgroundModel | ImageModel;
+type ImageModelInput = ModelInput;
+interface RangeInput {
+    tl?: AnchorModel | {
+        col: number;
+        row: number;
+    } | string;
+    br?: AnchorModel | {
+        col: number;
+        row: number;
+    } | string;
+    ext?: ImageExt;
+    editAs?: string;
+    hyperlinks?: ImageHyperlinks;
+}
+interface ModelInput {
+    type: string;
+    imageId: string;
+    range?: string | RangeInput | ImageRangeModel;
+    hyperlinks?: ImageHyperlinks;
+}
+declare class Image {
+    worksheet: Worksheet;
+    type?: string;
+    imageId?: string;
+    range?: ImageRange;
+    constructor(worksheet: Worksheet, model?: ModelInput);
+    get model(): Model;
+    set model({ type, imageId, range, hyperlinks }: ModelInput);
+}
+export { Image, type Model as ImageModel, type ImageModelInput };

package/dist/browser/modules/excel/image.js

@@ -0,0 +1,60 @@
+import { colCache } from "./utils/col-cache.js";
+import { Anchor } from "./anchor.js";
+class Image {
+    constructor(worksheet, model) {
+        this.worksheet = worksheet;
+        if (model) {
+            this.model = model;
+        }
+    }
+    get model() {
+        switch (this.type) {
+            case "background":
+                return {
+                    type: this.type,
+                    imageId: this.imageId
+                };
+            case "image":
+                return {
+                    type: this.type,
+                    imageId: this.imageId,
+                    hyperlinks: this.range.hyperlinks,
+                    range: {
+                        tl: this.range.tl.model,
+                        br: this.range.br && this.range.br.model,
+                        ext: this.range.ext,
+                        editAs: this.range.editAs
+                    }
+                };
+            default:
+                throw new Error("Invalid Image Type");
+        }
+    }
+    set model({ type, imageId, range, hyperlinks }) {
+        this.type = type;
+        this.imageId = imageId;
+        if (type === "image") {
+            if (typeof range === "string") {
+                const decoded = colCache.decode(range);
+                if ("top" in decoded) {
+                    // It's a Location (range like "A1:C3")
+                    this.range = {
+                        tl: new Anchor(this.worksheet, { col: decoded.left, row: decoded.top }, -1),
+                        br: new Anchor(this.worksheet, { col: decoded.right, row: decoded.bottom }, 0),
+                        editAs: "oneCell"
+                    };
+                }
+            }
+            else if (range) {
+                this.range = {
+                    tl: new Anchor(this.worksheet, range.tl, 0),
+                    br: range.br ? new Anchor(this.worksheet, range.br, 0) : undefined,
+                    ext: range.ext,
+                    editAs: range.editAs,
+                    hyperlinks: hyperlinks || ("hyperlinks" in range ? range.hyperlinks : undefined)
+                };
+            }
+        }
+    }
+}
+export { Image };

package/dist/browser/modules/excel/note.js

@@ -0,0 +1,61 @@
+import { deepMerge } from "./utils/under-dash.js";
+class Note {
+    constructor(note) {
+        this.note = note;
+    }
+    get model() {
+        let value = null;
+        switch (typeof this.note) {
+            case "string":
+                value = {
+                    type: "note",
+                    note: {
+                        texts: [
+                            {
+                                text: this.note
+                            }
+                        ]
+                    }
+                };
+                break;
+            default:
+                value = {
+                    type: "note",
+                    note: this.note
+                };
+                break;
+        }
+        // Suitable for all cell comments
+        return deepMerge({}, Note.DEFAULT_CONFIGS, value);
+    }
+    set model(value) {
+        const { note } = value;
+        const { texts } = note;
+        if (texts && texts.length === 1 && Object.keys(texts[0]).length === 1) {
+            this.note = texts[0].text;
+        }
+        else {
+            this.note = note;
+        }
+    }
+    static fromModel(model) {
+        const note = new Note();
+        note.model = model;
+        return note;
+    }
+}
+Note.DEFAULT_CONFIGS = {
+    note: {
+        margins: {
+            insetmode: "auto",
+            inset: [0.13, 0.13, 0.25, 0.25]
+        },
+        protection: {
+            locked: "True",
+            lockText: "True"
+        },
+        editAs: "absolute"
+    },
+    type: "note"
+};
+export { Note };

package/dist/browser/modules/excel/pivot-table.d.ts

@@ -0,0 +1,152 @@
+import type { Table } from "@excel/table";
+/**
+ * Interface representing the source data abstraction for pivot tables.
+ * This allows both Worksheet and Table to be used as pivot table data sources.
+ */
+export interface PivotTableSource {
+    /** Name of the worksheet containing the source data (used in pivotCacheDefinition) */
+    name: string;
+    /** Get row values by 1-indexed row number */
+    getRow(rowNumber: number): {
+        values: any[];
+    };
+    /** Get column values by 1-indexed column number */
+    getColumn(columnNumber: number): {
+        values: any[];
+    };
+    /** Get all sheet values as a sparse 2D array */
+    getSheetValues(): any[][];
+    /** Dimensions with short range reference (e.g., "A1:E10") */
+    dimensions: {
+        shortRange: string;
+    };
+}
+/**
+ * Model for creating a new pivot table.
+ * Pass this to worksheet.addPivotTable() to create a pivot table.
+ */
+export interface PivotTableModel {
+    /**
+     * Source worksheet for the pivot table data.
+     * Either sourceSheet or sourceTable must be provided (mutually exclusive).
+     */
+    sourceSheet?: PivotTableSource;
+    /**
+     * Source table for the pivot table data.
+     * Either sourceSheet or sourceTable must be provided (mutually exclusive).
+     * The table must have headerRow=true and contain at least one data row.
+     */
+    sourceTable?: Table;
+    /** Column names to use as row fields in the pivot table */
+    rows: string[];
+    /**
+     * Column names to use as column fields in the pivot table.
+     * If omitted or empty, Excel will use "Values" as the column field.
+     * @default []
+     */
+    columns?: string[];
+    /** Column names to aggregate as values in the pivot table */
+    values: string[];
+    /**
+     * Aggregation metric for the pivot table values.
+     * - 'sum': Sum of values (default)
+     * - 'count': Count of values
+     * @default 'sum'
+     */
+    metric?: "sum" | "count";
+    /**
+     * Controls whether pivot table style overrides worksheet column widths.
+     * - '0': Preserve worksheet column widths (useful for custom sizing)
+     * - '1': Apply pivot table style width/height (default Excel behavior)
+     * @default '1'
+     */
+    applyWidthHeightFormats?: "0" | "1";
+}
+/**
+ * Represents a cache field in a pivot table.
+ * Cache fields store unique values from source columns for row/column grouping.
+ */
+export interface CacheField {
+    /** Name of the field (column header from source) */
+    name: string;
+    /** Unique values for row/column fields, null for value fields */
+    sharedItems: any[] | null;
+    /** Minimum value for numeric fields */
+    minValue?: number;
+    /** Maximum value for numeric fields */
+    maxValue?: number;
+}
+/** Aggregation function types for pivot table data fields */
+export type PivotTableSubtotal = "sum" | "count" | "average" | "max" | "min" | "product" | "countNums" | "stdDev" | "stdDevP" | "var" | "varP";
+/**
+ * Data field configuration for pivot table aggregation.
+ * Defines how values are aggregated in the pivot table.
+ */
+export interface DataField {
+    /** Display name for the data field (e.g., "Sum of Sales") */
+    name: string;
+    /** Index of the source field in cacheFields */
+    fld: number;
+    /** Base field index for calculated fields */
+    baseField?: number;
+    /** Base item index for calculated fields */
+    baseItem?: number;
+    /** Aggregation function (default: 'sum') */
+    subtotal?: PivotTableSubtotal;
+}
+/**
+ * Internal pivot table representation used by the library.
+ * This is the processed model after calling makePivotTable().
+ */
+export interface PivotTable {
+    /** Source data adapter (always present for new pivot tables) */
+    source?: PivotTableSource;
+    /** Field indices for row fields */
+    rows: number[];
+    /** Field indices for column fields */
+    columns: number[];
+    /** Field indices for value fields */
+    values: number[];
+    /** Aggregation metric */
+    metric: "sum" | "count";
+    /** Cache fields with shared items */
+    cacheFields: CacheField[];
+    /** Cache ID for linking to pivot cache */
+    cacheId: string;
+    /** Width/height format setting */
+    applyWidthHeightFormats: "0" | "1";
+    /** 1-indexed table number for file naming (pivotTable1.xml, pivotTable2.xml, etc.) */
+    tableNumber: number;
+    /** Flag indicating this pivot table was loaded from file (not newly created) */
+    isLoaded?: boolean;
+    /** Data fields for loaded pivot tables */
+    dataFields?: DataField[];
+    /** Cache definition for loaded pivot tables */
+    cacheDefinition?: ParsedCacheDefinition;
+    /** Cache records for loaded pivot tables */
+    cacheRecords?: ParsedCacheRecords;
+}
+/**
+ * Parsed cache definition from loaded pivot table files.
+ */
+export interface ParsedCacheDefinition {
+    sourceRef?: string;
+    sourceSheet?: string;
+    cacheFields: CacheField[];
+    recordCount?: number;
+    rId?: string;
+    isLoaded?: boolean;
+}
+/**
+ * Parsed cache records from loaded pivot table files.
+ */
+export interface ParsedCacheRecords {
+    records: Array<Array<{
+        type: string;
+        value?: any;
+    }>>;
+    count: number;
+    isLoaded?: boolean;
+}
+declare function makePivotTable(worksheet: any, model: PivotTableModel): PivotTable;
+export { makePivotTable };