handsontable 17.1.0 → 18.0.0-rc2

package/plugins/exportFile/types/xlsx.d.ts

@@ -0,0 +1,120 @@
+import BaseType from './_base';
+/**
+ * A cell value that ExcelJS accepts: a primitive, a formula object, or null.
+ */
+type ExcelCellValue = string | number | boolean | null | undefined | {
+    formula: string;
+    result?: string | number | boolean | null;
+} | {
+    sharedFormula: string;
+    result?: string | number | boolean | null;
+};
+interface ExcelJsCell {
+    value: ExcelCellValue;
+    numFmt: string;
+    alignment: object;
+    border: object;
+    font: object;
+    fill: object;
+    protection: {
+        locked: boolean;
+    };
+    dataValidation: object;
+    note: string;
+}
+interface ExcelJsRow {
+    getCell(colNumber: number): ExcelJsCell;
+    height: number;
+    hidden: boolean;
+    commit(): void;
+}
+interface ExcelJsColumn {
+    width: number;
+    hidden: boolean;
+}
+interface ExcelJsView {
+    rightToLeft?: boolean;
+    state?: string;
+    xSplit?: number;
+    ySplit?: number;
+}
+interface ExcelJsWorksheet {
+    getRow(rowNumber: number): ExcelJsRow;
+    getColumn(colNumber: number): ExcelJsColumn;
+    getCell(rowNumber: number, colNumber: number): ExcelJsCell;
+    mergeCells(startRow: number, startCol: number, endRow: number, endCol: number): void;
+    addConditionalFormatting(descriptor: {
+        ref: string;
+        rules: unknown[];
+    }): void;
+    protect(password: string, options?: Record<string, boolean>): void;
+    state: string;
+    views: ExcelJsView[];
+}
+interface ExcelJsWorkbook {
+    addWorksheet(name: string): ExcelJsWorksheet;
+    worksheets: Array<{
+        name: string;
+    }>;
+    xlsx: {
+        writeBuffer(options?: object): Promise<Uint8Array>;
+    };
+}
+/**
+ * One entry in the `conditionalFormatting` option array.
+ */
+interface ConditionalFormattingDescriptor {
+    rows?: [number, number];
+    cols?: [number, number];
+    rules: unknown[];
+}
+interface XlsxEngine {
+    Workbook: new () => ExcelJsWorkbook;
+}
+/**
+ * @private
+ */
+declare class Xlsx extends BaseType {
+    #private;
+    /**
+     * Marks this formatter as binary (non-stringifiable).
+     *
+     * @returns {boolean}
+     */
+    static get BINARY(): boolean;
+    /**
+     * Returns true to indicate that XLSX data should be treated as binary output.
+     */
+    get binary(): boolean;
+    /**
+     * Default options for exporting XLSX format.
+     *
+     * @returns {object}
+     */
+    static get DEFAULT_OPTIONS(): {
+        mimeType: string;
+        fileExtension: string;
+        bom: boolean;
+        engine: XlsxEngine | null;
+        compression: boolean | number | null;
+        conditionalFormatting: ConditionalFormattingDescriptor[];
+        exportFormulas: boolean;
+        headerStyle: {
+            backgroundColor: string;
+            border: {
+                style: string;
+            };
+        } | null;
+    };
+    /**
+     * Builds an XLSX workbook and returns its binary buffer.
+     *
+     * When the `sheets` option is provided the workbook contains one worksheet per entry,
+     * each driven by its own Handsontable instance. Otherwise a single worksheet named
+     * `'Sheet1'` is produced from the primary DataProvider.
+     *
+     * @returns {Promise<Uint8Array>}
+     */
+    export(): Promise<Uint8Array>;
+}
+export default Xlsx;

package/plugins/exportFile/types/xlsx.js

@@ -249,7 +249,9 @@ var /**
    */ static get BINARY() {
         return true;
     }
-    get binary() {
+    /**
+   * Returns true to indicate that XLSX data should be treated as binary output.
+   */ get binary() {
         return true;
     }
     /**
@@ -289,14 +291,14 @@ var /**
    *
    * @returns {Promise<Uint8Array>}
    */ async export() {
-        const { engine } = this.options;
+        const engine = this.options.engine;
         if (!engine || typeof engine.Workbook !== 'function') {
             (0, _errors.throwWithCause)('Missing or invalid ExcelJS engine. Pass the ExcelJS module via the `engines` option ' + 'in the exportFile plugin settings: `exportFile: { engines: { xlsx: ExcelJS } }`.');
         }
         // Clear style caches for all documents involved in this export. In multi-sheet
         // mode each sheet may come from a different Handsontable instance living in a
         // different document (e.g. an iframe), so every distinct document must be cleared.
-        const { sheets } = this.options;
+        const sheets = this.options.sheets;
         const docsToClear = sheets && sheets.length > 0 ? new Set(sheets.map((s)=>s.instance.rootDocument)) : new Set([
             this.dataProvider.hot.rootDocument
         ]);
@@ -357,13 +359,14 @@ function populateWorksheet(workbook, worksheet, dataProvider, options) {
     const frozenColumns = dataProvider.getFrozenColumns();
     const nestedColumnHeaders = dataProvider.getNestedColumnHeaders();
     const isRtl = dataProvider.getLayoutDirection() === 'rtl';
-    const { exportFormulas } = options;
+    const exportFormulas = options.exportFormulas ?? false;
     // Build a fast O(1) lookup: "dataRowIndex:dataColIndex" → summary descriptor.
     // Always built so the protection pre-scan can identify ColumnSummary destination
     // cells; the formula-writing path also uses this map when exportFormulas is true.
     const summaryMap = new Map();
     const columnSummaries = dataProvider.getColumnSummaries();
-    columnSummaries.forEach((summary)=>{
+    columnSummaries.forEach((summaryRaw)=>{
+        const summary = summaryRaw;
         summaryMap.set(`${summary.destRow}:${summary.destCol}`, summary);
     });
     const sourceData = exportFormulas ? dataProvider.getSourceData() : null;
@@ -409,7 +412,7 @@ function populateWorksheet(workbook, worksheet, dataProvider, options) {
     //    initialise font/fill/border to sentinel values, which adds noise to the file
     //    and breaks styling assertions in tests.
     const hasColumnSummary = summaryMap.size > 0;
-    const hasReadOnlyCells = !hasColumnSummary && cellsMeta.some((row)=>row.some((meta)=>meta.readOnly === true));
+    const hasReadOnlyCells = !hasColumnSummary && cellsMeta.some((row)=>row.some((meta)=>meta?.readOnly === true));
     const context = {
         exportFormulas,
         formulasSeparator,
@@ -547,7 +550,7 @@ function resolveCellValue(cellValue, meta, sourceValue, summary, context) {
     if (exportFormulas && (0, _formulautils.isFormulaValue)(sourceValue)) {
         return {
             value: {
-                formula: (0, _formulautils.normalizeFormula)(sourceValue, formulasSeparator, dataRowOffset - 1, dataColOffset - 1, excludedHiddenRows, excludedHiddenCols)
+                formula: (0, _formulautils.normalizeFormula)(sourceValue, formulasSeparator, dataRowOffset - 1, dataColOffset - 1, excludedHiddenRows ?? undefined, excludedHiddenCols ?? undefined)
             },
             numFmt: null
         };
@@ -617,7 +620,7 @@ function getMultiSelectExportValue(value) {
     if (value.length === 0) {
         return null;
     }
-    return value.map((item)=>item !== null && typeof item === 'object' ? item.value : item).join(', ');
+    return value.map((item)=>item !== null && typeof item === 'object' ? String(item.value) : String(item)).join(', ');
 }
 function buildHeaderFill(headerStyle) {
     if (!headerStyle?.backgroundColor) {
@@ -841,7 +844,7 @@ function buildValidationSheet(workbook, cellsMeta) {
             validationSheet.getCell(rowNumber + 1, colNumber).value = (0, _object.isKeyValueObject)(item) ? String(item.value) : String(item);
         }
         const colLetter = (0, _formulautils.colIndexToLetter)(colNumber);
-        const escapedName = sheetName.replace(/'/g, '\'\'');
+        const escapedName = sheetName.replaceAll('\'', '\'\'');
         const rangeRef = `'${escapedName}'!$${colLetter}$1:$${colLetter}$${source.length}`;
         validationMap.set(key, rangeRef);
         colNumber += 1;

package/plugins/exportFile/types/xlsx.mjs

@@ -234,7 +234,9 @@ var /**
    */ static get BINARY() {
         return true;
     }
-    get binary() {
+    /**
+   * Returns true to indicate that XLSX data should be treated as binary output.
+   */ get binary() {
         return true;
     }
     /**
@@ -274,14 +276,14 @@ var /**
    *
    * @returns {Promise<Uint8Array>}
    */ async export() {
-        const { engine } = this.options;
+        const engine = this.options.engine;
         if (!engine || typeof engine.Workbook !== 'function') {
             throwWithCause('Missing or invalid ExcelJS engine. Pass the ExcelJS module via the `engines` option ' + 'in the exportFile plugin settings: `exportFile: { engines: { xlsx: ExcelJS } }`.');
         }
         // Clear style caches for all documents involved in this export. In multi-sheet
         // mode each sheet may come from a different Handsontable instance living in a
         // different document (e.g. an iframe), so every distinct document must be cleared.
-        const { sheets } = this.options;
+        const sheets = this.options.sheets;
         const docsToClear = sheets && sheets.length > 0 ? new Set(sheets.map((s)=>s.instance.rootDocument)) : new Set([
             this.dataProvider.hot.rootDocument
         ]);
@@ -342,13 +344,14 @@ function populateWorksheet(workbook, worksheet, dataProvider, options) {
     const frozenColumns = dataProvider.getFrozenColumns();
     const nestedColumnHeaders = dataProvider.getNestedColumnHeaders();
     const isRtl = dataProvider.getLayoutDirection() === 'rtl';
-    const { exportFormulas } = options;
+    const exportFormulas = options.exportFormulas ?? false;
     // Build a fast O(1) lookup: "dataRowIndex:dataColIndex" → summary descriptor.
     // Always built so the protection pre-scan can identify ColumnSummary destination
     // cells; the formula-writing path also uses this map when exportFormulas is true.
     const summaryMap = new Map();
     const columnSummaries = dataProvider.getColumnSummaries();
-    columnSummaries.forEach((summary)=>{
+    columnSummaries.forEach((summaryRaw)=>{
+        const summary = summaryRaw;
         summaryMap.set(`${summary.destRow}:${summary.destCol}`, summary);
     });
     const sourceData = exportFormulas ? dataProvider.getSourceData() : null;
@@ -394,7 +397,7 @@ function populateWorksheet(workbook, worksheet, dataProvider, options) {
     //    initialise font/fill/border to sentinel values, which adds noise to the file
     //    and breaks styling assertions in tests.
     const hasColumnSummary = summaryMap.size > 0;
-    const hasReadOnlyCells = !hasColumnSummary && cellsMeta.some((row)=>row.some((meta)=>meta.readOnly === true));
+    const hasReadOnlyCells = !hasColumnSummary && cellsMeta.some((row)=>row.some((meta)=>meta?.readOnly === true));
     const context = {
         exportFormulas,
         formulasSeparator,
@@ -532,7 +535,7 @@ function resolveCellValue(cellValue, meta, sourceValue, summary, context) {
     if (exportFormulas && isFormulaValue(sourceValue)) {
         return {
             value: {
-                formula: normalizeFormula(sourceValue, formulasSeparator, dataRowOffset - 1, dataColOffset - 1, excludedHiddenRows, excludedHiddenCols)
+                formula: normalizeFormula(sourceValue, formulasSeparator, dataRowOffset - 1, dataColOffset - 1, excludedHiddenRows ?? undefined, excludedHiddenCols ?? undefined)
             },
             numFmt: null
         };
@@ -602,7 +605,7 @@ function getMultiSelectExportValue(value) {
     if (value.length === 0) {
         return null;
     }
-    return value.map((item)=>item !== null && typeof item === 'object' ? item.value : item).join(', ');
+    return value.map((item)=>item !== null && typeof item === 'object' ? String(item.value) : String(item)).join(', ');
 }
 function buildHeaderFill(headerStyle) {
     if (!headerStyle?.backgroundColor) {
@@ -826,7 +829,7 @@ function buildValidationSheet(workbook, cellsMeta) {
             validationSheet.getCell(rowNumber + 1, colNumber).value = isKeyValueObject(item) ? String(item.value) : String(item);
         }
         const colLetter = colIndexToLetter(colNumber);
-        const escapedName = sheetName.replace(/'/g, '\'\'');
+        const escapedName = sheetName.replaceAll('\'', '\'\'');
         const rangeRef = `'${escapedName}'!$${colLetter}$1:$${colLetter}$${source.length}`;
         validationMap.set(key, rangeRef);
         colNumber += 1;

package/plugins/exportFile/utils.d.mts

@@ -0,0 +1 @@
+export * from './utils.js';

package/plugins/exportFile/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Builds the dialog overlay DOM fragment for the export progress indicator.
+ *
+ * The title text is resolved at call-time so it reflects the active locale.
+ *
+ * @param {string} title Translated title string (e.g. "Exporting…").
+ * @returns {DocumentFragment}
+ */
+export declare function buildExportDialogContent(title: string): DocumentFragment;

package/plugins/filters/component/_base.d.mts

@@ -0,0 +1 @@
+export * from './_base.js';

package/plugins/filters/component/_base.d.ts

@@ -0,0 +1,115 @@
+import type { HotInstance } from '../../../core/types';
+import { LinkedPhysicalIndexToValueMap as IndexToValueMap } from '../../../translations';
+/**
+ * @private
+ * @class BaseComponent
+ */
+export declare class BaseComponent {
+    /**
+     * The Handsontable instance.
+     *
+     * @type {Core}
+     */
+    hot: HotInstance | null;
+    /**
+     * The component uniq id.
+     *
+     * @type {string}
+     */
+    id: string;
+    /**
+     * List of registered component UI elements.
+     *
+     * @type {Array}
+     */
+    elements: unknown[];
+    /**
+     * Flag which determines if element is hidden.
+     *
+     * @type {boolean}
+     */
+    hidden: boolean;
+    /**
+     * The component states id.
+     *
+     * @type {string}
+     */
+    stateId: string;
+    /**
+     * Index map which stores component states for each column.
+     *
+     * @type {LinkedPhysicalIndexToValueMap|null}
+     */
+    state: IndexToValueMap | null;
+    /**
+     * Initializes the filter component with a Handsontable instance, assigns the component ID, and optionally registers a column index map for stateful components.
+     */
+    constructor(hotInstance: HotInstance, { id, stateless }: {
+        id: string;
+        stateless?: boolean;
+    });
+    /**
+     * Gets the list of elements from which the component is built.
+     *
+     * @returns {BaseUI[]}
+     */
+    getElements(): unknown[];
+    /**
+     * Reset elements to its initial state.
+     */
+    reset(): void;
+    /**
+     * Hide component.
+     */
+    hide(): void;
+    /**
+     * Show component.
+     */
+    show(): void;
+    /**
+     * Check if component is hidden.
+     *
+     * @returns {boolean}
+     */
+    isHidden(): boolean;
+    /**
+     * Restores the component state from the given physical column index. The method
+     * internally calls the `setState` method. The state then is individually processed
+     * by each component.
+     *
+     * @param {number} physicalColumn The physical column index.
+     */
+    restoreState(physicalColumn: number): void;
+    /**
+     * The custom logic for component state restoring.
+     */
+    setState(_value?: unknown): void;
+    /**
+     * Saves the component state to the given physical column index. The method
+     * internally calls the `getState` method, which returns the current state of
+     * the component.
+     *
+     * @param {number} physicalColumn The physical column index.
+     */
+    saveState(physicalColumn: number): void;
+    /**
+     * The custom logic for component state gathering (for stateful components).
+     */
+    getState(): Record<string, unknown> | string;
+    /**
+     * Returns the menu item descriptor for this component (used to add it to the dropdown menu).
+     *
+     * @returns {object}
+     */
+    getMenuItemDescriptor(): Record<string, unknown>;
+    /**
+     * Destroy element.
+     */
+    destroy(): void;
+}
+export interface BaseComponent {
+    addLocalHook(key: string, callback: Function): this;
+    removeLocalHook(key: string, callback: Function): this;
+    runLocalHooks(key: string, ...args: unknown[]): void;
+    clearLocalHooks(): this;
+}

package/plugins/filters/component/_base.js

@@ -61,7 +61,7 @@ class BaseComponent {
     }
     /**
    * The custom logic for component state restoring.
-   */ setState() {
+   */ setState(_value) {
         (0, _errors.throwWithCause)('The state setting logic is not implemented');
     }
     /**
@@ -79,18 +79,29 @@ class BaseComponent {
    * The custom logic for component state gathering (for stateful components).
    */ getState() {
         (0, _errors.throwWithCause)('The state gathering logic is not implemented');
+        return {};
+    }
+    /**
+   * Returns the menu item descriptor for this component (used to add it to the dropdown menu).
+   *
+   * @returns {object}
+   */ getMenuItemDescriptor() {
+        (0, _errors.throwWithCause)('The menu item descriptor logic is not implemented');
+        return {};
     }
     /**
    * Destroy element.
    */ destroy() {
-        this.hot.columnIndexMapper.unregisterMap(this.stateId);
+        this.hot?.columnIndexMapper.unregisterMap(this.stateId);
         this.clearLocalHooks();
         (0, _array.arrayEach)(this.elements, (ui)=>ui.destroy());
         this.state = null;
-        this.elements = null;
+        this.elements.length = 0;
         this.hot = null;
     }
-    constructor(hotInstance, { id, stateless = true }){
+    /**
+   * Initializes the filter component with a Handsontable instance, assigns the component ID, and optionally registers a column index map for stateful components.
+   */ constructor(hotInstance, { id, stateless = true }){
         /**
    * List of registered component UI elements.
    *

package/plugins/filters/component/_base.mjs

@@ -49,7 +49,7 @@ import { LinkedPhysicalIndexToValueMap as IndexToValueMap } from '../../../trans
     }
     /**
    * The custom logic for component state restoring.
-   */ setState() {
+   */ setState(_value) {
         throwWithCause('The state setting logic is not implemented');
     }
     /**
@@ -67,18 +67,29 @@ import { LinkedPhysicalIndexToValueMap as IndexToValueMap } from '../../../trans
    * The custom logic for component state gathering (for stateful components).
    */ getState() {
         throwWithCause('The state gathering logic is not implemented');
+        return {};
+    }
+    /**
+   * Returns the menu item descriptor for this component (used to add it to the dropdown menu).
+   *
+   * @returns {object}
+   */ getMenuItemDescriptor() {
+        throwWithCause('The menu item descriptor logic is not implemented');
+        return {};
     }
     /**
    * Destroy element.
    */ destroy() {
-        this.hot.columnIndexMapper.unregisterMap(this.stateId);
+        this.hot?.columnIndexMapper.unregisterMap(this.stateId);
         this.clearLocalHooks();
         arrayEach(this.elements, (ui)=>ui.destroy());
         this.state = null;
-        this.elements = null;
+        this.elements.length = 0;
         this.hot = null;
     }
-    constructor(hotInstance, { id, stateless = true }){
+    /**
+   * Initializes the filter component with a Handsontable instance, assigns the component ID, and optionally registers a column index map for stateful components.
+   */ constructor(hotInstance, { id, stateless = true }){
         /**
    * List of registered component UI elements.
    *

package/plugins/filters/component/actionBar.d.mts

@@ -0,0 +1 @@
+export * from './actionBar.js';

package/plugins/filters/component/actionBar.d.ts

@@ -0,0 +1,57 @@
+import type { HotInstance } from '../../../core/types';
+import { BaseComponent } from './_base';
+/**
+ * @private
+ * @class ActionBarComponent
+ */
+export declare class ActionBarComponent extends BaseComponent {
+    #private;
+    /**
+     * The name of the component.
+     *
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Returns the identifier string for the OK action button.
+     */
+    static get BUTTON_OK(): string;
+    /**
+     * Returns the identifier string for the Cancel action button.
+     */
+    static get BUTTON_CANCEL(): string;
+    /**
+     * Initializes the action bar component with OK and Cancel buttons.
+     */
+    constructor(hotInstance: HotInstance, options: {
+        id: string;
+        name: string;
+    });
+    /**
+     * Register all necessary hooks.
+     *
+     * @private
+     */
+    registerHooks(): void;
+    /**
+     * Get menu object descriptor.
+     *
+     * @returns {object}
+     */
+    getMenuItemDescriptor(): {
+        key: string;
+        name: string;
+        isCommand: boolean;
+        disableSelection: boolean;
+        hidden: () => boolean;
+        renderer: (hot: HotInstance, wrapper: HTMLElement) => HTMLElement;
+    };
+    /**
+     * Fire accept event.
+     */
+    accept(): void;
+    /**
+     * Fire cancel event.
+     */
+    cancel(): void;
+}

package/plugins/filters/component/actionBar.js

@@ -76,10 +76,14 @@ var /**
    * @param {InputUI} button InputUI object.
    */ _onButtonClick = /*#__PURE__*/ new WeakSet();
 class ActionBarComponent extends _base.BaseComponent {
-    static get BUTTON_OK() {
+    /**
+   * Returns the identifier string for the OK action button.
+   */ static get BUTTON_OK() {
         return 'ok';
     }
-    static get BUTTON_CANCEL() {
+    /**
+   * Returns the identifier string for the Cancel action button.
+   */ static get BUTTON_CANCEL() {
         return 'cancel';
     }
     /**
@@ -103,8 +107,15 @@ class ActionBarComponent extends _base.BaseComponent {
             disableSelection: true,
             hidden: ()=>this.isHidden(),
             renderer: (hot, wrapper)=>{
-                (0, _element.addClass)(wrapper.parentNode, 'htFiltersMenuActionBar');
-                (0, _array.arrayEach)(this.elements, (ui)=>wrapper.appendChild(ui.element));
+                if ((0, _element.isHTMLElement)(wrapper.parentNode)) {
+                    (0, _element.addClass)(wrapper.parentNode, 'htFiltersMenuActionBar');
+                }
+                (0, _array.arrayEach)(this.elements, (ui)=>{
+                    const el = ui.element;
+                    if (el) {
+                        wrapper.appendChild(el);
+                    }
+                });
                 return wrapper;
             }
         };
@@ -119,7 +130,9 @@ class ActionBarComponent extends _base.BaseComponent {
    */ cancel() {
         this.runLocalHooks('cancel');
     }
-    constructor(hotInstance, options){
+    /**
+   * Initializes the action bar component with OK and Cancel buttons.
+   */ constructor(hotInstance, options){
         super(hotInstance, {
             id: options.id,
             stateless: true
@@ -129,13 +142,13 @@ class ActionBarComponent extends _base.BaseComponent {
    * @type {string}
    */ this.name = '';
         this.name = options.name;
-        this.elements.push(new _input.InputUI(this.hot, {
+        this.elements.push(new _input.InputUI(hotInstance, {
             type: 'button',
             value: _constants.FILTERS_BUTTONS_OK,
             className: 'htUIButton htUIButtonOK',
             identifier: ActionBarComponent.BUTTON_OK
         }));
-        this.elements.push(new _input.InputUI(this.hot, {
+        this.elements.push(new _input.InputUI(hotInstance, {
             type: 'button',
             value: _constants.FILTERS_BUTTONS_CANCEL,
             className: 'htUIButton htUIButtonCancel',