handsontable 17.1.0 → 18.0.0-rc2

package/plugins/mergeCells/mergeCells.d.ts

@@ -1,26 +1,306 @@
-import Core from '../../core';
-import { BasePlugin } from '../base';
-import CellRange from '../../3rdparty/walkontable/src/cell/range';
-
-export interface MergeCellsSettings {
-  row: number;
-  col: number;
-  rowspan: number;
-  colspan: number;
-}
-export interface DetailedSettings {
-  virtualized: boolean;
-  cells: MergeCellsSettings[];
-}
-
-export type Settings = boolean | MergeCellsSettings[] | DetailedSettings;
-
-export class MergeCells extends BasePlugin {
-  constructor(hotInstance: Core);
-  isEnabled(): boolean;
-  clearCollections(): void;
-  mergeSelection(cellRange?: CellRange): void;
-  unmergeSelection(cellRange?: CellRange): void;
-  merge(startRow: number, startColumn: number, endRow: number, endColumn: number): void;
-  unmerge(startRow: number, startColumn: number, endRow: number, endColumn: number): void;
+import type { default as CellRange } from '../../3rdparty/walkontable/src/cell/range';
+import { BasePlugin, defaultMainSettingSymbol } from '../base';
+import MergedCellsCollection from './cellsCollection';
+import AutofillCalculations from './calculations/autofill';
+import SelectionCalculations from './calculations/selection';
+export declare const PLUGIN_KEY = "mergeCells";
+export declare const PLUGIN_PRIORITY = 150;
+/**
+ * @plugin MergeCells
+ * @class MergeCells
+ *
+ * @description
+ * Plugin, which allows merging cells in the table (using the initial configuration, API or context menu).
+ *
+ * @example
+ *
+ * ::: only-for javascript
+ * ```js
+ * const hot = new Handsontable(document.getElementById('example'), {
+ *  data: getData(),
+ *  mergeCells: [
+ *    {row: 0, col: 3, rowspan: 3, colspan: 3},
+ *    {row: 2, col: 6, rowspan: 2, colspan: 2},
+ *    {row: 4, col: 8, rowspan: 3, colspan: 3}
+ *  ],
+ * ```
+ * :::
+ *
+ * ::: only-for react
+ * ```jsx
+ * <HotTable
+ *   data={getData()}
+ *   // enable plugin
+ *   mergeCells={[
+ *    {row: 0, col: 3, rowspan: 3, colspan: 3},
+ *    {row: 2, col: 6, rowspan: 2, colspan: 2},
+ *    {row: 4, col: 8, rowspan: 3, colspan: 3}
+ *   ]}
+ * />
+ * ```
+ * :::
+ *
+ * ::: only-for angular
+ * ```ts
+ * settings = {
+ *   data: getData(),
+ *   // Enable plugin
+ *   mergeCells: [
+ *     { row: 0, col: 3, rowspan: 3, colspan: 3 },
+ *     { row: 2, col: 6, rowspan: 2, colspan: 2 },
+ *     { row: 4, col: 8, rowspan: 3, colspan: 3 },
+ *   ],
+ * };
+ * ```
+ *
+ * ```html
+ * <hot-table [settings]="settings"></hot-table>
+ * ```
+ * :::
+ */
+export declare class MergeCells extends BasePlugin {
+    #private;
+    /**
+     * Returns the plugin key used to identify this plugin in Handsontable settings.
+     */
+    static get PLUGIN_KEY(): string;
+    /**
+     * Returns the priority order used to determine the order in which plugins are initialized.
+     */
+    static get PLUGIN_PRIORITY(): number;
+    /**
+     * Returns the default settings applied when the plugin is enabled without explicit configuration.
+     */
+    static get DEFAULT_SETTINGS(): {
+        [defaultMainSettingSymbol]: string;
+        virtualized: boolean;
+        cells: {
+            row: number;
+            col: number;
+            rowspan: number;
+            colspan: number;
+        }[];
+    };
+    /**
+     * A container for all the merged cells.
+     *
+     * @private
+     * @type {MergedCellsCollection}
+     */
+    mergedCellsCollection: MergedCellsCollection;
+    /**
+     * Instance of the class responsible for all the autofill-related calculations.
+     *
+     * @private
+     * @type {AutofillCalculations}
+     */
+    autofillCalculations: AutofillCalculations;
+    /**
+     * Instance of the class responsible for the selection-related calculations.
+     *
+     * @private
+     * @type {SelectionCalculations}
+     */
+    selectionCalculations: SelectionCalculations;
+    /**
+     * Checks if the plugin is enabled in the handsontable settings. This method is executed in {@link Hooks#beforeInit}
+     * hook and if it returns `true` then the {@link MergeCells#enablePlugin} method is called.
+     *
+     * @returns {boolean}
+     */
+    isEnabled(): boolean;
+    /**
+     * Enables the plugin functionality for this Handsontable instance.
+     */
+    enablePlugin(): void;
+    /**
+     * Disables the plugin functionality for this Handsontable instance.
+     */
+    disablePlugin(): void;
+    /**
+     * Updates the plugin's state.
+     *
+     * This method is executed when [`updateSettings()`](@/api/core.md#updatesettings) is invoked with any of the
+     * following configuration options:
+     *  - [`mergeCells`](@/api/options.md#mergecells)
+     */
+    updatePlugin(): void;
+    /**
+     * If the browser is recognized as Chrome, force an additional repaint to prevent showing the effects of a Chrome bug.
+     *
+     * Issue described in https://github.com/handsontable/dev-handsontable/issues/521.
+     *
+     * @private
+     */
+    ifChromeForceRepaint(): void;
+    /**
+     * Validates a single setting object, represented by a single merged cell information object.
+     *
+     * @private
+     * @param {object} setting An object with `row`, `col`, `rowspan` and `colspan` properties.
+     * @returns {boolean}
+     */
+    validateSetting(setting: {
+        row: number;
+        col: number;
+        rowspan: number;
+        colspan: number;
+    }): boolean;
+    /**
+     * Generates the merged cells from the settings provided to the plugin.
+     *
+     * @private
+     */
+    generateFromSettings(): void;
+    /**
+     * Clears the merged cells from the merged cell container.
+     */
+    clearCollections(): void;
+    /**
+     * Returns `true` if a range is mergeable.
+     *
+     * @private
+     * @param {object} newMergedCellInfo Merged cell information object to test.
+     * @param {boolean} [auto=false] `true` if triggered at initialization.
+     * @returns {boolean}
+     */
+    canMergeRange(newMergedCellInfo: {
+        row: number;
+        col: number;
+        rowspan: number;
+        colspan: number;
+    }, auto?: boolean): boolean;
+    /**
+     * Merges the selection provided as a cell range.
+     *
+     * @param {CellRange} [cellRange] Selection cell range.
+     */
+    mergeSelection(cellRange?: CellRange | undefined): void;
+    /**
+     * Unmerges the selection provided as a cell range.
+     *
+     * @param {CellRange} [cellRange] Selection cell range.
+     */
+    unmergeSelection(cellRange?: CellRange | undefined): void;
+    /**
+     * Merges cells in the provided cell range.
+     *
+     * @private
+     * @param {CellRange} cellRange Cell range to merge.
+     * @param {boolean} [auto=false] `true` if is called automatically, e.g. At initialization.
+     * @param {boolean} [preventPopulation=false] `true`, if the method should not run `populateFromArray` at the end,
+     *   but rather return its arguments.
+     * @returns {Array|boolean} Returns an array of [row, column, dataUnderCollection] if preventPopulation is set to
+     *   true. If the the merging process went successful, it returns `true`, otherwise - `false`.
+     * @fires Hooks#beforeMergeCells
+     * @fires Hooks#afterMergeCells
+     */
+    mergeRange(cellRange: CellRange, auto?: boolean, preventPopulation?: boolean): boolean | (number | unknown[][])[] | null;
+    /**
+     * Unmerges the selection provided as a cell range. If no cell range is provided, it uses the current selection.
+     *
+     * @private
+     * @param {CellRange} cellRange Selection cell range.
+     * @param {boolean} [auto=false] `true` if called automatically by the plugin.
+     *
+     * @fires Hooks#beforeUnmergeCells
+     * @fires Hooks#afterUnmergeCells
+     */
+    unmergeRange(cellRange: CellRange, auto?: boolean): void;
+    /**
+     * Merges or unmerges, based on the cell range provided as `cellRange`.
+     *
+     * @private
+     * @param {CellRange} cellRange The cell range to merge or unmerged.
+     */
+    toggleMerge(cellRange: CellRange): void;
+    /**
+     * Merges the specified range.
+     *
+     * @param {number} startRow Start row of the merged cell.
+     * @param {number} startColumn Start column of the merged cell.
+     * @param {number} endRow End row of the merged cell.
+     * @param {number} endColumn End column of the merged cell.
+     * @fires Hooks#beforeMergeCells
+     * @fires Hooks#afterMergeCells
+     */
+    merge(startRow: number, startColumn: number, endRow: number, endColumn: number): void;
+    /**
+     * Unmerges the merged cell in the provided range.
+     *
+     * @param {number} startRow Start row of the merged cell.
+     * @param {number} startColumn Start column of the merged cell.
+     * @param {number} endRow End row of the merged cell.
+     * @param {number} endColumn End column of the merged cell.
+     * @fires Hooks#beforeUnmergeCells
+     * @fires Hooks#afterUnmergeCells
+     */
+    unmerge(startRow: number, startColumn: number, endRow: number, endColumn: number): void;
+    /**
+     * Register shortcuts responsible for toggling a merge.
+     *
+     * @private
+     */
+    registerShortcuts(): void;
+    /**
+     * Unregister shortcuts responsible for toggling a merge.
+     *
+     * @private
+     */
+    unregisterShortcuts(): void;
+    /**
+     * Modify viewport start when needed.
+     *
+     * @private
+     * @param {object} calc The row calculator object.
+     * @param {number} nrOfColumns Number of visual columns.
+     */
+    modifyViewportRowStart(calc: {
+        startRow: number;
+        endRow: number;
+    }, nrOfColumns: number): void;
+    /**
+     * Modify viewport end when needed.
+     *
+     * @private
+     * @param {object} calc The row calculator object.
+     * @param {number} nrOfColumns Number of visual columns.
+     */
+    modifyViewportRowEnd(calc: {
+        startRow: number;
+        endRow: number;
+    }, nrOfColumns: number): void;
+    /**
+     * Modify viewport start when needed.
+     *
+     * @private
+     * @param {object} calc The column calculator object.
+     * @param {number} nrOfRows Number of visual rows.
+     */
+    modifyViewportColumnStart(calc: {
+        startColumn: number;
+        endColumn: number;
+    }, nrOfRows: number): void;
+    /**
+     * Modify viewport end when needed.
+     *
+     * @private
+     * @param {object} calc The column calculator object.
+     * @param {number} nrOfRows Number of visual rows.
+     */
+    modifyViewportColumnEnd(calc: {
+        startColumn: number;
+        endColumn: number;
+    }, nrOfRows: number): void;
+    /**
+     * Translates merged cell coordinates to renderable indexes.
+     *
+     * @private
+     * @param {number} parentRow Visual row index.
+     * @param {number} rowspan Rowspan.
+     * @param {number} parentColumn Visual column index.
+     * @param {number} colspan Colspan.
+     * @returns {Array<number>} A two-element array of `[renderableRow, renderableColumn]`.
+     */
+    translateMergedCellToRenderable(parentRow: number, rowspan: number, parentColumn: number, colspan: number): [number, number];
 }