handsontable 12.2.0 → 12.3.0-next-bb1a7c2-20221208

package/core.js

@@ -43,7 +43,8 @@ var _array = require("./helpers/array");
 var _parseTable = require("./utils/parseTable");
 var _registry = require("./plugins/registry");
 var _registry2 = require("./renderers/registry");
-var _registry3 = require("./validators/registry");
+var _registry3 = require("./editors/registry");
+var _registry4 = require("./validators/registry");
 var _string = require("./helpers/string");
 var _number = require("./helpers/number");
 var _tableView = _interopRequireDefault(require("./tableView"));
@@ -53,7 +54,7 @@ var _translations = require("./translations");
 var _rootInstance = require("./utils/rootInstance");
 var _src = require("./3rdparty/walkontable/src");
 var _pluginHooks = _interopRequireDefault(require("./pluginHooks"));
-var _registry4 = require("./i18n/registry");
+var _registry5 = require("./i18n/registry");
 var _utils = require("./i18n/utils");
 var _selection = require("./selection");
 var _dataMap = require("./dataMap");
@@ -65,7 +66,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."); }
@@ -85,37 +86,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');
  * ```
  * :::
  *
@@ -229,7 +234,7 @@ function Core(rootElement, userSettings) {
   this.getDirectionFactor = function () {
     return instance.isLtr() ? 1 : -1;
   };
-  userSettings.language = (0, _registry4.getValidLanguageCode)(userSettings.language);
+  userSettings.language = (0, _registry5.getValidLanguageCode)(userSettings.language);
   var metaManager = new _dataMap.MetaManager(instance, userSettings, [_dataMap.DynamicCellMetaMod, _dataMap.ExtendMetaPropertiesMod]);
   var tableMeta = metaManager.getTableMeta();
   var globalMeta = metaManager.getGlobalMeta();
@@ -446,7 +451,8 @@ 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;
@@ -521,7 +527,6 @@ 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;
@@ -577,7 +582,6 @@ 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
@@ -640,7 +644,6 @@ 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) {
@@ -686,7 +689,6 @@ 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);
@@ -720,7 +722,8 @@ 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;
@@ -846,7 +849,8 @@ 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;
@@ -1021,8 +1025,8 @@ function Core(rootElement, userSettings) {
                   var orgValueSchema = (0, _object.duckSchema)(Array.isArray(orgValue) ? orgValue : orgValue[0] || orgValue);
                   var valueSchema = (0, _object.duckSchema)(Array.isArray(value) ? value : value[0] || value);
 
-                  /* eslint-disable max-depth */
-                  if ((0, _object.isObjectEqual)(orgValueSchema, valueSchema)) {
+                  // Allow overwriting values with the same object-based schema or any array-based schema.
+                  if ((0, _object.isObjectEqual)(orgValueSchema, valueSchema) || Array.isArray(orgValueSchema) && Array.isArray(valueSchema)) {
                     value = (0, _object.deepClone)(value);
                   } else {
                     pushData = false;
@@ -1054,7 +1058,7 @@ function Core(rootElement, userSettings) {
    */
   function setLanguage(languageCode) {
     var normalizedLanguageCode = (0, _utils.normalizeLanguageCode)(languageCode);
-    if ((0, _registry4.hasLanguageDictionary)(normalizedLanguageCode)) {
+    if ((0, _registry5.hasLanguageDictionary)(normalizedLanguageCode)) {
       instance.runHooks('beforeLanguageChange', normalizedLanguageCode);
       globalMeta.language = normalizedLanguageCode;
       instance.runHooks('afterLanguageChange', normalizedLanguageCode);
@@ -1106,6 +1110,16 @@ 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) {
+      (0, _element.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;
@@ -1259,9 +1273,7 @@ function Core(rootElement, userSettings) {
               source: source
             }),
             numberOfCreatedRows = _datamap$createRow2.delta;
-          if (numberOfCreatedRows >= 1) {
-            metaManager.createRow(null, numberOfCreatedRows);
-          } else {
+          if (numberOfCreatedRows === 0) {
             skipThisChange = true;
             break;
           }
@@ -1273,9 +1285,7 @@ function Core(rootElement, userSettings) {
               source: source
             }),
             numberOfCreatedColumns = _datamap$createCol2.delta;
-          if (numberOfCreatedColumns >= 1) {
-            metaManager.createColumn(null, numberOfCreatedColumns);
-          } else {
+          if (numberOfCreatedColumns === 0) {
             skipThisChange = true;
             break;
           }
@@ -2100,6 +2110,7 @@ function Core(rootElement, userSettings) {
       dataSource: dataSource,
       internalSource: 'updateData',
       source: source,
+      metaManager: metaManager,
       firstRun: firstRun
     });
   };
@@ -2142,6 +2153,7 @@ function Core(rootElement, userSettings) {
       dataSource: dataSource,
       internalSource: 'loadData',
       source: source,
+      metaManager: metaManager,
       firstRun: firstRun
     });
   };
@@ -3124,16 +3136,15 @@ function Core(rootElement, userSettings) {
   this.isColumnModificationAllowed = function () {
     return !(instance.dataType === 'object' || tableMeta.columns);
   };
-  var rendererLookup = (0, _data.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.
@@ -3142,8 +3153,12 @@ function Core(rootElement, userSettings) {
    * hot.getCellRenderer(hot.getCellMeta(1, 1));
    * ```
    */
-  this.getCellRenderer = function (row, column) {
-    return (0, _registry2.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 (0, _registry2.getRenderer)(cellRenderer);
+    }
+    return (0, _mixed.isUndefined)(cellRenderer) ? (0, _registry2.getRenderer)('text') : cellRenderer;
   };
 
   /**
@@ -3151,9 +3166,9 @@ 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.
@@ -3162,31 +3177,36 @@ function Core(rootElement, userSettings) {
    * hot.getCellEditor(hot.getCellMeta(1, 1));
    * ```
    */
-  this.getCellEditor = (0, _data.cellMethodLookupFactory)('editor');
-  var validatorLookup = (0, _data.cellMethodLookupFactory)('validator');
+  this.getCellEditor = function (rowOrMeta, column) {
+    var cellEditor = typeof rowOrMeta === 'number' ? instance.getCellMeta(rowOrMeta, column).editor : rowOrMeta.editor;
+    if (typeof cellEditor === 'string') {
+      return (0, _registry3.getEditor)(cellEditor);
+    }
+    return (0, _mixed.isUndefined)(cellEditor) ? (0, _registry3.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 = (0, _registry3.getValidator)(validator);
+  this.getCellValidator = function (rowOrMeta, column) {
+    var cellValidator = typeof rowOrMeta === 'number' ? instance.getCellMeta(rowOrMeta, column).validator : rowOrMeta.validator;
+    if (typeof cellValidator === 'string') {
+      return (0, _registry4.getValidator)(cellValidator);
     }
-    return validator;
+    return cellValidator;
   };
 
   /**
@@ -3373,54 +3393,84 @@ 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 ((0, _function.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 ((0, _function.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 && (0, _function.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 ((0, _function.isFunction)(tableMeta.colHeaders)) {
-        result = tableMeta.colHeaders(physicalColumn);
-      } else if (tableMeta.colHeaders && typeof tableMeta.colHeaders !== 'string' && typeof tableMeta.colHeaders !== 'number') {
-        result = (0, _data.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 && (0, _function.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 ((0, _function.isFunction)(tableMeta.colHeaders)) {
+      result = tableMeta.colHeaders(physicalColumn);
+    } else if (tableMeta.colHeaders && typeof tableMeta.colHeaders !== 'string' && typeof tableMeta.colHeaders !== 'number') {
+      result = (0, _data.spreadsheetColumnLabel)(columnIndex); // see #1458
+    }
+
+    result = instance.runHooks('modifyColumnHeaderValue', result, column, headerLevel);
     return result;
   };
 
@@ -3518,14 +3568,29 @@ 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) {
@@ -3697,35 +3762,48 @@ 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;
@@ -3737,24 +3815,48 @@ 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);
    * ```
@@ -3762,12 +3864,12 @@ 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] : [[]];
@@ -3847,13 +3949,23 @@ 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;
@@ -4169,7 +4281,7 @@ function Core(rootElement, userSettings) {
    * @returns {string}
    */
   this.getTranslatedPhrase = function (dictionaryKey, extraArguments) {
-    return (0, _registry4.getTranslatedPhrase)(tableMeta.language, dictionaryKey, extraArguments);
+    return (0, _registry5.getTranslatedPhrase)(tableMeta.language, dictionaryKey, extraArguments);
   };
 
   /**