@cj-tech-master/excelts 3.1.0-canary.20260102041828.82ed571 → 3.1.0

package/dist/esm/doc/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/esm/doc/pivot-table.js

@@ -0,0 +1,237 @@
+import { range, toSortedArray } from "../utils/utils.js";
+import { colCache } from "../utils/col-cache.js";
+// TK(2023-10-10): turn this into a class constructor.
+/**
+ * Creates a PivotTableSource adapter from a Table object.
+ * This allows Tables to be used as pivot table data sources with the same interface as Worksheets.
+ */
+function createTableSourceAdapter(table) {
+    const tableModel = table.model;
+    // Validate that table has headerRow enabled (required for pivot table column names)
+    if (tableModel.headerRow === false) {
+        throw new Error("Cannot create pivot table from a table without headers. Set headerRow: true on the table.");
+    }
+    // Validate table has data rows
+    if (!tableModel.rows || tableModel.rows.length === 0) {
+        throw new Error("Cannot create pivot table from an empty table. Add data rows to the table.");
+    }
+    const columnNames = tableModel.columns.map(col => col.name);
+    // Check for duplicate column names
+    const nameSet = new Set();
+    for (const name of columnNames) {
+        if (nameSet.has(name)) {
+            throw new Error(`Duplicate column name "${name}" found in table. Pivot tables require unique column names.`);
+        }
+        nameSet.add(name);
+    }
+    // Build the full data array: headers + rows
+    const headerRow = [undefined, ...columnNames]; // sparse array starting at index 1
+    const dataRows = tableModel.rows.map(row => [undefined, ...row]); // sparse array starting at index 1
+    // Calculate the range reference for the table
+    const tl = tableModel.tl;
+    const startRow = tl.row;
+    const startCol = tl.col;
+    const endRow = startRow + tableModel.rows.length; // header row + data rows
+    const endCol = startCol + columnNames.length - 1;
+    const shortRange = colCache.encode(startRow, startCol, endRow, endCol);
+    // Use the worksheet name (not table name) for pivotCacheDefinition's worksheetSource
+    // The sheet attribute in worksheetSource must reference the actual worksheet name
+    const worksheetName = table.worksheet.name;
+    return {
+        name: worksheetName,
+        getRow(rowNumber) {
+            if (rowNumber === 1) {
+                return { values: headerRow };
+            }
+            const dataIndex = rowNumber - 2; // rowNumber 2 maps to index 0
+            if (dataIndex >= 0 && dataIndex < dataRows.length) {
+                return { values: dataRows[dataIndex] };
+            }
+            return { values: [] };
+        },
+        getColumn(columnNumber) {
+            // Validate column number is within bounds
+            if (columnNumber < 1 || columnNumber > columnNames.length) {
+                return { values: [] };
+            }
+            // Values should be sparse array with header at index 1, data starting at index 2
+            const values = [];
+            values[1] = columnNames[columnNumber - 1];
+            for (let i = 0; i < tableModel.rows.length; i++) {
+                values[i + 2] = tableModel.rows[i][columnNumber - 1];
+            }
+            return { values };
+        },
+        getSheetValues() {
+            // Return sparse array where index 1 is header row, and subsequent indices are data rows
+            const result = [];
+            result[1] = headerRow;
+            for (let i = 0; i < dataRows.length; i++) {
+                result[i + 2] = dataRows[i];
+            }
+            return result;
+        },
+        dimensions: { shortRange }
+    };
+}
+/**
+ * Resolves the data source from the model, supporting both sourceSheet and sourceTable.
+ */
+function resolveSource(model) {
+    if (model.sourceTable) {
+        return createTableSourceAdapter(model.sourceTable);
+    }
+    // For sourceSheet, it already implements the required interface
+    return model.sourceSheet;
+}
+function makePivotTable(worksheet, model) {
+    // Example `model`:
+    // {
+    //   // Source of data (either sourceSheet OR sourceTable):
+    //   sourceSheet: worksheet1,  // Use entire sheet range
+    //   // OR
+    //   sourceTable: table,       // Use table data
+    //
+    //   // Pivot table fields: values indicate field names;
+    //   // they come from the first row in `worksheet1` or table column names.
+    //   rows: ['A', 'B'],
+    //   columns: ['C'],
+    //   values: ['E'], // only 1 item possible for now
+    //   metric: 'sum', // only 'sum' possible for now
+    // }
+    // Validate source exists before trying to resolve it
+    if (!model.sourceSheet && !model.sourceTable) {
+        throw new Error("Either sourceSheet or sourceTable must be provided.");
+    }
+    if (model.sourceSheet && model.sourceTable) {
+        throw new Error("Cannot specify both sourceSheet and sourceTable. Choose one.");
+    }
+    // Resolve source first to avoid creating adapter multiple times
+    const source = resolveSource(model);
+    validate(worksheet, model, source);
+    const { rows, values } = model;
+    const columns = model.columns ?? [];
+    const cacheFields = makeCacheFields(source, [...rows, ...columns], values);
+    const nameToIndex = cacheFields.reduce((result, cacheField, index) => {
+        result[cacheField.name] = index;
+        return result;
+    }, {});
+    const rowIndices = rows.map(row => nameToIndex[row]);
+    const columnIndices = columns.map(column => nameToIndex[column]);
+    const valueIndices = values.map(value => nameToIndex[value]);
+    // Calculate tableNumber based on existing pivot tables (1-indexed)
+    const tableNumber = worksheet.workbook.pivotTables.length + 1;
+    // Base cache ID starts at 10 (Excel convention), each subsequent table increments
+    const BASE_CACHE_ID = 10;
+    // form pivot table object
+    return {
+        source,
+        rows: rowIndices,
+        columns: columnIndices,
+        values: valueIndices,
+        metric: model.metric ?? "sum",
+        cacheFields,
+        // Dynamic cacheId: 10 for first table, 11 for second, etc.
+        // Used in <pivotTableDefinition> and xl/workbook.xml
+        cacheId: String(BASE_CACHE_ID + tableNumber - 1),
+        // Control 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)
+        applyWidthHeightFormats: model.applyWidthHeightFormats ?? "1",
+        // Table number for file naming (pivotTable1.xml, pivotTable2.xml, etc.)
+        tableNumber
+    };
+}
+function validate(_worksheet, model, source) {
+    if (model.metric && model.metric !== "sum" && model.metric !== "count") {
+        throw new Error('Only the "sum" and "count" metrics are supported at this time.');
+    }
+    const columns = model.columns ?? [];
+    // Get header names from source (already resolved)
+    const headerNames = source.getRow(1).values.slice(1);
+    // Use Set for O(1) lookup
+    const headerNameSet = new Set(headerNames);
+    for (const name of [...model.rows, ...columns, ...model.values]) {
+        if (!headerNameSet.has(name)) {
+            throw new Error(`The header name "${name}" was not found in ${source.name}.`);
+        }
+    }
+    if (!model.rows.length) {
+        throw new Error("No pivot table rows specified.");
+    }
+    // Allow empty columns - Excel will use "Values" as column field
+    // But can't have multiple values with columns specified
+    if (model.values.length < 1) {
+        throw new Error("Must have at least one value.");
+    }
+    if (model.values.length > 1 && columns.length > 0) {
+        throw new Error("It is currently not possible to have multiple values when columns are specified. Please either supply an empty array for columns or a single value.");
+    }
+}
+function makeCacheFields(source, fieldNamesWithSharedItems, valueFieldNames) {
+    // Cache fields are used in pivot tables to reference source data.
+    // Fields in fieldNamesWithSharedItems get their unique values extracted as sharedItems.
+    // Fields in valueFieldNames (but not in fieldNamesWithSharedItems) get min/max calculated.
+    // Other fields are unused and get empty sharedItems.
+    const names = source.getRow(1).values;
+    // Use Set for O(1) lookup instead of object
+    const sharedItemsFields = new Set(fieldNamesWithSharedItems);
+    const valueFields = new Set(valueFieldNames);
+    const aggregate = (columnIndex) => {
+        const columnValues = source.getColumn(columnIndex).values;
+        // Build unique values set directly, skipping header (index 0,1) and null/undefined
+        const uniqueValues = new Set();
+        for (let i = 2; i < columnValues.length; i++) {
+            const v = columnValues[i];
+            if (v !== null && v !== undefined) {
+                uniqueValues.add(v);
+            }
+        }
+        return toSortedArray(uniqueValues);
+    };
+    // Calculate min/max for numeric fields
+    const getMinMax = (columnIndex) => {
+        const columnValues = source.getColumn(columnIndex).values;
+        let min = Infinity;
+        let max = -Infinity;
+        let hasNumeric = false;
+        for (let i = 2; i < columnValues.length; i++) {
+            const v = columnValues[i];
+            if (typeof v === "number" && !isNaN(v)) {
+                hasNumeric = true;
+                if (v < min) {
+                    min = v;
+                }
+                if (v > max) {
+                    max = v;
+                }
+            }
+        }
+        return hasNumeric ? { minValue: min, maxValue: max } : null;
+    };
+    // Build result array
+    const result = [];
+    for (const columnIndex of range(1, names.length)) {
+        const name = names[columnIndex];
+        if (sharedItemsFields.has(name)) {
+            // Field used for rows/columns - extract unique values as sharedItems
+            result.push({ name, sharedItems: aggregate(columnIndex) });
+        }
+        else if (valueFields.has(name)) {
+            // Field used only for values (aggregation) - calculate min/max
+            const minMax = getMinMax(columnIndex);
+            result.push({
+                name,
+                sharedItems: null,
+                minValue: minMax?.minValue,
+                maxValue: minMax?.maxValue
+            });
+        }
+        else {
+            // Unused field - just empty sharedItems (like Excel does)
+            result.push({ name, sharedItems: null });
+        }
+    }
+    return result;
+}
+export { makePivotTable };

package/dist/esm/doc/range.js

@@ -0,0 +1,280 @@
+import { colCache } from "../utils/col-cache.js";
+// used by worksheet to calculate sheet dimensions
+class Range {
+    constructor(...args) {
+        this.model = {
+            top: 0,
+            left: 0,
+            bottom: 0,
+            right: 0
+        };
+        this.decode(args);
+    }
+    setTLBR(t, l, b, r, s) {
+        if (typeof t === "string" && typeof l === "string") {
+            // setTLBR(tl, br, s) - t and l are address strings
+            const tl = colCache.decodeAddress(t);
+            const br = colCache.decodeAddress(l);
+            this.model = {
+                top: Math.min(tl.row, br.row),
+                left: Math.min(tl.col, br.col),
+                bottom: Math.max(tl.row, br.row),
+                right: Math.max(tl.col, br.col),
+                sheetName: typeof b === "string" ? b : undefined
+            };
+        }
+        else if (typeof t === "number" &&
+            typeof l === "number" &&
+            typeof b === "number" &&
+            typeof r === "number") {
+            // setTLBR(t, l, b, r, s) - all numbers
+            this.model = {
+                top: Math.min(t, b),
+                left: Math.min(l, r),
+                bottom: Math.max(t, b),
+                right: Math.max(l, r),
+                sheetName: s
+            };
+        }
+    }
+    decode(argv) {
+        switch (argv.length) {
+            case 5: // [t,l,b,r,s]
+                if (typeof argv[0] === "number" &&
+                    typeof argv[1] === "number" &&
+                    typeof argv[2] === "number" &&
+                    typeof argv[3] === "number" &&
+                    typeof argv[4] === "string") {
+                    this.setTLBR(argv[0], argv[1], argv[2], argv[3], argv[4]);
+                }
+                break;
+            case 4: // [t,l,b,r]
+                if (typeof argv[0] === "number" &&
+                    typeof argv[1] === "number" &&
+                    typeof argv[2] === "number" &&
+                    typeof argv[3] === "number") {
+                    this.setTLBR(argv[0], argv[1], argv[2], argv[3]);
+                }
+                break;
+            case 3: // [tl,br,s]
+                if (typeof argv[0] === "string" &&
+                    typeof argv[1] === "string" &&
+                    typeof argv[2] === "string") {
+                    this.setTLBR(argv[0], argv[1], argv[2]);
+                }
+                break;
+            case 2: // [tl,br]
+                if (typeof argv[0] === "string" && typeof argv[1] === "string") {
+                    this.setTLBR(argv[0], argv[1]);
+                }
+                break;
+            case 1: {
+                const value = argv[0];
+                if (value instanceof Range) {
+                    // copy constructor
+                    this.model = {
+                        top: value.model.top,
+                        left: value.model.left,
+                        bottom: value.model.bottom,
+                        right: value.model.right,
+                        sheetName: value.sheetName
+                    };
+                }
+                else if (Array.isArray(value)) {
+                    // an arguments array
+                    this.decode(value);
+                }
+                else if (typeof value === "object" &&
+                    "top" in value &&
+                    "left" in value &&
+                    "bottom" in value &&
+                    "right" in value) {
+                    // a model
+                    this.model = {
+                        top: value.top,
+                        left: value.left,
+                        bottom: value.bottom,
+                        right: value.right,
+                        sheetName: value.sheetName
+                    };
+                }
+                else if (typeof value === "string") {
+                    // [sheetName!]tl:br
+                    const decoded = colCache.decodeEx(value);
+                    if ("top" in decoded) {
+                        // It's a DecodedRange
+                        this.model = {
+                            top: decoded.top,
+                            left: decoded.left,
+                            bottom: decoded.bottom,
+                            right: decoded.right,
+                            sheetName: decoded.sheetName
+                        };
+                    }
+                    else if ("row" in decoded) {
+                        // It's an Address
+                        this.model = {
+                            top: decoded.row,
+                            left: decoded.col,
+                            bottom: decoded.row,
+                            right: decoded.col,
+                            sheetName: decoded.sheetName
+                        };
+                    }
+                }
+                break;
+            }
+            case 0:
+                this.model = {
+                    top: 0,
+                    left: 0,
+                    bottom: 0,
+                    right: 0
+                };
+                break;
+            default:
+                throw new Error(`Invalid number of arguments to _getDimensions() - ${argv.length}`);
+        }
+    }
+    get top() {
+        return this.model.top || 1;
+    }
+    set top(value) {
+        this.model.top = value;
+    }
+    get left() {
+        return this.model.left || 1;
+    }
+    set left(value) {
+        this.model.left = value;
+    }
+    get bottom() {
+        return this.model.bottom || 1;
+    }
+    set bottom(value) {
+        this.model.bottom = value;
+    }
+    get right() {
+        return this.model.right || 1;
+    }
+    set right(value) {
+        this.model.right = value;
+    }
+    get sheetName() {
+        return this.model.sheetName;
+    }
+    set sheetName(value) {
+        this.model.sheetName = value;
+    }
+    get _serialisedSheetName() {
+        const { sheetName } = this.model;
+        if (sheetName) {
+            if (/^[a-zA-Z0-9]*$/.test(sheetName)) {
+                return `${sheetName}!`;
+            }
+            return `'${sheetName}'!`;
+        }
+        return "";
+    }
+    expand(top, left, bottom, right) {
+        if (!this.model.top || top < this.top) {
+            this.top = top;
+        }
+        if (!this.model.left || left < this.left) {
+            this.left = left;
+        }
+        if (!this.model.bottom || bottom > this.bottom) {
+            this.bottom = bottom;
+        }
+        if (!this.model.right || right > this.right) {
+            this.right = right;
+        }
+    }
+    expandRow(row) {
+        if (row) {
+            const { dimensions, number } = row;
+            if (dimensions) {
+                this.expand(number, dimensions.min, number, dimensions.max);
+            }
+        }
+    }
+    expandToAddress(addressStr) {
+        const address = colCache.decodeEx(addressStr);
+        if ("row" in address && "col" in address) {
+            this.expand(address.row, address.col, address.row, address.col);
+        }
+    }
+    get tl() {
+        return colCache.n2l(this.left) + this.top;
+    }
+    get $t$l() {
+        return `$${colCache.n2l(this.left)}$${this.top}`;
+    }
+    get br() {
+        return colCache.n2l(this.right) + this.bottom;
+    }
+    get $b$r() {
+        return `$${colCache.n2l(this.right)}$${this.bottom}`;
+    }
+    get range() {
+        return `${this._serialisedSheetName + this.tl}:${this.br}`;
+    }
+    get $range() {
+        return `${this._serialisedSheetName + this.$t$l}:${this.$b$r}`;
+    }
+    get shortRange() {
+        return this.count > 1 ? this.range : this._serialisedSheetName + this.tl;
+    }
+    get $shortRange() {
+        return this.count > 1 ? this.$range : this._serialisedSheetName + this.$t$l;
+    }
+    get count() {
+        return (1 + this.bottom - this.top) * (1 + this.right - this.left);
+    }
+    toString() {
+        return this.range;
+    }
+    intersects(other) {
+        if (other.sheetName && this.sheetName && other.sheetName !== this.sheetName) {
+            return false;
+        }
+        if (other.bottom < this.top) {
+            return false;
+        }
+        if (other.top > this.bottom) {
+            return false;
+        }
+        if (other.right < this.left) {
+            return false;
+        }
+        if (other.left > this.right) {
+            return false;
+        }
+        return true;
+    }
+    contains(addressStr) {
+        const address = colCache.decodeEx(addressStr);
+        if ("row" in address && "col" in address) {
+            return this.containsEx(address);
+        }
+        return false;
+    }
+    containsEx(address) {
+        if (address.sheetName && this.sheetName && address.sheetName !== this.sheetName) {
+            return false;
+        }
+        return (address.row >= this.top &&
+            address.row <= this.bottom &&
+            address.col >= this.left &&
+            address.col <= this.right);
+    }
+    forEachAddress(cb) {
+        for (let col = this.left; col <= this.right; col++) {
+            for (let row = this.top; row <= this.bottom; row++) {
+                cb(colCache.encodeAddress(row, col), row, col);
+            }
+        }
+    }
+}
+export { Range };
+export { Range as Dimensions };