@cj-tech-master/excelts 4.0.4 → 4.1.0-canary.20260110033117.75bcac1

package/dist/browser/index.browser.d.ts

@@ -12,9 +12,11 @@ export { Image } from "@excel/image";
 export * from "@excel/anchor";
 export { Table } from "@excel/table";
 export { DataValidations } from "@excel/data-validations";
+export { FormCheckbox } from "@excel/form-control";
 export * from "@excel/enums";
 export * from "@excel/types";
 export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "@excel/pivot-table";
+export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "@excel/form-control";
 import { WorkbookWriter } from "@excel/stream/workbook-writer.browser";
 import { WorkbookReader } from "@excel/stream/workbook-reader.browser";
 import { WorksheetWriter } from "@excel/stream/worksheet-writer";

package/dist/browser/index.browser.js

@@ -15,6 +15,7 @@ export { Image } from "./modules/excel/image.js";
 export * from "./modules/excel/anchor.js";
 export { Table } from "./modules/excel/table.js";
 export { DataValidations } from "./modules/excel/data-validations.js";
+export { FormCheckbox } from "./modules/excel/form-control.js";
 // =============================================================================
 // Enums
 // =============================================================================

package/dist/browser/index.d.ts

@@ -8,6 +8,7 @@ export { Image } from "@excel/image";
 export * from "@excel/anchor";
 export { Table } from "@excel/table";
 export { DataValidations } from "@excel/data-validations";
+export { FormCheckbox } from "@excel/form-control";
 export { WorkbookWriter } from "@excel/stream/workbook-writer";
 export { WorkbookReader } from "@excel/stream/workbook-reader";
 export { WorksheetWriter } from "@excel/stream/worksheet-writer";
@@ -15,6 +16,7 @@ export { WorksheetReader } from "@excel/stream/worksheet-reader";
 export * from "@excel/enums";
 export * from "@excel/types";
 export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "@excel/pivot-table";
+export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "@excel/form-control";
 export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "@excel/stream/workbook-reader";
 export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "@excel/stream/worksheet-reader";
 export type { WorkbookWriterOptions, ZipOptions, ZlibOptions } from "@excel/stream/workbook-writer";

package/dist/browser/index.js

@@ -11,6 +11,7 @@ export { Image } from "./modules/excel/image.js";
 export * from "./modules/excel/anchor.js";
 export { Table } from "./modules/excel/table.js";
 export { DataValidations } from "./modules/excel/data-validations.js";
+export { FormCheckbox } from "./modules/excel/form-control.js";
 // =============================================================================
 // Node.js Only: Streaming Classes
 // These can also be accessed via Workbook.createStreamWriter/createStreamReader

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

@@ -809,6 +809,40 @@ class BooleanValue {
         return this.model.value.toString();
     }
 }
+class CheckboxValue {
+    constructor(cell, value) {
+        this.model = {
+            address: cell.address,
+            type: Cell.Types.Checkbox,
+            value: value.checkbox
+        };
+    }
+    get value() {
+        return { checkbox: this.model.value };
+    }
+    set value(value) {
+        this.model.value = value.checkbox;
+    }
+    get type() {
+        return Cell.Types.Checkbox;
+    }
+    get effectiveType() {
+        return Cell.Types.Boolean;
+    }
+    get address() {
+        return this.model.address;
+    }
+    set address(value) {
+        this.model.address = value;
+    }
+    toCsvString() {
+        return this.model.value ? 1 : 0;
+    }
+    release() { }
+    toString() {
+        return this.model.value.toString();
+    }
+}
 class ErrorValue {
     constructor(cell, value) {
         this.model = {
@@ -898,6 +932,9 @@ const Value = {
             return Cell.Types.Date;
         }
         if (typeof value === "object") {
+            if ("checkbox" in value && typeof value.checkbox === "boolean") {
+                return Cell.Types.Checkbox;
+            }
             if ("text" in value && value.text && "hyperlink" in value && value.hyperlink) {
                 return Cell.Types.Hyperlink;
             }
@@ -930,7 +967,8 @@ const Value = {
         { t: Cell.Types.SharedString, f: SharedStringValue },
         { t: Cell.Types.RichText, f: RichTextValue },
         { t: Cell.Types.Boolean, f: BooleanValue },
-        { t: Cell.Types.Error, f: ErrorValue }
+        { t: Cell.Types.Error, f: ErrorValue },
+        { t: Cell.Types.Checkbox, f: CheckboxValue }
     ].reduce((p, t) => {
         p[t.t] = t.f;
         return p;

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

@@ -10,7 +10,8 @@ export declare enum ValueType {
     RichText = 8,
     Boolean = 9,
     Error = 10,
-    JSON = 11
+    JSON = 11,// Internal type for JSON values that serialize as String
+    Checkbox = 12
 }
 export declare enum FormulaType {
     None = 0,

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

@@ -11,7 +11,8 @@ export var ValueType;
     ValueType[ValueType["RichText"] = 8] = "RichText";
     ValueType[ValueType["Boolean"] = 9] = "Boolean";
     ValueType[ValueType["Error"] = 10] = "Error";
-    ValueType[ValueType["JSON"] = 11] = "JSON"; // Internal type for JSON values that serialize as String
+    ValueType[ValueType["JSON"] = 11] = "JSON";
+    ValueType[ValueType["Checkbox"] = 12] = "Checkbox";
 })(ValueType || (ValueType = {}));
 export var FormulaType;
 (function (FormulaType) {

package/dist/browser/modules/excel/form-control.d.ts

@@ -0,0 +1,157 @@
+import type { Worksheet } from "@excel/worksheet";
+/**
+ * Form Control Checkbox - Legacy checkbox control compatible with Office 2007+ and WPS/LibreOffice
+ *
+ * Unlike the modern In-Cell Checkbox (which only works in Microsoft 365),
+ * Form Control Checkboxes are floating controls that work in virtually all
+ * spreadsheet applications.
+ */
+/** EMU (English Metric Units) to pixels conversion factor at 96 DPI */
+export declare const EMU_PER_PIXEL = 9525;
+/** EMU to points conversion factor */
+export declare const EMU_PER_POINT = 12700;
+/** Anchor position for form control placement */
+export interface FormControlAnchor {
+    /** Column index (0-based) */
+    col: number;
+    /** Column offset in EMUs (1 pixel ≈ 9525 EMUs at 96 DPI) */
+    colOff: number;
+    /** Row index (0-based) */
+    row: number;
+    /** Row offset in EMUs */
+    rowOff: number;
+}
+/** Checkbox state values */
+export type CheckboxState = "Checked" | "Unchecked" | "Mixed";
+/** Options for adding a form control checkbox */
+export interface FormCheckboxOptions {
+    /** Cell reference where the checkbox value (TRUE/FALSE) will be stored */
+    link?: string;
+    /** Initial checked state */
+    checked?: boolean;
+    /** Label text displayed next to the checkbox */
+    text?: string;
+    /** Whether to use flat appearance (no 3D effect) */
+    noThreeD?: boolean;
+    /** Whether to print the checkbox */
+    print?: boolean;
+}
+/** Internal model for form control checkbox */
+export interface FormCheckboxModel {
+    /** Unique shape ID (e.g., 1025, 1026, ...) */
+    shapeId: number;
+    /** Control property ID (rId in relationships) */
+    ctrlPropId: number;
+    /** Top-left anchor */
+    tl: FormControlAnchor;
+    /** Bottom-right anchor */
+    br: FormControlAnchor;
+    /** Cell link (e.g., "$A$1") */
+    link?: string;
+    /** Checked state */
+    checked: CheckboxState;
+    /** Label text */
+    text: string;
+    /** Use flat appearance */
+    noThreeD: boolean;
+    /** Print control */
+    print: boolean;
+}
+/** Range input for form control - can be a cell reference or position object */
+export type FormControlRange = string | {
+    /** Top-left position */
+    tl: {
+        col: number;
+        row: number;
+        colOff?: number;
+        rowOff?: number;
+    } | string;
+    /** Bottom-right position (optional, defaults to reasonable size) */
+    br?: {
+        col: number;
+        row: number;
+        colOff?: number;
+        rowOff?: number;
+    } | string;
+} | {
+    /** Start column (0-based) */
+    startCol: number;
+    /** Start row (0-based) */
+    startRow: number;
+    /** End column (0-based) */
+    endCol: number;
+    /** End row (0-based) */
+    endRow: number;
+    /** Column offset from start in EMUs */
+    startColOff?: number;
+    /** Row offset from start in EMUs */
+    startRowOff?: number;
+    /** Column offset from end in EMUs */
+    endColOff?: number;
+    /** Row offset from end in EMUs */
+    endRowOff?: number;
+};
+declare class FormCheckbox {
+    worksheet: Worksheet;
+    model: FormCheckboxModel;
+    constructor(worksheet: Worksheet, range: FormControlRange, options?: FormCheckboxOptions);
+    /**
+     * Get the checked state
+     */
+    get checked(): boolean;
+    /**
+     * Set the checked state
+     */
+    set checked(value: boolean);
+    /**
+     * Get the linked cell address
+     */
+    get link(): string | undefined;
+    /**
+     * Set the linked cell address
+     */
+    set link(value: string | undefined);
+    /**
+     * Get the label text
+     */
+    get text(): string;
+    /**
+     * Set the label text
+     */
+    set text(value: string);
+    /**
+     * Convert cell reference to absolute format (e.g., "A1" -> "$A$1")
+     */
+    private _toAbsoluteRef;
+    /**
+     * Parse range input into anchor positions
+     */
+    private _parseRange;
+    /**
+     * Convert anchor to VML anchor string format
+     * Format: "fromCol, fromColOff, fromRow, fromRowOff, toCol, toColOff, toRow, toRowOff"
+     * VML uses pixels for offsets
+     */
+    getVmlAnchor(): string;
+    /**
+     * Get VML style string for positioning
+     */
+    getVmlStyle(): string;
+    /**
+     * Get the numeric checked value for VML (0, 1, or 2)
+     */
+    getVmlCheckedValue(): number;
+    /**
+     * Convert anchor to VML anchor string format from model
+     */
+    static getVmlAnchor(model: FormCheckboxModel): string;
+    /**
+     * Get VML style string for positioning from model
+     */
+    static getVmlStyle(model: FormCheckboxModel): string;
+    /**
+     * Get the numeric checked value for VML from model (0, 1, or 2)
+     */
+    static getVmlCheckedValue(model: FormCheckboxModel): number;
+}
+export { FormCheckbox };

package/dist/browser/modules/excel/form-control.js

@@ -0,0 +1,267 @@
+import { colCache } from "./utils/col-cache.js";
+/**
+ * Form Control Checkbox - Legacy checkbox control compatible with Office 2007+ and WPS/LibreOffice
+ *
+ * Unlike the modern In-Cell Checkbox (which only works in Microsoft 365),
+ * Form Control Checkboxes are floating controls that work in virtually all
+ * spreadsheet applications.
+ */
+// ============================================================================
+// Constants (exported for use by xforms)
+// ============================================================================
+/** EMU (English Metric Units) to pixels conversion factor at 96 DPI */
+export const EMU_PER_PIXEL = 9525;
+/** EMU to points conversion factor */
+export const EMU_PER_POINT = 12700;
+/** Default column offset in EMUs (~15 pixels) */
+const DEFAULT_COL_OFF = 142875;
+/** Default row offset in EMUs (~3 pixels) */
+const DEFAULT_ROW_OFF = 28575;
+/** Default end column offset in EMUs (~29 pixels) */
+const DEFAULT_END_COL_OFF = 276225;
+/** Default end row offset in EMUs (~20 pixels) */
+const DEFAULT_END_ROW_OFF = 190500;
+// ============================================================================
+// FormCheckbox Class
+// ============================================================================
+class FormCheckbox {
+    constructor(worksheet, range, options) {
+        this.worksheet = worksheet;
+        // Parse range to get anchors
+        const { tl, br } = this._parseRange(range);
+        // Generate shape ID (starting from 1025)
+        const existingCount = worksheet.formControls?.length || 0;
+        const shapeId = 1025 + existingCount;
+        // Parse link cell reference
+        let link;
+        if (options?.link) {
+            // Ensure absolute reference format
+            link = this._toAbsoluteRef(options.link);
+        }
+        // Note: ctrlPropId is set later in worksheet-xform.ts prepare() for global uniqueness
+        this.model = {
+            shapeId,
+            ctrlPropId: 0, // Placeholder, set during prepare()
+            tl,
+            br,
+            link,
+            checked: options?.checked ? "Checked" : "Unchecked",
+            text: options?.text ?? "",
+            noThreeD: options?.noThreeD ?? true,
+            print: options?.print ?? false
+        };
+    }
+    /**
+     * Get the checked state
+     */
+    get checked() {
+        return this.model.checked === "Checked";
+    }
+    /**
+     * Set the checked state
+     */
+    set checked(value) {
+        this.model.checked = value ? "Checked" : "Unchecked";
+    }
+    /**
+     * Get the linked cell address
+     */
+    get link() {
+        return this.model.link;
+    }
+    /**
+     * Set the linked cell address
+     */
+    set link(value) {
+        this.model.link = value ? this._toAbsoluteRef(value) : undefined;
+    }
+    /**
+     * Get the label text
+     */
+    get text() {
+        return this.model.text;
+    }
+    /**
+     * Set the label text
+     */
+    set text(value) {
+        this.model.text = value;
+    }
+    /**
+     * Convert cell reference to absolute format (e.g., "A1" -> "$A$1")
+     */
+    _toAbsoluteRef(ref) {
+        // If already absolute, return as-is
+        if (ref.includes("$")) {
+            return ref;
+        }
+        // Parse and convert
+        const addr = colCache.decodeAddress(ref);
+        return `$${colCache.n2l(addr.col)}$${addr.row}`;
+    }
+    /**
+     * Parse range input into anchor positions
+     */
+    _parseRange(range) {
+        let tl;
+        let br;
+        if (typeof range === "string") {
+            // Parse cell reference like "B2" or "B2:D3"
+            const decoded = colCache.decode(range);
+            if ("top" in decoded) {
+                // It's a range like "B2:D3"
+                tl = {
+                    col: decoded.left - 1, // Convert to 0-based
+                    colOff: DEFAULT_COL_OFF,
+                    row: decoded.top - 1,
+                    rowOff: DEFAULT_ROW_OFF
+                };
+                br = {
+                    col: decoded.right - 1,
+                    colOff: DEFAULT_END_COL_OFF,
+                    row: decoded.bottom - 1,
+                    rowOff: DEFAULT_END_ROW_OFF
+                };
+            }
+            else {
+                // Single cell reference - create default size checkbox
+                tl = {
+                    col: decoded.col - 1,
+                    colOff: DEFAULT_COL_OFF,
+                    row: decoded.row - 1,
+                    rowOff: DEFAULT_ROW_OFF
+                };
+                // Default size: about 2 columns wide, 1 row tall
+                br = {
+                    col: decoded.col + 1,
+                    colOff: DEFAULT_END_COL_OFF,
+                    row: decoded.row,
+                    rowOff: DEFAULT_END_ROW_OFF
+                };
+            }
+        }
+        else if ("startCol" in range) {
+            // startCol/startRow/endCol/endRow format (0-based)
+            tl = {
+                col: range.startCol,
+                colOff: range.startColOff ?? DEFAULT_COL_OFF,
+                row: range.startRow,
+                rowOff: range.startRowOff ?? DEFAULT_ROW_OFF
+            };
+            br = {
+                col: range.endCol,
+                colOff: range.endColOff ?? DEFAULT_END_COL_OFF,
+                row: range.endRow,
+                rowOff: range.endRowOff ?? DEFAULT_END_ROW_OFF
+            };
+        }
+        else {
+            // Object format with tl/br
+            if (typeof range.tl === "string") {
+                const decoded = colCache.decodeAddress(range.tl);
+                tl = {
+                    col: decoded.col - 1,
+                    colOff: DEFAULT_COL_OFF,
+                    row: decoded.row - 1,
+                    rowOff: DEFAULT_ROW_OFF
+                };
+            }
+            else {
+                tl = {
+                    col: range.tl.col,
+                    colOff: range.tl.colOff ?? DEFAULT_COL_OFF,
+                    row: range.tl.row,
+                    rowOff: range.tl.rowOff ?? DEFAULT_ROW_OFF
+                };
+            }
+            if (range.br) {
+                if (typeof range.br === "string") {
+                    const decoded = colCache.decodeAddress(range.br);
+                    br = {
+                        col: decoded.col - 1,
+                        colOff: DEFAULT_END_COL_OFF,
+                        row: decoded.row - 1,
+                        rowOff: DEFAULT_END_ROW_OFF
+                    };
+                }
+                else {
+                    br = {
+                        col: range.br.col,
+                        colOff: range.br.colOff ?? DEFAULT_END_COL_OFF,
+                        row: range.br.row,
+                        rowOff: range.br.rowOff ?? DEFAULT_END_ROW_OFF
+                    };
+                }
+            }
+            else {
+                // Default size
+                br = {
+                    col: tl.col + 2,
+                    colOff: DEFAULT_END_COL_OFF,
+                    row: tl.row + 1,
+                    rowOff: DEFAULT_END_ROW_OFF
+                };
+            }
+        }
+        return { tl, br };
+    }
+    // =========================================================================
+    // Instance methods - delegate to static methods
+    // =========================================================================
+    /**
+     * Convert anchor to VML anchor string format
+     * Format: "fromCol, fromColOff, fromRow, fromRowOff, toCol, toColOff, toRow, toRowOff"
+     * VML uses pixels for offsets
+     */
+    getVmlAnchor() {
+        return FormCheckbox.getVmlAnchor(this.model);
+    }
+    /**
+     * Get VML style string for positioning
+     */
+    getVmlStyle() {
+        return FormCheckbox.getVmlStyle(this.model);
+    }
+    /**
+     * Get the numeric checked value for VML (0, 1, or 2)
+     */
+    getVmlCheckedValue() {
+        return FormCheckbox.getVmlCheckedValue(this.model);
+    }
+    // =========================================================================
+    // Static utility methods - can be used with FormCheckboxModel directly
+    // =========================================================================
+    /**
+     * Convert anchor to VML anchor string format from model
+     */
+    static getVmlAnchor(model) {
+        const { tl, br } = model;
+        const tlColOff = Math.round(tl.colOff / EMU_PER_PIXEL);
+        const tlRowOff = Math.round(tl.rowOff / EMU_PER_PIXEL);
+        const brColOff = Math.round(br.colOff / EMU_PER_PIXEL);
+        const brRowOff = Math.round(br.rowOff / EMU_PER_PIXEL);
+        return `${tl.col}, ${tlColOff}, ${tl.row}, ${tlRowOff}, ${br.col}, ${brColOff}, ${br.row}, ${brRowOff}`;
+    }
+    /**
+     * Get VML style string for positioning from model
+     */
+    static getVmlStyle(model) {
+        const marginLeft = Math.round(model.tl.colOff / EMU_PER_POINT);
+        const marginTop = Math.round(model.tl.rowOff / EMU_PER_POINT);
+        return `position:absolute;margin-left:${marginLeft}pt;margin-top:${marginTop}pt;width:96pt;height:18pt;z-index:1;visibility:visible`;
+    }
+    /**
+     * Get the numeric checked value for VML from model (0, 1, or 2)
+     */
+    static getVmlCheckedValue(model) {
+        switch (model.checked) {
+            case "Checked":
+                return 1;
+            case "Mixed":
+                return 2;
+            default:
+                return 0;
+        }
+    }
+}
+export { FormCheckbox };

package/dist/browser/modules/excel/stream/workbook-writer.browser.d.ts

@@ -132,6 +132,7 @@ export declare abstract class WorkbookWriterBase<TWorksheetWriter extends Worksh
     addApp(): Promise<void>;
     addCore(): Promise<void>;
     addSharedStrings(): Promise<void>;
+    addFeaturePropertyBag(): Promise<void>;
     addWorkbookRels(): Promise<void>;
     addWorkbook(): Promise<void>;
     _finalize(): Promise<this>;

package/dist/browser/modules/excel/stream/workbook-writer.browser.js

@@ -20,6 +20,7 @@ import { ContentTypesXform } from "../xlsx/xform/core/content-types-xform.js";
 import { AppXform } from "../xlsx/xform/core/app-xform.js";
 import { WorkbookXform } from "../xlsx/xform/book/workbook-xform.js";
 import { SharedStringsXform } from "../xlsx/xform/strings/shared-strings-xform.js";
+import { FeaturePropertyBagXform } from "../xlsx/xform/core/feature-property-bag-xform.js";
 import { theme1Xml } from "../xlsx/xml/theme1.js";
 import { Writeable, stringToUint8Array } from "../../stream/index.browser.js";
 import { mediaPath, OOXML_PATHS, OOXML_REL_TARGETS, worksheetRelTarget } from "../utils/ooxml-paths.js";
@@ -134,6 +135,7 @@ export class WorkbookWriterBase {
             this.addCore(),
             this.addSharedStrings(),
             this.addStyles(),
+            this.addFeaturePropertyBag(),
             this.addWorkbookRels()
         ]);
         await this.addWorkbook();
@@ -226,7 +228,8 @@ export class WorkbookWriterBase {
                 worksheets: this._worksheets.filter(Boolean),
                 sharedStrings: this.sharedStrings,
                 commentRefs: this.commentRefs,
-                media: this.media
+                media: this.media,
+                hasCheckboxes: this.styles.hasCheckboxes
             };
             const xform = new ContentTypesXform();
             this._addFile(xform.toXml(model), OOXML_PATHS.contentTypes);
@@ -280,6 +283,13 @@ export class WorkbookWriterBase {
         }
         return Promise.resolve();
     }
+    addFeaturePropertyBag() {
+        if (this.styles.hasCheckboxes) {
+            const xform = new FeaturePropertyBagXform();
+            this._addFile(xform.toXml({}), OOXML_PATHS.xlFeaturePropertyBag);
+        }
+        return Promise.resolve();
+    }
     addWorkbookRels() {
         let count = 1;
         const relationships = [
@@ -293,6 +303,14 @@ export class WorkbookWriterBase {
                 Target: OOXML_REL_TARGETS.workbookSharedStrings
             });
         }
+        // Add FeaturePropertyBag relationship if checkboxes are used
+        if (this.styles.hasCheckboxes) {
+            relationships.push({
+                Id: `rId${count++}`,
+                Type: RelType.FeaturePropertyBag,
+                Target: OOXML_REL_TARGETS.workbookFeaturePropertyBag
+            });
+        }
         this._worksheets.forEach(ws => {
             if (ws) {
                 ws.rId = `rId${count++}`;

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

@@ -52,8 +52,12 @@ declare class Table {
     set model(value: TableModel);
     cacheState(): void;
     commit(): void;
-    addRow(values: CellValue[], rowNumber?: number): void;
-    removeRows(rowIndex: number, count?: number): void;
+    addRow(values: CellValue[], rowNumber?: number, options?: {
+        commit?: boolean;
+    }): void;
+    removeRows(rowIndex: number, count?: number, options?: {
+        commit?: boolean;
+    }): void;
     getColumn(colIndex: number): Column;
     addColumn(column: TableColumnProperties, values: CellValue[], colIndex?: number): void;
     removeColumns(colIndex: number, count?: number): void;