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

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

@@ -12,9 +12,11 @@ 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";
 export * from "./modules/excel/enums.js";
 export * from "./modules/excel/types.js";
 export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
+export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 import { WorkbookWriter } from "./modules/excel/stream/workbook-writer.browser.js";
 import { WorkbookReader } from "./modules/excel/stream/workbook-reader.browser.js";
 import { WorksheetWriter } from "./modules/excel/stream/worksheet-writer.js";

package/dist/types/index.d.ts

@@ -8,6 +8,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";
 export { WorkbookWriter } from "./modules/excel/stream/workbook-writer.js";
 export { WorkbookReader } from "./modules/excel/stream/workbook-reader.js";
 export { WorksheetWriter } from "./modules/excel/stream/worksheet-writer.js";
@@ -15,6 +16,7 @@ export { WorksheetReader } from "./modules/excel/stream/worksheet-reader.js";
 export * from "./modules/excel/enums.js";
 export * from "./modules/excel/types.js";
 export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
+export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "./modules/excel/stream/workbook-reader.js";
 export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "./modules/excel/stream/worksheet-reader.js";
 export type { WorkbookWriterOptions, ZipOptions, ZlibOptions } from "./modules/excel/stream/workbook-writer.js";

package/dist/types/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/types/modules/excel/form-control.d.ts

@@ -0,0 +1,157 @@
+import type { Worksheet } from "./worksheet.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.
+ */
+/** 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/types/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/types/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;

package/dist/types/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/types/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/types/modules/excel/worksheet.d.ts

@@ -5,6 +5,7 @@ import type { Cell, FormulaResult } from "./cell.js";
 import { Image, type ImageModel } from "./image.js";
 import { Table, type TableModel } from "./table.js";
 import { DataValidations } from "./data-validations.js";
+import { FormCheckbox, type FormCheckboxModel, type FormCheckboxOptions, type FormControlRange } from "./form-control.js";
 import { type PivotTable, type PivotTableModel } from "./pivot-table.js";
 import type { Workbook } from "./workbook.js";
 import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, RowBreak, RowValues, TableProperties, WorksheetProperties, WorksheetView } from "./types.js";
@@ -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/types/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/types/modules/excel/xlsx/xform/core/feature-property-bag-xform.d.ts

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

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

@@ -0,0 +1,22 @@
+import { BaseXform } from "../base-xform.js";
+import type { FormCheckboxModel } from "../../../form-control.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.
+ */
+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/types/modules/excel/xlsx/xform/drawing/vml-drawing-xform.d.ts

@@ -0,0 +1,44 @@
+import { BaseXform } from "../base-xform.js";
+import { type FormCheckboxModel } from "../../../form-control.js";
+/**
+ * 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 };

package/dist/types/modules/excel/xlsx/xform/style/style-xform.d.ts

@@ -9,6 +9,8 @@ interface StyleModel {
     xfId?: number;
     alignment?: any;
     protection?: any;
+    checkbox?: boolean;
+    xfComplementIndex?: number;
 }
 interface StyleOptions {
     xfId?: boolean;

package/dist/types/modules/excel/xlsx/xform/style/styles-xform.d.ts

@@ -11,6 +11,7 @@ interface StylesModel {
 declare class StylesXform extends BaseXform {
     private index?;
     private weakMap?;
+    private _hasCheckboxes?;
     parser: any;
     static Mock: typeof StylesXform;
     constructor(initialise?: boolean);
@@ -24,6 +25,7 @@ declare class StylesXform extends BaseXform {
     getStyleModel(id: number): any;
     addDxfStyle(style: any): number;
     getDxfStyle(id: number): any;
+    get hasCheckboxes(): boolean;
     _addStyle(style: any): number;
     _addNumFmtStr(formatCode: string): number;
     _addFont(font: any): number;

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

@@ -92,6 +92,8 @@ declare class XLSX {
         PivotCacheDefinition: string;
         PivotCacheRecords: string;
         PivotTable: string;
+        FeaturePropertyBag: string;
+        CtrlProp: string;
     };
     constructor(workbook: Workbook);
     /**
@@ -195,6 +197,7 @@ declare class XLSX {
     addThemes(zip: IZipWriter, model: any): Promise<void>;
     addOfficeRels(zip: IZipWriter, _model: any): Promise<void>;
     addWorkbookRels(zip: IZipWriter, model: any): Promise<void>;
+    addFeaturePropertyBag(zip: IZipWriter, model: any): Promise<void>;
     addSharedStrings(zip: IZipWriter, model: any): Promise<void>;
     addStyles(zip: IZipWriter, model: any): Promise<void>;
     addWorkbook(zip: IZipWriter, model: any): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "4.0.4",
+  "version": "4.1.0-canary.20260110032830.e7d8c4e",
   "description": "TypeScript Excel Workbook Manager - Read and Write xlsx and csv Files.",
   "type": "module",
   "publishConfig": {
@@ -87,9 +87,9 @@
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^25.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.51.0",
-    "@typescript-eslint/parser": "^8.51.0",
-    "@typescript/native-preview": "^7.0.0-dev.20260101.1",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260108.1",
     "@vitest/browser": "^4.0.16",
     "@vitest/browser-playwright": "^4.0.16",
     "@vitest/ui": "^4.0.16",
@@ -99,17 +99,17 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import-x": "^4.16.1",
-    "eslint-plugin-oxlint": "^1.36.0",
+    "eslint-plugin-oxlint": "^1.38.0",
     "eslint-plugin-unused-imports": "^4.3.0",
     "husky": "^9.1.7",
-    "oxlint": "^1.36.0",
+    "oxlint": "^1.38.0",
     "playwright": "^1.57.0",
     "prettier": "^3.7.4",
     "rimraf": "^6.1.2",
-    "rolldown": "^1.0.0-beta.58",
+    "rolldown": "^1.0.0-beta.59",
     "rollup-plugin-visualizer": "^6.0.5",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.51.0",
+    "typescript-eslint": "^8.52.0",
     "vite-tsconfig-paths": "^6.0.3",
     "vitest": "^4.0.16"
   },
@@ -120,7 +120,7 @@
     "test:browser": "rimraf dist && npm run build:browser:bundle && vitest run --config vitest.browser.config.ts",
     "test:watch": "vitest",
     "build": "rimraf dist && concurrently \"npm run build:esm\" \"npm run build:cjs\" \"npm run build:browser\" \"npm run build:browser:bundle\" && npm run build:verify",
-    "build:verify": "node scripts/check-dist-esm-specifiers.mjs --dir dist/esm && node scripts/check-dist-esm-specifiers.mjs --dir dist/browser && tsc --noEmit --module NodeNext --moduleResolution NodeNext dist/types/index.d.ts",
+    "build:verify": "tsc --noEmit --module NodeNext --moduleResolution NodeNext dist/types/index.d.ts",
     "analyze:browser": "rimraf dist && node --input-type=module -e \"import { execSync } from 'node:child_process'; process.env.ANALYZE='true'; execSync('rolldown -c rolldown.config.ts', { stdio: 'inherit' });\"",
     "clean": "pnpm dlx --reporter=silent rimraf \"**/node_modules\" pnpm-lock.yaml \"**/dist\" -g && pnpm i",
     "lint": "eslint && oxlint",