handsontable 17.1.0 → 18.0.0-rc2

package/plugins/mergeCells/calculations/autofill.mjs

@@ -108,7 +108,7 @@ import { arrayEach } from '../../../helpers/array.mjs';
    * @param {Array} baseArea The base selection area.
    * @param {Array} fullArea The drag area (containing the base area).
    * @param {string} direction The drag direction.
-   * @returns {number|null} The "length" (height or width, depending on the direction) of the drag.
+   * @returns {number} The "length" (height or width, depending on the direction) of the drag.
    */ getAutofillSize(baseArea, fullArea, direction) {
         const [baseAreaStartRow, baseAreaStartColumn, baseAreaEndRow, baseAreaEndColumn] = baseArea;
         const [dragAreaStartRow, dragAreaStartColumn, dragAreaEndRow, dragAreaEndColumn] = fullArea;
@@ -122,7 +122,7 @@ import { arrayEach } from '../../../helpers/array.mjs';
             case 'right':
                 return dragAreaEndColumn - baseAreaEndColumn;
             default:
-                return null;
+                return 0;
         }
     }
     /**
@@ -132,7 +132,7 @@ import { arrayEach } from '../../../helpers/array.mjs';
    * @param {Array} baseArea The base selection area.
    * @param {Array} fullArea The base selection area extended by the drag area.
    * @param {string} direction Drag direction.
-   * @returns {Array|null} Array representing the drag area coordinates.
+   * @returns {Array} Array representing the drag area coordinates.
    */ getDragArea(baseArea, fullArea, direction) {
         const [baseAreaStartRow, baseAreaStartColumn, baseAreaEndRow, baseAreaEndColumn] = baseArea;
         const [fullAreaStartRow, fullAreaStartColumn, fullAreaEndRow, fullAreaEndColumn] = fullArea;
@@ -174,7 +174,12 @@ import { arrayEach } from '../../../helpers/array.mjs';
                     ];
                 }
             default:
-                return null;
+                return [
+                    0,
+                    0,
+                    0,
+                    0
+                ];
         }
     }
     /**
@@ -221,8 +226,9 @@ import { arrayEach } from '../../../helpers/array.mjs';
             default:
         }
         arrayEach(mergedCellArray, (currentCollection)=>{
-            if (currentCollection[inclusionFunctionName](endOfDragRecreationIndex) && currentCollection.isFarther(farthestCollection, direction)) {
-                farthestCollection = currentCollection;
+            const mc = currentCollection;
+            if (mc[inclusionFunctionName](endOfDragRecreationIndex) && mc.isFarther(farthestCollection, direction)) {
+                farthestCollection = mc;
             }
         });
         return farthestCollection;
@@ -300,7 +306,7 @@ import { arrayEach } from '../../../helpers/array.mjs';
                     multiplier += 1;
                 }
             }
-        }while (inBounds(current, fillOffset))
+        }while (current !== null && inBounds(current, fillOffset))
         this.currentFillData = null;
         this.plugin.hot.render();
         if (foundMergedCells.length > 0) {
@@ -314,38 +320,35 @@ import { arrayEach } from '../../../helpers/array.mjs';
    * @param {Array} changes The changes made.
    * @returns {object} Object with `from` and `to` properties, both containing `row` and `column` keys.
    */ getRangeFromChanges(changes) {
-        const rows = {
-            min: null,
-            max: null
-        };
-        const columns = {
-            min: null,
-            max: null
-        };
+        let rowMin = null;
+        let rowMax = null;
+        let colMin = null;
+        let colMax = null;
         arrayEach(changes, (change)=>{
-            const rowIndex = change[0];
-            const columnIndex = this.plugin.hot.propToCol(change[1]);
-            if (rows.min === null || rowIndex < rows.min) {
-                rows.min = rowIndex;
+            const changeArr = change;
+            const rowIndex = changeArr[0];
+            const columnIndex = this.plugin.hot.propToCol(changeArr[1]);
+            if (rowMin === null || rowIndex < rowMin) {
+                rowMin = rowIndex;
             }
-            if (rows.max === null || rowIndex > rows.max) {
-                rows.max = rowIndex;
+            if (rowMax === null || rowIndex > rowMax) {
+                rowMax = rowIndex;
             }
-            if (columns.min === null || columnIndex < columns.min) {
-                columns.min = columnIndex;
+            if (colMin === null || columnIndex < colMin) {
+                colMin = columnIndex;
             }
-            if (columns.max === null || columnIndex > columns.max) {
-                columns.max = columnIndex;
+            if (colMax === null || columnIndex > colMax) {
+                colMax = columnIndex;
             }
         });
         return {
             from: {
-                row: rows.min,
-                column: columns.min
+                row: rowMin ?? 0,
+                column: colMin ?? 0
             },
             to: {
-                row: rows.max,
-                column: columns.max
+                row: rowMax ?? 0,
+                column: colMax ?? 0
             }
         };
     }
@@ -375,7 +378,9 @@ import { arrayEach } from '../../../helpers/array.mjs';
         }
         return !mergedCellsWithoutPartials.every(({ rowspan })=>rowspan === dragRange.getHeight());
     }
-    constructor(plugin){
+    /**
+   * Initializes the autofill calculations helper with a reference to the MergeCells plugin and its merged cells collection.
+   */ constructor(plugin){
         /**
    * Cache of the currently processed autofill data.
    *

package/plugins/mergeCells/calculations/selection.d.mts

@@ -0,0 +1,2 @@
+export * from './selection.js';
+export { default } from './selection.js';

package/plugins/mergeCells/calculations/selection.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Class responsible for all of the Selection-related operations on merged cells.
+ *
+ * @private
+ * @class SelectionCalculations
+ */
+import type { HotInstance } from '../../../core/types';
+import type { default as CellRange } from '../../../3rdparty/walkontable/src/cell/range';
+import type MergedCellCoords from '../cellCoords';
+import type MergedCellsCollection from '../cellsCollection';
+/**
+ * Minimal interface that SelectionCalculations requires from the MergeCells plugin.
+ */
+interface MergeCellsPluginRef {
+    hot: HotInstance;
+    mergedCellsCollection: MergedCellsCollection;
+}
+/**
+ * Handles all selection-related calculations for merged cells, such as class name generation and full-selection detection.
+ */
+declare class SelectionCalculations {
+    /**
+     * Reference to the Merge Cells plugin.
+     *
+     * @type {MergeCells}
+     */
+    plugin: MergeCellsPluginRef;
+    /**
+     * Reference to the Handsontable instance.
+     *
+     * @type {Handsontable}
+     */
+    hot: HotInstance;
+    /**
+     * Class name used for fully selected merged cells.
+     *
+     * @type {string}
+     */
+    fullySelectedMergedCellClassName: string;
+    /**
+     * Initializes the selection calculations helper with a reference to the MergeCells plugin instance.
+     */
+    constructor(plugin: MergeCellsPluginRef);
+    /**
+     * Generate an additional class name for the entirely-selected merged cells.
+     *
+     * @param {number} currentRow Visual row index of the currently processed cell.
+     * @param {number} currentColumn Visual column index of the currently cell.
+     * @param {Array} cornersOfSelection Array of the current selection in a form of `[startRow, startColumn, endRow, endColumn]`.
+     * @param {number|undefined} layerLevel Number indicating which layer of selection is currently processed.
+     * @returns {string|undefined} A `String`, which will act as an additional `className` to be added to the currently processed cell.
+     */
+    getSelectedMergedCellClassName(currentRow: number, currentColumn: number, cornersOfSelection: number[], layerLevel: number | undefined): string | undefined;
+    /**
+     * Check if the provided merged cell is fully selected (by one or many layers of selection).
+     *
+     * @param {MergedCellCoords} mergedCell The merged cell to be processed.
+     * @param {CellRange[]} selectionRangesArray Array of selection ranges.
+     * @returns {boolean}
+     */
+    isMergeCellFullySelected(mergedCell: MergedCellCoords, selectionRangesArray: CellRange[]): boolean;
+    /**
+     * Generate an array of the entirely-selected merged cells' class names.
+     *
+     * @returns {string[]} An `Array` of `String`s. Each of these strings will act like class names to be removed from all the cells in the table.
+     */
+    getSelectedMergedCellClassNameToRemove(): string[];
+}
+export default SelectionCalculations;

package/plugins/mergeCells/calculations/selection.js

@@ -1,4 +1,9 @@
-"use strict";
+/**
+ * Class responsible for all of the Selection-related operations on merged cells.
+ *
+ * @private
+ * @class SelectionCalculations
+ */ "use strict";
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
@@ -9,10 +14,7 @@ Object.defineProperty(exports, "default", {
     }
 });
 /**
- * Class responsible for all of the Selection-related operations on merged cells.
- *
- * @private
- * @class SelectionCalculations
+ * Handles all selection-related calculations for merged cells, such as class name generation and full-selection detection.
  */ class SelectionCalculations {
     /**
    * Generate an additional class name for the entirely-selected merged cells.
@@ -30,12 +32,13 @@ Object.defineProperty(exports, "default", {
         if (layerLevel === undefined) {
             return;
         }
-        const isFirstRenderableMergedCell = this.plugin.mergedCellsCollection.isFirstRenderableMergedCell(currentRow, currentColumn);
+        const mergedCellsCollection = this.plugin.mergedCellsCollection;
+        const isFirstRenderableMergedCell = mergedCellsCollection.isFirstRenderableMergedCell(currentRow, currentColumn);
         // We add extra classes just to the first renderable merged cell.
         if (!isFirstRenderableMergedCell) {
             return;
         }
-        const mergedCell = this.plugin.mergedCellsCollection.get(currentRow, currentColumn);
+        const mergedCell = mergedCellsCollection.get(currentRow, currentColumn);
         if (!mergedCell) {
             return;
         }
@@ -44,7 +47,7 @@ Object.defineProperty(exports, "default", {
         const fullMergeAreaWithinSelection = startRow <= mergedCell.row && startColumn <= mergedCell.col && endRow >= mergeRowEnd && endColumn >= mergeColumnEnd;
         if (fullMergeAreaWithinSelection) {
             return `${this.fullySelectedMergedCellClassName}-${layerLevel}`;
-        } else if (this.isMergeCellFullySelected(mergedCell, this.plugin.hot.getSelectedRange())) {
+        } else if (this.isMergeCellFullySelected(mergedCell, this.hot.getSelectedRange())) {
             return `${this.fullySelectedMergedCellClassName}-multiple`;
         }
     }
@@ -87,7 +90,9 @@ Object.defineProperty(exports, "default", {
         classNames.push(`${this.fullySelectedMergedCellClassName}-multiple`);
         return classNames;
     }
-    constructor(plugin){
+    /**
+   * Initializes the selection calculations helper with a reference to the MergeCells plugin instance.
+   */ constructor(plugin){
         /**
    * Class name used for fully selected merged cells.
    *

package/plugins/mergeCells/calculations/selection.mjs

@@ -3,6 +3,8 @@
  *
  * @private
  * @class SelectionCalculations
+ */ /**
+ * Handles all selection-related calculations for merged cells, such as class name generation and full-selection detection.
  */ class SelectionCalculations {
     /**
    * Generate an additional class name for the entirely-selected merged cells.
@@ -20,12 +22,13 @@
         if (layerLevel === undefined) {
             return;
         }
-        const isFirstRenderableMergedCell = this.plugin.mergedCellsCollection.isFirstRenderableMergedCell(currentRow, currentColumn);
+        const mergedCellsCollection = this.plugin.mergedCellsCollection;
+        const isFirstRenderableMergedCell = mergedCellsCollection.isFirstRenderableMergedCell(currentRow, currentColumn);
         // We add extra classes just to the first renderable merged cell.
         if (!isFirstRenderableMergedCell) {
             return;
         }
-        const mergedCell = this.plugin.mergedCellsCollection.get(currentRow, currentColumn);
+        const mergedCell = mergedCellsCollection.get(currentRow, currentColumn);
         if (!mergedCell) {
             return;
         }
@@ -34,7 +37,7 @@
         const fullMergeAreaWithinSelection = startRow <= mergedCell.row && startColumn <= mergedCell.col && endRow >= mergeRowEnd && endColumn >= mergeColumnEnd;
         if (fullMergeAreaWithinSelection) {
             return `${this.fullySelectedMergedCellClassName}-${layerLevel}`;
-        } else if (this.isMergeCellFullySelected(mergedCell, this.plugin.hot.getSelectedRange())) {
+        } else if (this.isMergeCellFullySelected(mergedCell, this.hot.getSelectedRange())) {
             return `${this.fullySelectedMergedCellClassName}-multiple`;
         }
     }
@@ -77,7 +80,9 @@
         classNames.push(`${this.fullySelectedMergedCellClassName}-multiple`);
         return classNames;
     }
-    constructor(plugin){
+    /**
+   * Initializes the selection calculations helper with a reference to the MergeCells plugin instance.
+   */ constructor(plugin){
         /**
    * Class name used for fully selected merged cells.
    *

package/plugins/mergeCells/cellCoords.d.mts

@@ -0,0 +1,2 @@
+export * from './cellCoords.js';
+export { default } from './cellCoords.js';

package/plugins/mergeCells/cellCoords.d.ts

@@ -0,0 +1,218 @@
+import type { HotInstance } from '../../core/types';
+import type { default as CellCoords } from '../../3rdparty/walkontable/src/cell/coords';
+import type { default as CellRange } from '../../3rdparty/walkontable/src/cell/range';
+/**
+ * The `MergedCellCoords` class represents a single merged cell.
+ *
+ * @private
+ * @class MergedCellCoords
+ */
+declare class MergedCellCoords {
+    #private;
+    /**
+     * The index of the topmost merged cell row.
+     *
+     * @type {number}
+     */
+    row: number;
+    /**
+     * The index of the leftmost column.
+     *
+     * @type {number}
+     */
+    col: number;
+    /**
+     * The `rowspan` value of the merged cell.
+     *
+     * @type {number}
+     */
+    rowspan: number;
+    /**
+     * The `colspan` value of the merged cell.
+     *
+     * @type {number}
+     */
+    colspan: number;
+    /**
+     * `true` only if the merged cell is bound to be removed.
+     *
+     * @type {boolean}
+     */
+    removed: boolean;
+    /**
+     * The CellCoords function factory.
+     *
+     * @type {Function}
+     */
+    cellCoordsFactory: (row: number, col: number) => CellCoords;
+    /**
+     * The CellRange function factory.
+     *
+     * @type {Function}
+     */
+    cellRangeFactory: (highlight: CellCoords, from: CellCoords, to: CellCoords) => CellRange;
+    /**
+     * Initializes the merged cell coordinates with its top-left position, span dimensions, and factories for creating cell coordinate and range objects.
+     */
+    constructor(row: number, column: number, rowspan: number, colspan: number, cellCoordsFactory: (row: number, col: number) => CellCoords, cellRangeFactory: (highlight: CellCoords, from: CellCoords, to: CellCoords) => CellRange);
+    /**
+     * Get a warning message for when the declared merged cell data contains negative values.
+     *
+     * @param {{ row: number, col: number, rowspan: number, colspan: number }} mergedCell Object containing information
+     * about the merged cells that was about to be added.
+     * @returns {string}
+     */
+    static NEGATIVE_VALUES_WARNING({ row, col, rowspan, colspan }: {
+        row: number;
+        col: number;
+        rowspan: number;
+        colspan: number;
+    }): string;
+    /**
+     * Get a warning message for when the declared merged cell data contains values exceeding the table limits.
+     *
+     * @param {{ row: number, col: number, rowspan: number, colspan: number }} mergedCell Object containing information
+     * about the merged cells that was about to be added.
+     * @returns {string}
+     */
+    static IS_OUT_OF_BOUNDS_WARNING({ row, col }: {
+        row: number;
+        col: number;
+    }): string;
+    /**
+     * Get a warning message for when the declared merged cell data represents a single cell.
+     *
+     * @param {{ row: number, col: number, rowspan: number, colspan: number }} mergedCell Object containing information
+     * about the merged cells that was about to be added.
+     * @returns {string}
+     */
+    static IS_SINGLE_CELL({ row, col }: {
+        row: number;
+        col: number;
+    }): string;
+    /**
+     * Get a warning message for when the declared merged cell data contains "colspan" or "rowspan", that equals 0.
+     *
+     * @param {{ row: number, col: number, rowspan: number, colspan: number }} mergedCell Object containing information
+     * about the merged cells that was about to be added.
+     * @returns {string}
+     */
+    static ZERO_SPAN_WARNING({ row, col }: {
+        row: number;
+        col: number;
+    }): string;
+    /**
+     * Check whether the values provided for a merged cell contain any negative values.
+     *
+     * @param {{ row: number, col: number, rowspan: number, colspan: number }} mergedCell Object containing information
+     * about the merged cells that was about to be added.
+     * @returns {boolean}
+     */
+    static containsNegativeValues({ row, col, rowspan, colspan }: {
+        row: number;
+        col: number;
+        rowspan: number;
+        colspan: number;
+    }): boolean;
+    /**
+     * Check whether the provided merged cell information object represents a single cell.
+     *
+     * @private
+     * @param {{ row: number, col: number, rowspan: number, colspan: number }} mergedCell Object containing information
+     * about the merged cells that was about to be added.
+     * @returns {boolean}
+     */
+    static isSingleCell({ rowspan, colspan }: {
+        rowspan: number;
+        colspan: number;
+    }): boolean;
+    /**
+     * Check whether the provided merged cell information object contains a rowspan or colspan of 0.
+     *
+     * @private
+     * @param {{ row: number, col: number, rowspan: number, colspan: number }} mergedCell Object containing information
+     * about the merged cells that was about to be added.
+     * @returns {boolean}
+     */
+    static containsZeroSpan({ rowspan, colspan }: {
+        rowspan: number;
+        colspan: number;
+    }): boolean;
+    /**
+     * Check whether the provided merged cell object is to be declared out of bounds of the table.
+     *
+     * @param {object} mergeCell Object containing the `row`, `col`, `rowspan` and `colspan` properties.
+     * @param {number} rowCount Number of rows in the table.
+     * @param {number} columnCount Number of rows in the table.
+     * @returns {boolean}
+     */
+    static isOutOfBounds(mergeCell: {
+        row: number;
+        col: number;
+        rowspan: number;
+        colspan: number;
+    }, rowCount: number, columnCount: number): boolean;
+    /**
+     * Sanitize (prevent from going outside the boundaries) the merged cell.
+     *
+     * @param {Core} hotInstance The Handsontable instance.
+     */
+    normalize(hotInstance: HotInstance): void;
+    /**
+     * Returns `true` if the provided coordinates are inside the merged cell.
+     *
+     * @param {number} row The row index.
+     * @param {number} column The column index.
+     * @returns {boolean}
+     */
+    includes(row: number, column: number): boolean;
+    /**
+     * Returns `true` if the provided `column` property is within the column span of the merged cell.
+     *
+     * @param {number} column The column index.
+     * @returns {boolean}
+     */
+    includesHorizontally(column: number): boolean;
+    /**
+     * Returns `true` if the provided `row` property is within the row span of the merged cell.
+     *
+     * @param {number} row Row index.
+     * @returns {boolean}
+     */
+    includesVertically(row: number): boolean;
+    /**
+     * Shift (and possibly resize, if needed) the merged cell.
+     *
+     * @param {Array} shiftVector 2-element array containing the information on the shifting in the `x` and `y` axis.
+     * @param {number} indexOfChange Index of the preceding change.
+     * @returns {boolean} Returns `false` if the whole merged cell was removed.
+     */
+    shift(shiftVector: number[], indexOfChange: number): boolean;
+    /**
+     * Check if the second provided merged cell is "farther" in the provided direction.
+     *
+     * @param {MergedCellCoords} mergedCell The merged cell to check.
+     * @param {string} direction Drag direction.
+     * @returns {boolean|null} `true` if the second provided merged cell is "farther".
+     */
+    isFarther(mergedCell: MergedCellCoords | null, direction: string): boolean | null;
+    /**
+     * Get the bottom row index of the merged cell.
+     *
+     * @returns {number}
+     */
+    getLastRow(): number;
+    /**
+     * Get the rightmost column index of the merged cell.
+     *
+     * @returns {number}
+     */
+    getLastColumn(): number;
+    /**
+     * Get the range coordinates of the merged cell.
+     *
+     * @returns {CellRange}
+     */
+    getRange(): CellRange;
+}
+export default MergedCellCoords;

package/plugins/mergeCells/cellCoords.js

@@ -283,7 +283,9 @@ var /**
         }
         return _class_private_field_get(this, _cellRange);
     }
-    constructor(row, column, rowspan, colspan, cellCoordsFactory, cellRangeFactory){
+    /**
+   * Initializes the merged cell coordinates with its top-left position, span dimensions, and factories for creating cell coordinate and range objects.
+   */ constructor(row, column, rowspan, colspan, cellCoordsFactory, cellRangeFactory){
         _class_private_field_init(this, _cellRange, {
             writable: true,
             value: void 0

package/plugins/mergeCells/cellCoords.mjs

@@ -273,7 +273,9 @@ var /**
         }
         return _class_private_field_get(this, _cellRange);
     }
-    constructor(row, column, rowspan, colspan, cellCoordsFactory, cellRangeFactory){
+    /**
+   * Initializes the merged cell coordinates with its top-left position, span dimensions, and factories for creating cell coordinate and range objects.
+   */ constructor(row, column, rowspan, colspan, cellCoordsFactory, cellRangeFactory){
         _class_private_field_init(this, _cellRange, {
             writable: true,
             value: void 0

package/plugins/mergeCells/cellsCollection.d.mts

@@ -0,0 +1,2 @@
+export * from './cellsCollection.js';
+export { default } from './cellsCollection.js';