@cj-tech-master/excelts 4.1.0 → 4.2.0-canary.20260110034516.0919d4d

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/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/utils/ooxml-paths.d.ts

@@ -64,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

@@ -16,5 +16,6 @@ declare const RelType: {
     PivotCacheRecords: string;
     PivotTable: string;
     FeaturePropertyBag: string;
+    CtrlProp: string;
 };
 export { RelType };

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/xlsx.browser.d.ts

@@ -93,6 +93,7 @@ declare class XLSX {
         PivotCacheRecords: string;
         PivotTable: string;
         FeaturePropertyBag: string;
+        CtrlProp: string;
     };
     constructor(workbook: Workbook);
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "4.1.0",
+  "version": "4.2.0-canary.20260110034516.0919d4d",
   "description": "TypeScript Excel Workbook Manager - Read and Write xlsx and csv Files.",
   "type": "module",
   "publishConfig": {
@@ -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",