@cj-tech-master/excelts 4.0.4 → 4.1.0-canary.20260110032830.e7d8c4e

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

@@ -57,6 +57,26 @@ class Table {
         this.worksheet = worksheet;
         if (table) {
             this.table = table;
+            // When loading tables from xlsx, Excel stores table ranges and cell values in the worksheet,
+            // but may not embed row data into the table definition. Hydrate rows from the worksheet so
+            // table mutations (e.g. addRow) can correctly expand table ranges and serialize.
+            if (Array.isArray(table.rows) && table.rows.length === 0 && table.tableRef) {
+                const decoded = colCache.decode(table.tableRef);
+                if ("dimensions" in decoded) {
+                    const startRow = decoded.top + (table.headerRow === false ? 0 : 1);
+                    const endRow = decoded.bottom - (table.totalsRow === true ? 1 : 0);
+                    if (endRow >= startRow) {
+                        for (let r = startRow; r <= endRow; r++) {
+                            const row = worksheet.getRow(r);
+                            const values = [];
+                            for (let c = decoded.left; c <= decoded.right; c++) {
+                                values.push(row.getCell(c).value);
+                            }
+                            table.rows.push(values);
+                        }
+                    }
+                }
+            }
             // check things are ok first
             this.validate();
             this.store();
@@ -133,9 +153,10 @@ class Table {
         const { row, col } = table.tl;
         assert(row > 0, "Table must be on valid row");
         assert(col > 0, "Table must be on valid col");
-        const { width, filterHeight, tableHeight } = this;
-        // autoFilterRef is a range that includes optional headers only
-        table.autoFilterRef = colCache.encode(row, col, row + filterHeight - 1, col + width - 1);
+        const { width, tableHeight } = this;
+        // autoFilterRef is a single-row range that targets the header row only.
+        // Excel uses this for filter buttons; including data rows can break filter rendering.
+        table.autoFilterRef = colCache.encode(row, col, row, col + width - 1);
         // tableRef is a range that includes optional headers and totals
         table.tableRef = colCache.encode(row, col, row + tableHeight - 1, col + width - 1);
         table.columns.forEach((column, i) => {
@@ -304,8 +325,9 @@ class Table {
             }
         }
         this.store();
+        this._cache = undefined;
     }
-    addRow(values, rowNumber) {
+    addRow(values, rowNumber, options) {
         // Add a row of data, either insert at rowNumber or append
         this.cacheState();
         if (rowNumber === undefined) {
@@ -314,11 +336,17 @@ class Table {
         else {
             this.table.rows.splice(rowNumber, 0, values);
         }
+        if (options?.commit !== false) {
+            this.commit();
+        }
     }
-    removeRows(rowIndex, count = 1) {
+    removeRows(rowIndex, count = 1, options) {
         // Remove a rows of data
         this.cacheState();
         this.table.rows.splice(rowIndex, count);
+        if (options?.commit !== false) {
+            this.commit();
+        }
     }
     getColumn(colIndex) {
         const column = this.table.columns[colIndex];

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

@@ -274,7 +274,11 @@ export interface CellSharedFormulaValue {
     result?: number | string | boolean | Date | CellErrorValue;
     date1904?: boolean;
 }
-export type CellValue = null | number | string | boolean | Date | undefined | CellErrorValue | CellRichTextValue | CellHyperlinkValue | CellFormulaValue | CellArrayFormulaValue | CellSharedFormulaValue;
+export interface CellCheckboxValue {
+    /** Indicates this is a checkbox value */
+    checkbox: boolean;
+}
+export type CellValue = null | number | string | boolean | Date | undefined | CellErrorValue | CellRichTextValue | CellHyperlinkValue | CellFormulaValue | CellArrayFormulaValue | CellSharedFormulaValue | CellCheckboxValue;
 export interface CommentMargins {
     insetmode: "auto" | "custom";
     inset: number[];

package/dist/browser/modules/excel/utils/ooxml-paths.d.ts

@@ -8,6 +8,7 @@ export declare const OOXML_PATHS: {
     readonly xlSharedStrings: "xl/sharedStrings.xml";
     readonly xlStyles: "xl/styles.xml";
     readonly xlTheme1: "xl/theme/theme1.xml";
+    readonly xlFeaturePropertyBag: "xl/featurePropertyBag/featurePropertyBag.xml";
 };
 export declare function normalizeZipPath(path: string): string;
 export declare function getWorksheetNoFromWorksheetPath(path: string): number | undefined;
@@ -50,6 +51,7 @@ export declare const OOXML_REL_TARGETS: {
     readonly workbookStyles: "styles.xml";
     readonly workbookSharedStrings: "sharedStrings.xml";
     readonly workbookTheme1: "theme/theme1.xml";
+    readonly workbookFeaturePropertyBag: "featurePropertyBag/featurePropertyBag.xml";
 };
 export declare function pivotCacheDefinitionRelTargetFromWorkbook(n: number | string): string;
 export declare function commentsRelTargetFromWorksheet(sheetId: number | string): string;
@@ -62,3 +64,5 @@ export declare function pivotTableRelTargetFromWorksheetName(pivotName: string):
 export declare function tableRelTargetFromWorksheet(target: string): string;
 export declare function tableRelTargetFromWorksheetName(name: string): string;
 export declare function mediaRelTargetFromRels(filename: string): string;
+export declare function ctrlPropPath(id: number | string): string;
+export declare function ctrlPropRelTargetFromWorksheet(id: number | string): string;

package/dist/browser/modules/excel/utils/ooxml-paths.js

@@ -7,7 +7,8 @@ export const OOXML_PATHS = {
     xlWorkbookRels: "xl/_rels/workbook.xml.rels",
     xlSharedStrings: "xl/sharedStrings.xml",
     xlStyles: "xl/styles.xml",
-    xlTheme1: "xl/theme/theme1.xml"
+    xlTheme1: "xl/theme/theme1.xml",
+    xlFeaturePropertyBag: "xl/featurePropertyBag/featurePropertyBag.xml"
 };
 const worksheetXmlRegex = /^xl\/worksheets\/sheet(\d+)[.]xml$/;
 const worksheetRelsXmlRegex = /^xl\/worksheets\/_rels\/sheet(\d+)[.]xml[.]rels$/;
@@ -162,7 +163,8 @@ export const OOXML_REL_TARGETS = {
     // Targets inside xl/_rels/workbook.xml.rels (base: xl/)
     workbookStyles: "styles.xml",
     workbookSharedStrings: "sharedStrings.xml",
-    workbookTheme1: "theme/theme1.xml"
+    workbookTheme1: "theme/theme1.xml",
+    workbookFeaturePropertyBag: "featurePropertyBag/featurePropertyBag.xml"
 };
 export function pivotCacheDefinitionRelTargetFromWorkbook(n) {
     // Target inside xl/_rels/workbook.xml.rels (base: xl/)
@@ -207,3 +209,11 @@ export function mediaRelTargetFromRels(filename) {
     // Target from a rels file located under xl/*/_rels (base is one level deeper than xl/)
     return `../media/${filename}`;
 }
+// Form Control (ctrlProps) path functions
+export function ctrlPropPath(id) {
+    return `xl/ctrlProps/ctrlProp${id}.xml`;
+}
+export function ctrlPropRelTargetFromWorksheet(id) {
+    // Target inside xl/worksheets/_rels/sheetN.xml.rels (base: xl/worksheets/)
+    return `../ctrlProps/ctrlProp${id}.xml`;
+}

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

@@ -5,6 +5,7 @@ import type { Cell, FormulaResult } from "@excel/cell";
 import { Image, type ImageModel } from "@excel/image";
 import { Table, type TableModel } from "@excel/table";
 import { DataValidations } from "@excel/data-validations";
+import { FormCheckbox, type FormCheckboxModel, type FormCheckboxOptions, type FormControlRange } from "@excel/form-control";
 import { type PivotTable, type PivotTableModel } from "@excel/pivot-table";
 import type { Workbook } from "@excel/workbook";
 import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, RowBreak, RowValues, TableProperties, WorksheetProperties, WorksheetView } from "@excel/types";
@@ -104,6 +105,7 @@ interface WorksheetModel {
     tables: TableModel[];
     pivotTables: PivotTable[];
     conditionalFormattings: ConditionalFormattingOptions[];
+    formControls: FormCheckboxModel[];
     cols?: ColumnModel[];
     rows?: RowModel[];
     dimensions?: Range;
@@ -135,6 +137,7 @@ declare class Worksheet {
     };
     pivotTables: PivotTable[];
     conditionalFormattings: ConditionalFormattingOptions[];
+    formControls: FormCheckbox[];
     private _headerRowCount?;
     constructor(options: WorksheetOptions);
     get name(): string;
@@ -295,6 +298,35 @@ declare class Worksheet {
      */
     addBackgroundImage(imageId: string | number): void;
     getBackgroundImageId(): string | undefined;
+    /**
+     * Add a form control checkbox to the worksheet.
+     *
+     * Form control checkboxes are the legacy style that work in Office 2007+,
+     * WPS Office, LibreOffice, and other spreadsheet applications.
+     *
+     * Unlike modern in-cell checkboxes (which only work in Microsoft 365),
+     * form control checkboxes are floating controls positioned over cells.
+     *
+     * @param range - Cell reference (e.g., "B2") or range (e.g., "B2:D3") for positioning
+     * @param options - Checkbox options
+     * @returns The created FormCheckbox instance
+     *
+     * @example
+     * // Simple checkbox at B2
+     * ws.addFormCheckbox("B2");
+     *
+     * // Checkbox with label and linked cell
+     * ws.addFormCheckbox("B2:D3", {
+     *   text: "Accept terms",
+     *   link: "A2",
+     *   checked: false
+     * });
+     */
+    addFormCheckbox(range: FormControlRange, options?: FormCheckboxOptions): FormCheckbox;
+    /**
+     * Get all form control checkboxes in the worksheet
+     */
+    getFormCheckboxes(): FormCheckbox[];
     /**
      * Protect the worksheet with optional password and options
      */

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

@@ -6,6 +6,7 @@ import { Enums } from "./enums.js";
 import { Image } from "./image.js";
 import { Table } from "./table.js";
 import { DataValidations } from "./data-validations.js";
+import { FormCheckbox } from "./form-control.js";
 import { Encryptor } from "./utils/encryptor.browser.js";
 import { uint8ArrayToBase64 } from "../../utils/utils.browser.js";
 import { makePivotTable } from "./pivot-table.js";
@@ -92,6 +93,8 @@ class Worksheet {
         this.tables = {};
         this.pivotTables = [];
         this.conditionalFormattings = [];
+        // for form controls (legacy checkboxes, etc.)
+        this.formControls = [];
     }
     get name() {
         return this._name;
@@ -745,6 +748,43 @@ class Worksheet {
         return image && image.imageId;
     }
     // =========================================================================
+    // Form Controls (Legacy Checkboxes)
+    /**
+     * Add a form control checkbox to the worksheet.
+     *
+     * Form control checkboxes are the legacy style that work in Office 2007+,
+     * WPS Office, LibreOffice, and other spreadsheet applications.
+     *
+     * Unlike modern in-cell checkboxes (which only work in Microsoft 365),
+     * form control checkboxes are floating controls positioned over cells.
+     *
+     * @param range - Cell reference (e.g., "B2") or range (e.g., "B2:D3") for positioning
+     * @param options - Checkbox options
+     * @returns The created FormCheckbox instance
+     *
+     * @example
+     * // Simple checkbox at B2
+     * ws.addFormCheckbox("B2");
+     *
+     * // Checkbox with label and linked cell
+     * ws.addFormCheckbox("B2:D3", {
+     *   text: "Accept terms",
+     *   link: "A2",
+     *   checked: false
+     * });
+     */
+    addFormCheckbox(range, options) {
+        const checkbox = new FormCheckbox(this, range, options);
+        this.formControls.push(checkbox);
+        return checkbox;
+    }
+    /**
+     * Get all form control checkboxes in the worksheet
+     */
+    getFormCheckboxes() {
+        return this.formControls;
+    }
+    // =========================================================================
     // Worksheet Protection
     /**
      * Protect the worksheet with optional password and options
@@ -853,7 +893,8 @@ class Worksheet {
             sheetProtection: this.sheetProtection,
             tables: Object.values(this.tables).map(table => table.model),
             pivotTables: this.pivotTables,
-            conditionalFormattings: this.conditionalFormattings
+            conditionalFormattings: this.conditionalFormattings,
+            formControls: this.formControls.map(fc => fc.model)
         };
         // =================================================
         // columns
@@ -919,6 +960,8 @@ class Worksheet {
         }, {});
         this.pivotTables = value.pivotTables;
         this.conditionalFormattings = value.conditionalFormattings;
+        // Form controls are currently write-only (not parsed from XLSX)
+        this.formControls = [];
     }
 }
 export { Worksheet };

package/dist/browser/modules/excel/xlsx/rel-type.d.ts

@@ -15,5 +15,7 @@ declare const RelType: {
     PivotCacheDefinition: string;
     PivotCacheRecords: string;
     PivotTable: string;
+    FeaturePropertyBag: string;
+    CtrlProp: string;
 };
 export { RelType };

package/dist/browser/modules/excel/xlsx/rel-type.js

@@ -14,6 +14,8 @@ const RelType = {
     Table: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/table",
     PivotCacheDefinition: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheDefinition",
     PivotCacheRecords: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheRecords",
-    PivotTable: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotTable"
+    PivotTable: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotTable",
+    FeaturePropertyBag: "http://schemas.microsoft.com/office/2022/11/relationships/FeaturePropertyBag",
+    CtrlProp: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp"
 };
 export { RelType };

package/dist/browser/modules/excel/xlsx/xform/core/content-types-xform.js

@@ -1,6 +1,6 @@
 import { XmlStream } from "../../../utils/xml-stream.js";
 import { BaseXform } from "../base-xform.js";
-import { OOXML_PATHS, commentsPathFromName, drawingPath, pivotCacheDefinitionPath, pivotCacheRecordsPath, pivotTablePath, tablePath, toContentTypesPartName, worksheetPath } from "../../../utils/ooxml-paths.js";
+import { OOXML_PATHS, commentsPathFromName, ctrlPropPath, drawingPath, pivotCacheDefinitionPath, pivotCacheRecordsPath, pivotTablePath, tablePath, toContentTypesPartName, worksheetPath } from "../../../utils/ooxml-paths.js";
 // used for rendering the [Content_Types].xml file
 // not used for parsing
 class ContentTypesXform extends BaseXform {
@@ -63,6 +63,13 @@ class ContentTypesXform extends BaseXform {
             PartName: toContentTypesPartName(OOXML_PATHS.xlStyles),
             ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"
         });
+        // Add FeaturePropertyBag if checkboxes are used
+        if (model.hasCheckboxes) {
+            xmlStream.leafNode("Override", {
+                PartName: toContentTypesPartName(OOXML_PATHS.xlFeaturePropertyBag),
+                ContentType: "application/vnd.ms-excel.featurepropertybag+xml"
+            });
+        }
         const hasSharedStrings = model.sharedStrings && model.sharedStrings.count;
         if (hasSharedStrings) {
             xmlStream.leafNode("Override", {
@@ -98,6 +105,22 @@ class ContentTypesXform extends BaseXform {
                 });
             });
         }
+        // Add form control (ctrlProps) content types
+        if (model.formControlRefs) {
+            // Ensure vml extension is declared (may already be declared for comments)
+            if (!model.commentRefs) {
+                xmlStream.leafNode("Default", {
+                    Extension: "vml",
+                    ContentType: "application/vnd.openxmlformats-officedocument.vmlDrawing"
+                });
+            }
+            for (const ctrlPropId of model.formControlRefs) {
+                xmlStream.leafNode("Override", {
+                    PartName: toContentTypesPartName(ctrlPropPath(ctrlPropId)),
+                    ContentType: "application/vnd.ms-excel.controlproperties+xml"
+                });
+            }
+        }
         xmlStream.leafNode("Override", {
             PartName: toContentTypesPartName(OOXML_PATHS.docPropsCore),
             ContentType: "application/vnd.openxmlformats-package.core-properties+xml"

package/dist/browser/modules/excel/xlsx/xform/core/feature-property-bag-xform.d.ts

@@ -0,0 +1,8 @@
+import { BaseXform } from "@excel/xlsx/xform/base-xform";
+declare class FeaturePropertyBagXform extends BaseXform {
+    render(xmlStream: any): void;
+    parseOpen(): boolean;
+    parseText(): void;
+    parseClose(): boolean;
+}
+export { FeaturePropertyBagXform };

package/dist/browser/modules/excel/xlsx/xform/core/feature-property-bag-xform.js

@@ -0,0 +1,36 @@
+import { BaseXform } from "../base-xform.js";
+// FeaturePropertyBag is used to enable checkbox functionality
+// This is a static XML file that MS Excel requires for checkboxes to work
+class FeaturePropertyBagXform extends BaseXform {
+    render(xmlStream) {
+        xmlStream.openXml({ version: "1.0", encoding: "UTF-8", standalone: "yes" });
+        xmlStream.openNode("FeaturePropertyBags", {
+            xmlns: "http://schemas.microsoft.com/office/spreadsheetml/2022/featurepropertybag"
+        });
+        // Checkbox feature
+        xmlStream.leafNode("bag", { type: "Checkbox" });
+        // XFControls bag
+        xmlStream.openNode("bag", { type: "XFControls" });
+        xmlStream.leafNode("bagId", { k: "CellControl" }, "0");
+        xmlStream.closeNode();
+        // XFComplement bag
+        xmlStream.openNode("bag", { type: "XFComplement" });
+        xmlStream.leafNode("bagId", { k: "XFControls" }, "1");
+        xmlStream.closeNode();
+        // XFComplements bag
+        xmlStream.openNode("bag", { type: "XFComplements", extRef: "XFComplementsMapperExtRef" });
+        xmlStream.openNode("a", { k: "MappedFeaturePropertyBags" });
+        xmlStream.leafNode("bagId", {}, "2");
+        xmlStream.closeNode();
+        xmlStream.closeNode();
+        xmlStream.closeNode();
+    }
+    parseOpen() {
+        return false;
+    }
+    parseText() { }
+    parseClose() {
+        return false;
+    }
+}
+export { FeaturePropertyBagXform };

package/dist/browser/modules/excel/xlsx/xform/drawing/ctrl-prop-xform.d.ts

@@ -0,0 +1,22 @@
+import { BaseXform } from "@excel/xlsx/xform/base-xform";
+import type { FormCheckboxModel } from "@excel/form-control";
+/**
+ * Control Properties Xform - Generates ctrlProp*.xml for form controls
+ *
+ * Each form control (checkbox, button, etc.) has an associated ctrlProp file
+ * that stores its properties like objectType, checked state, and linked cell.
+ */
+declare class CtrlPropXform extends BaseXform {
+    model: FormCheckboxModel;
+    get tag(): string;
+    render(xmlStream: any, model?: FormCheckboxModel): void;
+    /**
+     * Generate XML string directly (convenience method)
+     * Uses render() internally to ensure consistency
+     */
+    toXml(model: FormCheckboxModel): string;
+    parseOpen(): boolean;
+    parseText(): void;
+    parseClose(): boolean;
+}
+export { CtrlPropXform };

package/dist/browser/modules/excel/xlsx/xform/drawing/ctrl-prop-xform.js

@@ -0,0 +1,52 @@
+import { XmlStream } from "../../../utils/xml-stream.js";
+import { BaseXform } from "../base-xform.js";
+/**
+ * Control Properties Xform - Generates ctrlProp*.xml for form controls
+ *
+ * Each form control (checkbox, button, etc.) has an associated ctrlProp file
+ * that stores its properties like objectType, checked state, and linked cell.
+ */
+class CtrlPropXform extends BaseXform {
+    get tag() {
+        return "formControlPr";
+    }
+    render(xmlStream, model) {
+        const renderModel = model || this.model;
+        const attrs = {
+            xmlns: "http://schemas.microsoft.com/office/spreadsheetml/2009/9/main",
+            objectType: "CheckBox",
+            checked: renderModel.checked,
+            lockText: "1"
+        };
+        // Add linked cell reference
+        if (renderModel.link) {
+            attrs.fmlaLink = renderModel.link;
+        }
+        // Add noThreeD for flat appearance
+        if (renderModel.noThreeD) {
+            attrs.noThreeD = "1";
+        }
+        xmlStream.openXml({ version: "1.0", encoding: "UTF-8", standalone: "yes" });
+        xmlStream.leafNode(this.tag, attrs);
+    }
+    /**
+     * Generate XML string directly (convenience method)
+     * Uses render() internally to ensure consistency
+     */
+    toXml(model) {
+        const xmlStream = new XmlStream();
+        this.render(xmlStream, model);
+        return xmlStream.xml;
+    }
+    // Parsing not implemented - form controls are write-only for now
+    parseOpen() {
+        return true;
+    }
+    parseText() {
+        // Not implemented
+    }
+    parseClose() {
+        return false;
+    }
+}
+export { CtrlPropXform };

package/dist/browser/modules/excel/xlsx/xform/drawing/vml-drawing-xform.d.ts

@@ -0,0 +1,44 @@
+import { BaseXform } from "@excel/xlsx/xform/base-xform";
+import { type FormCheckboxModel } from "@excel/form-control";
+/**
+ * Unified VML Drawing Xform - Combines Notes (comments) and Form Controls
+ *
+ * Excel uses a single VML file per worksheet that can contain:
+ * - Comment/note shapes (shapetype 202)
+ * - Form control shapes (checkbox shapetype 201, etc.)
+ *
+ * This unified xform renders both into a single VML file.
+ */
+interface VmlDrawingModel {
+    /** Comment/note shapes */
+    comments?: any[];
+    /** Form control checkboxes */
+    formControls?: FormCheckboxModel[];
+}
+declare class VmlDrawingXform extends BaseXform {
+    map: {
+        [key: string]: any;
+    };
+    parser: any;
+    model: VmlDrawingModel;
+    constructor();
+    get tag(): string;
+    /**
+     * Render VML drawing containing both notes and form controls
+     */
+    render(xmlStream: any, model?: VmlDrawingModel): void;
+    /**
+     * Render a checkbox form control shape
+     */
+    private _renderCheckboxShape;
+    parseOpen(node: any): boolean;
+    parseText(text: string): void;
+    parseClose(name: string): boolean;
+    static DRAWING_ATTRIBUTES: {
+        "xmlns:v": string;
+        "xmlns:o": string;
+        "xmlns:x": string;
+    };
+}
+export { VmlDrawingXform };
+export type { VmlDrawingModel };