handsontable 17.1.0 → 18.0.0-rc2

package/selection/selection.d.ts

@@ -0,0 +1,437 @@
+import type { default as CellCoords } from '../3rdparty/walkontable/src/cell/coords';
+import type { default as CellRange } from '../3rdparty/walkontable/src/cell/range';
+import type { SelectionFocusPosition, SelectionSettings, SelectionTableProps } from './types';
+import Highlight from './highlight/highlight';
+import SelectionRange from './range';
+/**
+ * @typedef {object} SelectionState
+ * @property {CellRange[]} ranges The array of all ranges.
+ * @property {CellRange} activeRange The active range.
+ * @property {number} activeSelectionLayer The active selection layer.
+ * @property {number[]} selectedByRowHeader The state of the selected row headers.
+ * @property {number[]} selectedByColumnHeader The state of the selected column headers.
+ * @property {boolean} disableHeadersHighlight The state of the disable headers highlight.
+ */
+/**
+ * @class Selection
+ * @util
+ */
+declare class Selection {
+    #private;
+    /**
+     * Triggers registered local hook callbacks for the given hook name, passing any additional arguments.
+     */
+    runLocalHooks: (...args: unknown[]) => void;
+    /**
+     * Registers a local hook callback for the given hook name on this instance.
+     */
+    addLocalHook: (...args: unknown[]) => this;
+    /**
+     * Handsontable settings instance.
+     *
+     * @type {GridSettings}
+     */
+    settings: SelectionSettings;
+    /**
+     * An additional object with dynamically defined properties which describes table state.
+     *
+     * @type {object}
+     */
+    tableProps: SelectionTableProps;
+    /**
+     * The flag which determines if the selection is in progress.
+     *
+     * @type {boolean}
+     */
+    inProgress: boolean;
+    /**
+     * Selection data layer (handle visual coordinates).
+     *
+     * @type {SelectionRange}
+     */
+    selectedRange: SelectionRange;
+    /**
+     * Visualization layer.
+     *
+     * @type {Highlight}
+     */
+    highlight: Highlight;
+    /**
+     * The collection of the selection layer levels where the whole row was selected using the row header or
+     * the corner header.
+     *
+     * @type {Set<number>}
+     */
+    selectedByRowHeader: Set<number>;
+    /**
+     * The collection of the selection layer levels where the whole column was selected using the column header or
+     * the corner header.
+     *
+     * @type {Set<number>}
+     */
+    selectedByColumnHeader: Set<number>;
+    /**
+     * Initializes the Selection manager with grid settings and table API references, and sets up transformation modules and highlight layers.
+     */
+    constructor(settings: SelectionSettings, tableProps: SelectionTableProps);
+    /**
+     * Updates the CSS class names used for row, column, header, and active header highlights based on
+     * the current settings. Call this after settings change via `updateSettings()`.
+     */
+    updateHighlightClassNames(): void;
+    /**
+     * Gets all selection range layers of the selection.
+     *
+     * @returns {SelectionRange}
+     */
+    getSelectedRange(): SelectionRange;
+    /**
+     * Gets the active selection range layer.
+     *
+     * @returns {CellRange}
+     */
+    getActiveSelectedRange(): CellRange | undefined;
+    /**
+     * Gets the index of the active selection range layer.
+     *
+     * @returns {number}
+     */
+    getActiveSelectionLayerIndex(): number;
+    /**
+     * Sets the index of the active selection range layer.
+     *
+     * @param {number} layerIndex The index of the active selection range layer.
+     */
+    setActiveSelectionLayerIndex(layerIndex: number): void;
+    /**
+     * Marks the source of the selection. It can be one of the following values: `mouse`, or any other string.
+     *
+     * @param {'mouse' | 'unknown' | string} sourceName The source name.
+     */
+    markSource(sourceName: string): void;
+    /**
+     * Marks end of the selection source. It restores the selection source to default value which is 'unknown'.
+     */
+    markEndSource(): void;
+    /**
+     * Returns the source of the selection.
+     *
+     * @returns {'mouse' | 'unknown' | string}
+     */
+    getSelectionSource(): string;
+    /**
+     * Set the number of expected layers. The method is not obligatory to call. It is used mostly internally
+     * to determine when the last selection layer of non-contiguous is applied, thus the viewport scroll is triggered.
+     *
+     * @param {number} layersCount The number of expected layers.
+     */
+    setExpectedLayers(layersCount: number): void;
+    /**
+     * Indicate that selection process began. It sets internally `.inProgress` property to `true`.
+     */
+    begin(): void;
+    /**
+     * Indicate that selection process finished. It sets internally `.inProgress` property to `false`.
+     */
+    finish(): void;
+    /**
+     * Check if the process of selecting the cell/cells is in progress.
+     *
+     * @returns {boolean}
+     */
+    isInProgress(): boolean;
+    /**
+     * Starts selection range on given coordinate object.
+     *
+     * @param {CellCoords} coords Visual coords.
+     * @param {boolean} [multipleSelection] If `true`, selection will be worked in 'multiple' mode. This option works
+     *                                      only when 'selectionMode' is set as 'multiple'. If the argument is not defined
+     *                                      the default trigger will be used.
+     * @param {boolean} [fragment=false] If `true`, the selection will be treated as a partial selection where the
+     *                                   `setRangeEnd` method won't be called on every `setRangeStart` call.
+     * @param {CellCoords} [highlightCoords] If set, allows changing the coordinates of the highlight/focus cell.
+     */
+    setRangeStart(coords: CellCoords, multipleSelection?: boolean, fragment?: boolean, highlightCoords?: CellCoords): void;
+    /**
+     * Starts selection range on given coordinate object.
+     *
+     * @param {CellCoords} coords Visual coords.
+     * @param {boolean} [multipleSelection] If `true`, selection will be worked in 'multiple' mode. This option works
+     *                                      only when 'selectionMode' is set as 'multiple'. If the argument is not defined
+     *                                      the default trigger will be used.
+     * @param {CellCoords} [highlightCoords] If set, allows changing the coordinates of the highlight/focus cell.
+     */
+    setRangeStartOnly(coords: CellCoords, multipleSelection?: boolean, highlightCoords?: CellCoords): void;
+    /**
+     * Ends selection range on given coordinate object.
+     *
+     * @param {CellCoords} coords Visual coords.
+     * @param {number} [layerIndex] The layer index to set the end on. If not provided, the current layer level is used.
+     */
+    setRangeEnd(coords: CellCoords, layerIndex?: number): void;
+    /**
+     * Applies and commits the selection to all layers (using the Walkontable Selection API) based on the selection (CellRanges)
+     * collected in the `selectedRange` module.
+     *
+     * @param {CellRange} [cellRange] The cell range to apply. If not provided, the current selection is used.
+     * @param {number} [layerLevel] The layer level to apply. If not provided, the current layer level is used.
+     */
+    applyAndCommit(cellRange?: CellRange | undefined, layerLevel?: number): void;
+    /**
+     * Sets the selection focus position at the specified coordinates.
+     *
+     * @param {CellCoords} coords The CellCoords instance with defined visual coordinates.
+     * @param {number} [layerIndex] The layer index to set the focus on.
+     */
+    setRangeFocus(coords: CellCoords, layerIndex?: number): void;
+    /**
+     * Selects cell relative to the current cell (if possible).
+     *
+     * @param {number} rowDelta Rows number to move, value can be passed as negative number.
+     * @param {number} colDelta Columns number to move, value can be passed as negative number.
+     * @param {boolean} [createMissingRecords=false] If `true` the new rows/columns will be created if necessary.
+     * Otherwise, row/column will be created according to `minSpareRows/minSpareCols` settings of Handsontable.
+     */
+    transformStart(rowDelta: number, colDelta: number, createMissingRecords?: boolean): void;
+    /**
+     * Sets selection end cell relative to the current selection end cell (if possible).
+     *
+     * @param {number} rowDelta Rows number to move, value can be passed as negative number.
+     * @param {number} colDelta Columns number to move, value can be passed as negative number.
+     */
+    transformEnd(rowDelta: number, colDelta: number): void;
+    /**
+     * Transforms the focus cell selection relative to the current focus position.
+     *
+     * @param {number} rowDelta Rows number to move, value can be passed as negative number.
+     * @param {number} colDelta Columns number to move, value can be passed as negative number.
+     */
+    transformFocus(rowDelta: number, colDelta: number): void;
+    /**
+     * Transforms the last selection layer down or up by the index count.
+     *
+     * @param {number} visualRowIndex Visual row index from which the selection will be shifted.
+     * @param {number} amount The number of rows to shift the selection.
+     */
+    shiftRows(visualRowIndex: number, amount: number): void;
+    /**
+     * Transforms the last selection layer left or right by the index count.
+     *
+     * @param {number} visualColumnIndex Visual column index from which the selection will be shifted.
+     * @param {number} amount The number of columns to shift the selection.
+     */
+    shiftColumns(visualColumnIndex: number, amount: number): void;
+    /**
+     * Returns currently used layer level.
+     *
+     * @returns {number} Returns layer level starting from 0. If no selection was added to the table -1 is returned.
+     */
+    getLayerLevel(): number;
+    /**
+     * Returns `true` if currently there is a selection on the screen, `false` otherwise.
+     *
+     * @returns {boolean}
+     */
+    isSelected(): boolean;
+    /**
+     * Returns information if we have a multi-selection. This method check multi-selection only on the latest layer of
+     * the selection.
+     *
+     * @param {CellRange} [cellRange] The cell range to check. If not provided, the latest selection layer is used.
+     * @returns {boolean}
+     */
+    isMultiple(cellRange?: CellRange | undefined): unknown;
+    /**
+     * Checks if the last selection involves changing the focus cell position only.
+     *
+     * @returns {boolean}
+     */
+    isFocusSelectionChanged(): boolean;
+    /**
+     * Returns `true` if the selection was applied by clicking to the row header. If the `layerLevel`
+     * argument is passed then only that layer will be checked. Otherwise, it checks if any row header
+     * was clicked on any selection layer level.
+     *
+     * @param {number} [layerLevel=this.getLayerLevel()] Selection layer level to check.
+     * @returns {boolean}
+     */
+    isSelectedByRowHeader(layerLevel?: number): boolean;
+    /**
+     * Returns `true` if the selection consists of entire rows (including their headers). If the `layerLevel`
+     * argument is passed then only that layer will be checked. Otherwise, it checks the selection for all layers.
+     *
+     * @param {number} [layerLevel=this.getLayerLevel()] Selection layer level to check.
+     * @returns {boolean}
+     */
+    isEntireRowSelected(layerLevel?: number): boolean;
+    /**
+     * Returns `true` if the selection was applied by clicking to the column header. If the `layerLevel`
+     * argument is passed then only that layer will be checked. Otherwise, it checks if any column header
+     * was clicked on any selection layer level.
+     *
+     * @param {number} [layerLevel=this.getLayerLevel()] Selection layer level to check.
+     * @returns {boolean}
+     */
+    isSelectedByColumnHeader(layerLevel?: number): boolean;
+    /**
+     * Returns `true` if the selection consists of entire columns (including their headers). If the `layerLevel`
+     * argument is passed then only that layer will be checked. Otherwise, it checks the selection for all layers.
+     *
+     * @param {number} [layerLevel=this.getLayerLevel()] Selection layer level to check.
+     * @returns {boolean}
+     */
+    isEntireColumnSelected(layerLevel?: number): boolean;
+    /**
+     * Returns `true` if the selection was applied by clicking on the row or column header on any layer level.
+     *
+     * @returns {boolean}
+     */
+    isSelectedByAnyHeader(): boolean;
+    /**
+     * Returns `true` if the selection was applied by clicking on the left-top corner overlay.
+     *
+     * @returns {boolean}
+     */
+    isSelectedByCorner(): boolean;
+    /**
+     * Returns `true` if coords is within selection coords. This method iterates through all selection layers to check if
+     * the coords object is within selection range.
+     *
+     * @param {CellCoords} coords The CellCoords instance with defined visual coordinates.
+     * @returns {boolean}
+     */
+    inInSelection(coords: CellCoords): boolean;
+    /**
+     * Returns `true` if the cell corner should be visible.
+     *
+     * @private
+     * @returns {boolean} `true` if the corner element has to be visible, `false` otherwise.
+     */
+    isCellCornerVisible(): unknown;
+    /**
+     * Returns `true` if the cell coordinates are visible (renderable).
+     *
+     * @private
+     * @param {CellCoords} coords The cell coordinates to check.
+     * @returns {boolean}
+     */
+    isCellVisible(coords: CellCoords): boolean;
+    /**
+     * Returns `true` if the area corner should be visible.
+     *
+     * @param {number} layerLevel The layer level.
+     * @returns {boolean} `true` if the corner element has to be visible, `false` otherwise.
+     */
+    isAreaCornerVisible(layerLevel: number): unknown;
+    /**
+     * Clear the selection by resetting the collected ranges and highlights.
+     */
+    clear(): void;
+    /**
+     * Deselects all selected cells.
+     */
+    deselect(): void;
+    /**
+     * Selects all cells and headers.
+     *
+     * @param {boolean} [includeRowHeaders=false] `true` If the selection should include the row headers,
+     * `false` otherwise.
+     * @param {boolean} [includeColumnHeaders=false] `true` If the selection should include the column
+     * headers, `false` otherwise.
+     * @param {object} [options] Additional object with options.
+     * @param {{row: number, col: number} | boolean} [options.focusPosition] The argument allows changing the cell/header
+     * focus position. The value takes an object with a `row` and `col` properties from -N to N, where
+     * negative values point to the headers and positive values point to the cell range. If `false`, the focus
+     * position won't be changed.
+     * @param {boolean} [options.disableHeadersHighlight] If `true`, disables highlighting the headers even when
+     * the logical coordinates points on them.
+     */
+    selectAll(includeRowHeaders?: boolean, includeColumnHeaders?: boolean, options?: {
+        focusPosition?: SelectionFocusPosition | boolean;
+        disableHeadersHighlight?: boolean;
+    }): void;
+    /**
+     * Make multiple, non-contiguous selection specified by `row` and `column` values or a range of cells
+     * finishing at `endRow`, `endColumn`. The method supports two input formats, first as an array of arrays such
+     * as `[[rowStart, columnStart, rowEnd, columnEnd]]` and second format as an array of CellRange objects.
+     * If the passed ranges have another format the exception will be thrown.
+     *
+     * @param {Array[]|CellRange[]} selectionRanges The coordinates which define what the cells should be selected.
+     * @returns {boolean} Returns `true` if selection was successful, `false` otherwise.
+     */
+    selectCells(selectionRanges: unknown[]): boolean;
+    /**
+     * Select column specified by `startColumn` visual index or column property or a range of columns finishing at
+     * `endColumn`.
+     *
+     * @param {number|string} startColumn Visual column index or column property from which the selection starts.
+     * @param {number|string} [endColumn] Visual column index or column property from to the selection finishes.
+     * @param {number | { row: number, col: number }} [focusPosition=0] The argument allows changing the cell/header focus
+     * position. The value can take visual row index from -N to N, where negative values point to the headers and positive
+     * values point to the cell range. An object with `row` and `col` properties also can be passed to change the focus
+     * position horizontally.
+     * @returns {boolean} Returns `true` if selection was successful, `false` otherwise.
+     */
+    selectColumns(startColumn: number | string, endColumn?: number | string, focusPosition?: number | {
+        row?: number;
+        col?: number;
+    }): boolean;
+    /**
+     * Select row specified by `startRow` visual index or a range of rows finishing at `endRow`.
+     *
+     * @param {number} startRow Visual row index from which the selection starts.
+     * @param {number} [endRow] Visual row index from to the selection finishes.
+     * @param {number | { row: number, col: number }} [focusPosition=0] The argument allows changing the cell/header focus
+     * position. The value can take visual row index from -N to N, where negative values point to the headers and positive
+     * values point to the cell range. An object with `row` and `col` properties also can be passed to change the focus
+     * position horizontally.
+     * @returns {boolean} Returns `true` if selection was successful, `false` otherwise.
+     */
+    selectRows(startRow: number, endRow?: number, focusPosition?: number | {
+        row?: number;
+        col?: number;
+    }): boolean;
+    /**
+     * Allows importing the selection for all layers from the provided array of CellRange objects.
+     * The method clears the current selection and sets the new one without triggering any
+     * selection related hooks.
+     *
+     * @param {SelectionState} selectionState The selection state to import.
+     */
+    importSelection({ ranges, activeRange, activeSelectionLayer, selectedByRowHeader, selectedByColumnHeader, disableHeadersHighlight, }: {
+        ranges: CellRange[];
+        activeRange: CellRange;
+        activeSelectionLayer: number;
+        selectedByRowHeader: number[];
+        selectedByColumnHeader: number[];
+        disableHeadersHighlight: boolean;
+    }): void;
+    /**
+     * Exports all selection layers with other properties related to the selection state.
+     *
+     * @returns {SelectionState}
+     */
+    exportSelection(): {
+        ranges: CellRange[];
+        activeRange: CellRange | undefined;
+        activeSelectionLayer: number;
+        selectedByRowHeader: number[];
+        selectedByColumnHeader: number[];
+        disableHeadersHighlight: boolean;
+    };
+    /**
+     * Refreshes the whole selection by clearing, reapplying and committing (calculating visual to renderable indexes)
+     * the selection by using already added visual ranges. The method can be useful when underneath some indexes
+     * was hidden/showed or dataset size was changed or the range of the cell ranges was modified. Then, to see the
+     * changes in the selection the method may be needed to be called. The method modifies the visual ranges if needed.
+     */
+    refresh(): void;
+    /**
+     * Refreshes the whole selection by only recommitting values. In terms of the selection the committing
+     * values means that the cell ranges are again recalculated to the renderable indexes - the visual
+     * indexes are not touched. The method can be useful when underneath some indexes was hidden/showed
+     * which affects the selection. In that cases the method may be needed to be called.
+     */
+    commit(): void;
+}
+export default Selection;