handsontable 12.2.0 → 12.3.0-next-bb1a7c2-20221208

package/core.mjs

@@ -8,7 +8,7 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
 function _taggedTemplateLiteral(strings, raw) { if (!raw) { raw = strings.slice(0); } return Object.freeze(Object.defineProperties(strings, { raw: { value: Object.freeze(raw) } })); }
 function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
 function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
-function _iterableToArrayLimit(arr, i) { var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"]; if (_i == null) return; var _arr = []; var _n = true; var _d = false; var _s, _e; try { for (_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true) { _arr.push(_s.value); if (i && _arr.length === i) break; } } catch (err) { _d = true; _e = err; } finally { try { if (!_n && _i["return"] != null) _i["return"](); } finally { if (_d) throw _e; } } return _arr; }
+function _iterableToArrayLimit(arr, i) { var _i = null == arr ? null : "undefined" != typeof Symbol && arr[Symbol.iterator] || arr["@@iterator"]; if (null != _i) { var _s, _e, _x, _r, _arr = [], _n = !0, _d = !1; try { if (_x = (_i = _i.call(arr)).next, 0 === i) { if (Object(_i) !== _i) return; _n = !1; } else for (; !(_n = (_s = _x.call(_i)).done) && (_arr.push(_s.value), _arr.length !== i); _n = !0) { ; } } catch (err) { _d = !0, _e = err; } finally { try { if (!_n && null != _i.return && (_r = _i.return(), Object(_r) !== _r)) return; } finally { if (_d) throw _e; } } return _arr; } }
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
 function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
@@ -39,7 +39,7 @@ import "core-js/modules/web.dom-collections.for-each.js";
 import "core-js/modules/web.timers.js";
 import "core-js/modules/web.immediate.js";
 import "core-js/modules/es.map.js";
-import { addClass, empty, removeClass } from "./helpers/dom/element.mjs";
+import { addClass, empty, observeVisibilityChangeOnce, removeClass } from "./helpers/dom/element.mjs";
 import { isFunction } from "./helpers/function.mjs";
 import { isDefined, isUndefined, isRegExp, _injectProductInfo, isEmpty } from "./helpers/mixed.mjs";
 import { isMobileBrowser, isIpadOS } from "./helpers/browser.mjs";
@@ -52,12 +52,13 @@ import { arrayMap, arrayEach, arrayReduce, getDifferenceOfArrays, stringToArray,
 import { instanceToHTML } from "./utils/parseTable.mjs";
 import { getPlugin, getPluginsNames } from "./plugins/registry.mjs";
 import { getRenderer } from "./renderers/registry.mjs";
+import { getEditor } from "./editors/registry.mjs";
 import { getValidator } from "./validators/registry.mjs";
 import { randomString, toUpperCaseFirst } from "./helpers/string.mjs";
 import { rangeEach, rangeEachReverse, isNumericLike } from "./helpers/number.mjs";
 import TableView from "./tableView.mjs";
 import DataSource from "./dataMap/dataSource.mjs";
-import { cellMethodLookupFactory, spreadsheetColumnLabel } from "./helpers/data.mjs";
+import { spreadsheetColumnLabel } from "./helpers/data.mjs";
 import { IndexMapper } from "./translations/index.mjs";
 import { registerAsRootInstance, hasValidParameter, isRootInstance } from "./utils/rootInstance.mjs";
 import { ViewportColumnsCalculator } from "./3rdparty/walkontable/src/index.mjs";
@@ -80,37 +81,41 @@ var deprecationWarns = new Set();
  * @class Core
  * @description
  *
- * The `Handsontable` class to which we refer as to `Core`, allows you to modify the grid's behavior by using one of the available public methods.
+ * The `Handsontable` class (known as the `Core`) lets you modify the grid's behavior by using Handsontable's public API methods.
+ *
+ * ::: only-for react
+ * To use these methods, associate a Handsontable instance with your instance
+ * of the [`HotTable` component](@/guides/getting-started/installation.md#use-the-hottable-component),
+ * by using React's `ref` feature (read more on the [Instance methods](@/guides/getting-started/react-methods.md) page).
+ * :::
  *
  * ## How to call a method
  *
  * ::: only-for javascript
  * ```js
- * // First, let's construct Handsontable
+ * // create a Handsontable instance
  * const hot = new Handsontable(document.getElementById('example'), options);
  *
- * // Then, let's use the setDataAtCell method
+ * // call a method
  * hot.setDataAtCell(0, 0, 'new value');
  * ```
  * :::
  *
  * ::: only-for react
- * ```jsx
- * const hotRef = useRef(null);
+ * ```jsx{3,7,13}
+ * import { useRef } from 'react';
  *
- * ...
+ * const hotTableComponent = useRef(null);
  *
- * // First, let's contruct Handsontable
  * <HotTable
- *   ref={hotRef}
+ *   // associate your `HotTable` component with a Handsontable instance
+ *   ref={hotTableComponent}
  *   settings={options}
  * />
  *
- * ...
- *
- * const hot = hotRef.current.hotInstance;
- * // Then, let's use the setDataAtCell method
- * hot.setDataAtCell(0, 0, 'new value');
+ * // access the Handsontable instance, under the `.current.hotInstance` property
+ * // call a method
+ * hotTableComponent.current.hotInstance.setDataAtCell(0, 0, 'new value');
  * ```
  * :::
  *
@@ -441,7 +446,8 @@ export default function Core(rootElement, userSettings) {
      * @param {number} [amount=1] Amount of rows or columns to remove.
      * @param {string} [source] Optional. Source of hook runner.
      * @param {boolean} [keepEmptyRows] Optional. Flag for preventing deletion of empty rows.
-     */alter: function alter(action, index) {
+     */
+    alter: function alter(action, index) {
       var _index, _index2;
       var amount = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 1;
       var source = arguments.length > 3 ? arguments[3] : undefined;
@@ -516,7 +522,6 @@ export default function Core(rootElement, userSettings) {
             rowDelta = _datamap$createRow.delta,
             startRowPhysicalIndex = _datamap$createRow.startPhysicalIndex;
           if (rowDelta) {
-            metaManager.createRow(startRowPhysicalIndex, amount);
             var currentSelectedRange = selection.selectedRange.current();
             var currentFromRange = currentSelectedRange === null || currentSelectedRange === void 0 ? void 0 : currentSelectedRange.from;
             var currentFromRow = currentFromRange === null || currentFromRange === void 0 ? void 0 : currentFromRange.row;
@@ -572,7 +577,6 @@ export default function Core(rootElement, userSettings) {
             colDelta = _datamap$createCol.delta,
             startColumnPhysicalIndex = _datamap$createCol.startPhysicalIndex;
           if (colDelta) {
-            metaManager.createColumn(startColumnPhysicalIndex, amount);
             if (Array.isArray(tableMeta.colHeaders)) {
               var spliceArray = [instance.toVisualColumn(startColumnPhysicalIndex), 0];
               spliceArray.length += colDelta; // inserts empty (undefined) elements at the end of an array
@@ -635,7 +639,6 @@ export default function Core(rootElement, userSettings) {
               if (!wasRemoved) {
                 return;
               }
-              metaManager.removeRow(instance.toPhysicalRow(calcIndex), groupAmount);
               var totalRows = instance.countRows();
               var fixedRowsTop = tableMeta.fixedRowsTop;
               if (fixedRowsTop >= calcIndex + 1) {
@@ -681,7 +684,6 @@ export default function Core(rootElement, userSettings) {
               if (!wasRemoved) {
                 return;
               }
-              metaManager.removeColumn(physicalColumnIndex, groupAmount);
               var fixedColumnsStart = tableMeta.fixedColumnsStart;
               if (fixedColumnsStart >= calcIndex + 1) {
                 tableMeta.fixedColumnsStart -= Math.min(groupAmount, fixedColumnsStart - calcIndex);
@@ -715,7 +717,8 @@ export default function Core(rootElement, userSettings) {
      * Makes sure there are empty rows at the bottom of the table.
      *
      * @private
-     */adjustRowsAndCols: function adjustRowsAndCols() {
+     */
+    adjustRowsAndCols: function adjustRowsAndCols() {
       var minRows = tableMeta.minRows;
       var minSpareRows = tableMeta.minSpareRows;
       var minCols = tableMeta.minCols;
@@ -841,7 +844,8 @@ export default function Core(rootElement, userSettings) {
      * @param {Array} deltas The deltas array. A difference between values of adjacent cells.
      *                       Useful **only** when the type of handled cells is `numeric`.
      * @returns {object|undefined} Ending td in pasted area (only if any cell was changed).
-     */populateFromArray: function populateFromArray(start, input, end, source, method, direction, deltas) {
+     */
+    populateFromArray: function populateFromArray(start, input, end, source, method, direction, deltas) {
       // TODO: either remove or implement the `direction` argument. Currently it's not working at all.
       var r;
       var rlen;
@@ -1016,8 +1020,8 @@ export default function Core(rootElement, userSettings) {
                   var orgValueSchema = duckSchema(Array.isArray(orgValue) ? orgValue : orgValue[0] || orgValue);
                   var valueSchema = duckSchema(Array.isArray(value) ? value : value[0] || value);
 
-                  /* eslint-disable max-depth */
-                  if (isObjectEqual(orgValueSchema, valueSchema)) {
+                  // Allow overwriting values with the same object-based schema or any array-based schema.
+                  if (isObjectEqual(orgValueSchema, valueSchema) || Array.isArray(orgValueSchema) && Array.isArray(valueSchema)) {
                     value = deepClone(value);
                   } else {
                     pushData = false;
@@ -1101,6 +1105,16 @@ export default function Core(rootElement, userSettings) {
     instance.runHooks('init');
     this.forceFullRender = true; // used when data was changed
     this.view.render();
+
+    // Run the logic only if it's the table's initialization and the root element is not visible.
+    if (!!firstRun && instance.rootElement.offsetParent === null) {
+      observeVisibilityChangeOnce(instance.rootElement, function () {
+        // Update the spreader size cache before rendering.
+        instance.view._wt.wtOverlays.updateLastSpreaderSize();
+        instance.render();
+        instance.view.adjustElementsSize();
+      });
+    }
     if (_typeof(firstRun) === 'object') {
       instance.runHooks('afterChange', firstRun[0], firstRun[1]);
       firstRun = false;
@@ -1254,9 +1268,7 @@ export default function Core(rootElement, userSettings) {
               source: source
             }),
             numberOfCreatedRows = _datamap$createRow2.delta;
-          if (numberOfCreatedRows >= 1) {
-            metaManager.createRow(null, numberOfCreatedRows);
-          } else {
+          if (numberOfCreatedRows === 0) {
             skipThisChange = true;
             break;
           }
@@ -1268,9 +1280,7 @@ export default function Core(rootElement, userSettings) {
               source: source
             }),
             numberOfCreatedColumns = _datamap$createCol2.delta;
-          if (numberOfCreatedColumns >= 1) {
-            metaManager.createColumn(null, numberOfCreatedColumns);
-          } else {
+          if (numberOfCreatedColumns === 0) {
             skipThisChange = true;
             break;
           }
@@ -2095,6 +2105,7 @@ export default function Core(rootElement, userSettings) {
       dataSource: dataSource,
       internalSource: 'updateData',
       source: source,
+      metaManager: metaManager,
       firstRun: firstRun
     });
   };
@@ -2137,6 +2148,7 @@ export default function Core(rootElement, userSettings) {
       dataSource: dataSource,
       internalSource: 'loadData',
       source: source,
+      metaManager: metaManager,
       firstRun: firstRun
     });
   };
@@ -3119,16 +3131,15 @@ export default function Core(rootElement, userSettings) {
   this.isColumnModificationAllowed = function () {
     return !(instance.dataType === 'object' || tableMeta.columns);
   };
-  var rendererLookup = cellMethodLookupFactory('renderer');
 
   /**
    * Returns the cell renderer function by given `row` and `column` arguments.
    *
    * @memberof Core#
    * @function getCellRenderer
-   * @param {number|object} row Visual row index or cell meta object (see {@link Core#getCellMeta}).
+   * @param {number|object} rowOrMeta Visual row index or cell meta object (see {@link Core#getCellMeta}).
    * @param {number} column Visual column index.
-   * @returns {Function} The renderer function.
+   * @returns {Function} Returns the renderer function.
    * @example
    * ```js
    * // Get cell renderer using `row` and `column` coordinates.
@@ -3137,8 +3148,12 @@ export default function Core(rootElement, userSettings) {
    * hot.getCellRenderer(hot.getCellMeta(1, 1));
    * ```
    */
-  this.getCellRenderer = function (row, column) {
-    return getRenderer(rendererLookup.call(this, row, column));
+  this.getCellRenderer = function (rowOrMeta, column) {
+    var cellRenderer = typeof rowOrMeta === 'number' ? instance.getCellMeta(rowOrMeta, column).renderer : rowOrMeta.renderer;
+    if (typeof cellRenderer === 'string') {
+      return getRenderer(cellRenderer);
+    }
+    return isUndefined(cellRenderer) ? getRenderer('text') : cellRenderer;
   };
 
   /**
@@ -3146,9 +3161,9 @@ export default function Core(rootElement, userSettings) {
    *
    * @memberof Core#
    * @function getCellEditor
-   * @param {number} row Visual row index or cell meta object (see {@link Core#getCellMeta}).
+   * @param {number} rowOrMeta Visual row index or cell meta object (see {@link Core#getCellMeta}).
    * @param {number} column Visual column index.
-   * @returns {Function} The editor class.
+   * @returns {Function|boolean} Returns the editor class or `false` is cell editor is disabled.
    * @example
    * ```js
    * // Get cell editor class using `row` and `column` coordinates.
@@ -3157,31 +3172,36 @@ export default function Core(rootElement, userSettings) {
    * hot.getCellEditor(hot.getCellMeta(1, 1));
    * ```
    */
-  this.getCellEditor = cellMethodLookupFactory('editor');
-  var validatorLookup = cellMethodLookupFactory('validator');
+  this.getCellEditor = function (rowOrMeta, column) {
+    var cellEditor = typeof rowOrMeta === 'number' ? instance.getCellMeta(rowOrMeta, column).editor : rowOrMeta.editor;
+    if (typeof cellEditor === 'string') {
+      return getEditor(cellEditor);
+    }
+    return isUndefined(cellEditor) ? getEditor('text') : cellEditor;
+  };
 
   /**
    * Returns the cell validator by `row` and `column`.
    *
    * @memberof Core#
    * @function getCellValidator
-   * @param {number|object} row Visual row index or cell meta object (see {@link Core#getCellMeta}).
+   * @param {number|object} rowOrMeta Visual row index or cell meta object (see {@link Core#getCellMeta}).
    * @param {number} column Visual column index.
    * @returns {Function|RegExp|undefined} The validator function.
    * @example
    * ```js
-   * // Get cell valiator using `row` and `column` coordinates.
+   * // Get cell validator using `row` and `column` coordinates.
    * hot.getCellValidator(1, 1);
-   * // Get cell valiator using cell meta object.
+   * // Get cell validator using cell meta object.
    * hot.getCellValidator(hot.getCellMeta(1, 1));
    * ```
    */
-  this.getCellValidator = function (row, column) {
-    var validator = validatorLookup.call(this, row, column);
-    if (typeof validator === 'string') {
-      validator = getValidator(validator);
+  this.getCellValidator = function (rowOrMeta, column) {
+    var cellValidator = typeof rowOrMeta === 'number' ? instance.getCellMeta(rowOrMeta, column).validator : rowOrMeta.validator;
+    if (typeof cellValidator === 'string') {
+      return getValidator(cellValidator);
     }
-    return validator;
+    return cellValidator;
   };
 
   /**
@@ -3368,54 +3388,84 @@ export default function Core(rootElement, userSettings) {
   };
 
   /**
-   * Returns an array of column headers (in string format, if they are enabled). If param `column` is given, it
-   * returns the header at the given column.
+   * Gets the values of column headers (if column headers are [enabled](@/api/options.md#colheaders)).
+   *
+   * To get an array with the values of all
+   * [bottom-most](@/guides/cell-features/clipboard.md#copy-with-headers) column headers,
+   * call `getColHeader()` with no arguments.
+   *
+   * To get the value of the bottom-most header of a specific column, use the `column` parameter.
+   *
+   * To get the value of a [specific-level](@/guides/columns/column-groups.md) header
+   * of a specific column, use the `column` and `headerLevel` parameters.
+   *
+   * Read more:
+   * - [Guides: Column groups](@/guides/columns/column-groups.md)
+   * - [Options: `colHeaders`](@/api/options.md#colheaders)
+   * - [Guides: Copy with headers](@/guides/cell-features/clipboard.md#copy-with-headers)
+   *
+   * ```js
+   * // get the contents of all bottom-most column headers
+   * hot.getColHeader();
+   *
+   * // get the contents of the bottom-most header of a specific column
+   * hot.getColHeader(5);
+   *
+   * // get the contents of a specific column header at a specific level
+   * hot.getColHeader(5, -2);
+   * ```
    *
    * @memberof Core#
    * @function getColHeader
-   * @param {number} [column] Visual column index.
+   * @param {number} [column] A visual column index.
+   * @param {number} [headerLevel=-1] (Since 12.3.0) Header level index. Accepts positive (0 to n)
+   *                                  and negative (-1 to -n) values. For positive values, 0 points to the
+   *                                  topmost header. For negative values, -1 points to the bottom-most
+   *                                  header (the header closest to the cells).
    * @fires Hooks#modifyColHeader
-   * @returns {Array|string|number} The column header(s).
+   * @fires Hooks#modifyColumnHeaderValue
+   * @returns {Array|string|number} Column header values.
    */
   this.getColHeader = function (column) {
+    var headerLevel = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : -1;
     var columnIndex = instance.runHooks('modifyColHeader', column);
-    var result = tableMeta.colHeaders;
     if (columnIndex === void 0) {
       var out = [];
       var ilen = instance.countCols();
       for (var i = 0; i < ilen; i++) {
         out.push(instance.getColHeader(i));
       }
-      result = out;
-    } else {
-      var translateVisualIndexToColumns = function translateVisualIndexToColumns(visualColumnIndex) {
-        var arr = [];
-        var columnsLen = instance.countCols();
-        var index = 0;
-        for (; index < columnsLen; index++) {
-          if (isFunction(tableMeta.columns) && tableMeta.columns(index)) {
-            arr.push(index);
-          }
+      return out;
+    }
+    var result = tableMeta.colHeaders;
+    var translateVisualIndexToColumns = function translateVisualIndexToColumns(visualColumnIndex) {
+      var arr = [];
+      var columnsLen = instance.countCols();
+      var index = 0;
+      for (; index < columnsLen; index++) {
+        if (isFunction(tableMeta.columns) && tableMeta.columns(index)) {
+          arr.push(index);
         }
-        return arr[visualColumnIndex];
-      };
-      var physicalColumn = instance.toPhysicalColumn(columnIndex);
-      var prop = translateVisualIndexToColumns(physicalColumn);
-      if (tableMeta.colHeaders === false) {
-        result = null;
-      } else if (tableMeta.columns && isFunction(tableMeta.columns) && tableMeta.columns(prop) && tableMeta.columns(prop).title) {
-        result = tableMeta.columns(prop).title;
-      } else if (tableMeta.columns && tableMeta.columns[physicalColumn] && tableMeta.columns[physicalColumn].title) {
-        result = tableMeta.columns[physicalColumn].title;
-      } else if (Array.isArray(tableMeta.colHeaders) && tableMeta.colHeaders[physicalColumn] !== void 0) {
-        result = tableMeta.colHeaders[physicalColumn];
-      } else if (isFunction(tableMeta.colHeaders)) {
-        result = tableMeta.colHeaders(physicalColumn);
-      } else if (tableMeta.colHeaders && typeof tableMeta.colHeaders !== 'string' && typeof tableMeta.colHeaders !== 'number') {
-        result = spreadsheetColumnLabel(columnIndex); // see #1458
       }
-    }
-
+      return arr[visualColumnIndex];
+    };
+    var physicalColumn = instance.toPhysicalColumn(columnIndex);
+    var prop = translateVisualIndexToColumns(physicalColumn);
+    if (tableMeta.colHeaders === false) {
+      result = null;
+    } else if (tableMeta.columns && isFunction(tableMeta.columns) && tableMeta.columns(prop) && tableMeta.columns(prop).title) {
+      result = tableMeta.columns(prop).title;
+    } else if (tableMeta.columns && tableMeta.columns[physicalColumn] && tableMeta.columns[physicalColumn].title) {
+      result = tableMeta.columns[physicalColumn].title;
+    } else if (Array.isArray(tableMeta.colHeaders) && tableMeta.colHeaders[physicalColumn] !== void 0) {
+      result = tableMeta.colHeaders[physicalColumn];
+    } else if (isFunction(tableMeta.colHeaders)) {
+      result = tableMeta.colHeaders(physicalColumn);
+    } else if (tableMeta.colHeaders && typeof tableMeta.colHeaders !== 'string' && typeof tableMeta.colHeaders !== 'number') {
+      result = spreadsheetColumnLabel(columnIndex); // see #1458
+    }
+
+    result = instance.runHooks('modifyColumnHeaderValue', result, column, headerLevel);
     return result;
   };
 
@@ -3513,14 +3563,29 @@ export default function Core(rootElement, userSettings) {
   };
 
   /**
-   * Returns the row height.
+   * Returns a row's height, as recognized by Handsontable.
    *
-   * Mind that this method is different from the [AutoRowSize](@/api/autoRowSize.md) plugin's [`getRowHeight()`](@/api/autoRowSize.md#getrowheight) method.
+   * Depending on your configuration, the method returns (in order of priority):
+   *   1. The row height set by the [`ManualRowResize`](@/api/manualRowResize.md) plugin
+   *     (if the plugin is enabled).
+   *   2. The row height set by the [`rowHeights`](@/api/options.md#rowheights) configuration option
+   *     (if the option is set).
+   *   3. The row height as measured in the DOM by the [`AutoRowSize`](@/api/autoRowSize.md) plugin
+   *     (if the plugin is enabled).
+   *   4. `undefined`, if neither [`ManualRowResize`](@/api/manualRowResize.md),
+   *     nor [`rowHeights`](@/api/options.md#rowheights),
+   *     nor [`AutoRowSize`](@/api/autoRowSize.md) is used.
+   *
+   * The height returned includes 1 px of the row's bottom border.
+   *
+   * Mind that this method is different from the
+   * [`getRowHeight()`](@/api/autoRowSize.md#getrowheight) method
+   * of the [`AutoRowSize`](@/api/autoRowSize.md) plugin.
    *
    * @memberof Core#
    * @function getRowHeight
-   * @param {number} row Visual row index.
-   * @returns {number} The given row's height.
+   * @param {number} row A visual row index.
+   * @returns {number|undefined} The height of the specified row, in pixels.
    * @fires Hooks#modifyRowHeight
    */
   this.getRowHeight = function (row) {
@@ -3692,35 +3757,48 @@ export default function Core(rootElement, userSettings) {
   };
 
   /**
-   * Select cell specified by `row` and `column` values or a range of cells finishing at `endRow`, `endCol`. If the table
-   * was configured to support data column properties that properties can be used to making a selection.
+   * Select a single cell, or a single range of adjacent cells.
+   *
+   * To select a cell, pass its visual row and column indexes, for example: `selectCell(2, 4)`.
    *
-   * By default, viewport will be scrolled to the selection. After the `selectCell` method had finished, the instance
-   * will be listening to keyboard input on the document.
+   * To select a range, pass the visual indexes of the first and last cell in the range, for example: `selectCell(2, 4, 3, 5)`.
+   *
+   * If your columns have properties, you can pass those properties' values instead of column indexes, for example: `selectCell(2, 'first_name')`.
+   *
+   * By default, `selectCell()` also:
+   *  - Scrolls the viewport to the newly-selected cells.
+   *  - Switches the keyboard focus to Handsontable (by calling Handsontable's [`listen()`](#listen) method).
    *
    * @example
    * ```js
    * // select a single cell
    * hot.selectCell(2, 4);
-   * // select a single cell using column property
-   * hot.selectCell(2, 'address');
+   *
    * // select a range of cells
    * hot.selectCell(2, 4, 3, 5);
-   * // select a range of cells using column properties
-   * hot.selectCell(2, 'address', 3, 'phone_number');
-   * // select a range of cells without scrolling to them
-   * hot.selectCell(2, 'address', 3, 'phone_number', false);
+   *
+   * // select a single cell, using a column property
+   * hot.selectCell(2, 'first_name');
+   *
+   * // select a range of cells, using column properties
+   * hot.selectCell(2, 'first_name', 3, 'last_name');
+   *
+   * // select a range of cells, without scrolling to them
+   * hot.selectCell(2, 4, 3, 5, false);
+   *
+   * // select a range of cells, without switching the keyboard focus to Handsontable
+   * hot.selectCell(2, 4, 3, 5, null, false);
    * ```
    *
    * @memberof Core#
    * @function selectCell
-   * @param {number} row Visual row index.
-   * @param {number|string} column Visual column index or column property.
-   * @param {number} [endRow] Visual end row index (if selecting a range).
-   * @param {number|string} [endColumn] Visual end column index or column property (if selecting a range).
-   * @param {boolean} [scrollToCell=true] If `true`, the viewport will be scrolled to the selection.
-   * @param {boolean} [changeListener=true] If `false`, Handsontable will not change keyboard events listener to himself.
-   * @returns {boolean} `true` if selection was successful, `false` otherwise.
+   * @param {number} row A visual row index.
+   * @param {number|string} column A visual column index (`number`), or a column property's value (`string`).
+   * @param {number} [endRow] If selecting a range: the visual row index of the last cell in the range.
+   * @param {number|string} [endColumn] If selecting a range: the visual column index (or a column property's value) of the last cell in the range.
+   * @param {boolean} [scrollToCell=true] `true`: scroll the viewport to the newly-selected cells. `false`: keep the previous viewport.
+   * @param {boolean} [changeListener=true] `true`: switch the keyboard focus to Handsontable. `false`: keep the previous keyboard focus.
+   * @returns {boolean} `true`: the selection was successful, `false`: the selection failed.
    */
   this.selectCell = function (row, column, endRow, endColumn) {
     var scrollToCell = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : true;
@@ -3732,24 +3810,48 @@ export default function Core(rootElement, userSettings) {
   };
 
   /**
-   * 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 which are the same as that
-   * produces by `getSelected` and `getSelectedRange` methods.
+   * Select multiple cells or ranges of cells, adjacent or non-adjacent.
+   *
+   * You can pass one of the below:
+   * - An array of arrays (which matches the output of Handsontable's [`getSelected()`](#getselected) method).
+   * - An array of [`CellRange`](@/api/cellRange.md) objects (which matches the output of Handsontable's [`getSelectedRange()`](#getselectedrange) method).
+   *
+   * To select multiple cells, pass the visual row and column indexes of each cell, for example: `hot.selectCells([[1, 1], [5, 5]])`.
+   *
+   * To select multiple ranges, pass the visual indexes of the first and last cell in each range, for example: `hot.selectCells([[1, 1, 2, 2], [6, 2, 0, 2]])`.
    *
-   * By default, viewport will be scrolled to selection. After the `selectCells` method had finished, the instance
-   * will be listening to keyboard input on the document.
+   * If your columns have properties, you can pass those properties' values instead of column indexes, for example: `hot.selectCells([[1, 'first_name'], [5, 'last_name']])`.
+   *
+   * By default, `selectCell()` also:
+   *  - Scrolls the viewport to the newly-selected cells.
+   *  - Switches the keyboard focus to Handsontable (by calling Handsontable's [`listen()`](#listen) method).
    *
    * @example
    * ```js
-   * // Using an array of arrays.
+   * // select non-adjacent cells
+   * hot.selectCells([[1, 1], [5, 5], [10, 10]]);
+   *
+   * // select non-adjacent ranges of cells
+   * hot.selectCells([[1, 1, 2, 2], [10, 10, 20, 20]]);
+   *
+   * // select cells and ranges of cells
    * hot.selectCells([[1, 1, 2, 2], [3, 3], [6, 2, 0, 2]]);
-   * // Using an array of arrays with defined columns as props.
+   *
+   * // select cells, using column properties
    * hot.selectCells([[1, 'id', 2, 'first_name'], [3, 'full_name'], [6, 'last_name', 0, 'first_name']]);
-   * // Using an array of CellRange objects (produced by `.getSelectedRange()` method).
+   *
+   * // select multiple ranges, using an array of `CellRange` objects
    * const selected = hot.getSelectedRange();
    *
    * selected[0].from.row = 0;
    * selected[0].from.col = 0;
+   * selected[0].to.row = 5;
+   * selected[0].to.col = 5;
+   *
+   * selected[1].from.row = 10;
+   * selected[1].from.col = 10;
+   * selected[1].to.row = 20;
+   * selected[1].to.col = 20;
    *
    * hot.selectCells(selected);
    * ```
@@ -3757,12 +3859,12 @@ export default function Core(rootElement, userSettings) {
    * @memberof Core#
    * @since 0.38.0
    * @function selectCells
-   * @param {Array[]|CellRange[]} coords Visual coords passed as an array of array (`[[rowStart, columnStart, rowEnd, columnEnd], ...]`)
-   *                                     the same format as `getSelected` method returns or as an CellRange objects
-   *                                     which is the same format what `getSelectedRange` method returns.
-   * @param {boolean} [scrollToCell=true] If `true`, the viewport will be scrolled to the selection.
-   * @param {boolean} [changeListener=true] If `false`, Handsontable will not change keyboard events listener to himself.
-   * @returns {boolean} `true` if selection was successful, `false` otherwise.
+   * @param {Array[]|CellRange[]} coords Visual coordinates,
+   * passed either as an array of arrays (`[[rowStart, columnStart, rowEnd, columnEnd], ...]`)
+   * or as an array of [`CellRange`](@/api/cellRange.md) objects.
+   * @param {boolean} [scrollToCell=true] `true`: scroll the viewport to the newly-selected cells. `false`: keep the previous viewport.
+   * @param {boolean} [changeListener=true] `true`: switch the keyboard focus to Handsontable. `false`: keep the previous keyboard focus.
+   * @returns {boolean} `true`: the selection was successful, `false`: the selection failed.
    */
   this.selectCells = function () {
     var coords = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [[]];
@@ -3842,13 +3944,23 @@ export default function Core(rootElement, userSettings) {
   };
 
   /**
-   * Select the whole table. The previous selection will be overwritten.
+   * Select the whole table.
+   *
+   * The previous selection is overwritten.
+   *
+   * ```js
+   * // select all cells in the table, including all headers
+   * hot.selectAll();
+   *
+   * // select all cells in the table, without headers
+   * hot.selectAll(false);
+   * ```
    *
    * @since 0.38.2
    * @memberof Core#
    * @function selectAll
-   * @param {boolean} [includeHeaders=true] `true` If the selection should include the row, column and corner headers,
-   * `false` otherwise.
+   * @param {boolean} [includeHeaders=true] `true`: include all row, column and corner headers.
+   * `false`: don't include any headers.
    */
   this.selectAll = function () {
     var includeHeaders = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;