handsontable 0.0.0-next-3e92a2d-20221130 → 0.0.0-next-4a99ab8-20221201

package/3rdparty/walkontable/src/cell/range.js

@@ -24,11 +24,24 @@ function _classPrivateFieldSet(receiver, privateMap, value) { var descriptor = _
 function _classExtractFieldDescriptor(receiver, privateMap, action) { if (!privateMap.has(receiver)) { throw new TypeError("attempted to " + action + " private field on non-instance"); } return privateMap.get(receiver); }
 function _classApplyDescriptorSet(receiver, descriptor, value) { if (descriptor.set) { descriptor.set.call(receiver, value); } else { if (!descriptor.writable) { throw new TypeError("attempted to set read only private field"); } descriptor.value = value; } }
 var _isRtl = /*#__PURE__*/new WeakMap();
+/* eslint-disable jsdoc/require-description-complete-sentence */
 /**
- * CellRange holds cell coordinates as {@link CellCoords} instances. This object represent unit of the selection layer which
- * can contains multiple contiguous cells or single cell.
+ * @description
  *
- * @util
+ * The `CellRange` class holds a set of cell coordinates ([`CellCoords`](@/api/cellCoords.md) instances)
+ * that form a [selection range](@/guides/cell-features/selection.md#select-ranges).
+ *
+ * A single `CellRange` instance represents a single unit of selection
+ * that contains either a single cell or multiple adjacent cells.
+ *
+ * To import the `CellRange` class:
+ *
+ * ```js
+ * import Handsontable, { CellRange } from '/handsontable';
+ *
+ * // or, using modules
+ * import Handsontable, { CellRange } from '/handsontable/base';
+ * ```
  */
 var CellRange = /*#__PURE__*/function () {
   /**
@@ -36,6 +49,7 @@ var CellRange = /*#__PURE__*/function () {
    * when you press Enter. The highlight cannot point to headers (negative values) so its
    * coordinates object is normalized while assigning.
    *
+   * @private
    * @type {CellCoords}
    */
 
@@ -43,12 +57,14 @@ var CellRange = /*#__PURE__*/function () {
    * Usually the same as highlight, but in Excel there is distinction - one can change
    * highlight within a selection.
    *
+   * @private
    * @type {CellCoords}
    */
 
   /**
    * End selection.
    *
+   * @private
    * @type {CellCoords}
    */
 
@@ -75,7 +91,7 @@ var CellRange = /*#__PURE__*/function () {
   }
 
   /**
-   * Set the new coordinates for highlighting selection.
+   * Highlights cell selection at the `coords` coordinates.
    *
    * @param {CellCoords} coords Coordinates to use.
    * @returns {CellRange}
@@ -88,7 +104,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Set the new coordinates where selection starts from.
+     * Sets the `coords` coordinates as the start of your range.
      *
      * @param {CellCoords} coords Coordinates to use.
      * @returns {CellRange}
@@ -101,7 +117,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Set new coordinates where selection ends from.
+     * Sets the `coords` coordinates as the end of your range.
      *
      * @param {CellCoords} coords Coordinates to use.
      * @returns {CellRange}
@@ -114,9 +130,12 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if given coordinates are valid in context of a given Walkontable instance.
+     * Checks if the coordinates in your `CellRange` instance are valid
+     * in the context of a given Walkontable instance.
      *
-     * @param {Walkontable} wot The Walkontable instance.
+     * See the [`isValid()`](@/api/cellCoords.md#isvalid) method of the [`CellCoords`](@/api/cellCoords.md) class.
+     *
+     * @param {Walkontable} wot A Walkontable instance.
      * @returns {boolean}
      */
   }, {
@@ -126,7 +145,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if this cell range is restricted to one cell.
+     * Checks if your range is just a single cell.
      *
      * @returns {boolean}
      */
@@ -137,7 +156,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Returns selected range height (in number of rows including rows' headers).
+     * Returns the height of your range (as a number of rows, including row headers).
      *
      * @returns {number}
      */
@@ -148,7 +167,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Returns selected range width (in number of columns including columns' headers).
+     * Returns the width of your range (as a number of columns, including column headers).
      *
      * @returns {number}
      */
@@ -159,7 +178,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Returns selected range height (in number of rows excluding rows' headers).
+     * Returns the height of your range (as a number of rows, excluding row headers).
      *
      * @returns {number}
      */
@@ -176,7 +195,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Returns selected range width (in number of columns excluding columns' headers).
+     * Returns the width of your range (as a number of columns, excluding column headers).
      *
      * @returns {number}
      */
@@ -193,7 +212,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Returns the number of cells within the range (excluding the column and row headers, if selected).
+     * Returns the number of cells within your range (excluding column and row headers).
      *
      * @returns {number}
      */
@@ -204,9 +223,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if given cell coordinates are within `from` and `to` cell coordinates of this range.
+     * Checks if another set of coordinates (`cellCoords`)
+     * is within the `from` and `to` coordinates of your range.
      *
-     * @param {CellCoords} cellCoords The cell coordinates to check.
+     * @param {CellCoords} cellCoords Coordinates to check.
      * @returns {boolean}
      */
   }, {
@@ -220,9 +240,9 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if given range is within of this range.
+     * Checks if another range (`cellRange`) is within your range.
      *
-     * @param {CellRange} cellRange The cells range to check.
+     * @param {CellRange} cellRange A range to check.
      * @returns {boolean}
      */
   }, {
@@ -232,9 +252,9 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if given range is equal to this range.
+     * Checks if another range (`cellRange`) is equal to your range.
      *
-     * @param {CellRange} cellRange The cells range to check.
+     * @param {CellRange} cellRange A range to check.
      * @returns {boolean}
      */
   }, {
@@ -244,10 +264,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if tested range overlaps with the range. Range A is considered to to be overlapping with range B
-     * if intersection of A and B or B and A is not empty.
+     * Checks if another range (`cellRange`) overlaps your range.
+     *
+     * Range A overlaps range B if the intersection of A and B (or B and A) is not empty.
      *
-     * @param {CellRange} cellRange The cells range to check.
+     * @param {CellRange} cellRange A range to check.
      * @returns {boolean}
      */
   }, {
@@ -257,9 +278,9 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if tested coordinates are positioned in south-east from this cell range.
+     * Checks if another range (`cellRange`) is south-east of your range.
      *
-     * @param {CellRange} cellRange The cells range to check.
+     * @param {CellRange} cellRange A range to check.
      * @returns {boolean}
      */
   }, {
@@ -269,9 +290,9 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if tested coordinates are positioned in north-west from this cell range.
+     * Checks if another range (`cellRange`) is north-west of your range.
      *
-     * @param {CellRange} cellRange The cells range to check.
+     * @param {CellRange} cellRange A range to check.
      * @returns {boolean}
      */
   }, {
@@ -281,10 +302,12 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Returns `true` if the provided range is overlapping the current range horizontally (e.g. The current range's last
-     * column is 5 and the provided range's first column is 3).
+     * Checks if another range (`cellRange`) overlaps your range horizontally.
      *
-     * @param {CellRange} cellRange The cells range to check.
+     * For example: returns `true` if the last column of your range is `5`
+     * and the first column of the `cellRange` range is `3`.
+     *
+     * @param {CellRange} cellRange A range to check.
      * @returns {boolean}
      */
   }, {
@@ -294,10 +317,12 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Returns `true` if the provided range is overlapping the current range vertically (e.g. The current range's last
-     *  row is 5 and the provided range's first row is 3).
+     * Checks if another range (`cellRange`) overlaps your range vertically.
+     *
+     * For example: returns `true` if the last row of your range is `5`
+     * and the first row of the `cellRange` range is `3`.
      *
-     * @param {CellRange} cellRange The cells range to check.
+     * @param {CellRange} cellRange A range to check.
      * @returns {boolean}
      */
   }, {
@@ -307,9 +332,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Adds a cell to a range (only if exceeds corners of the range). Returns information if range was expanded.
+     * Adds a cell to your range, at `cellCoords` coordinates.
      *
-     * @param {CellCoords} cellCoords The cell coordinates.
+     * The `cellCoords` coordinates must exceed a corner of your range.
+     *
+     * @param {CellCoords} cellCoords A new cell's coordinates.
      * @returns {boolean}
      */
   }, {
@@ -326,9 +353,9 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Expand the current object by the range passed in the first argument.
+     * Expand your range with another range (`expandingRange`).
      *
-     * @param {CellRange} expandingRange Object extending the range.
+     * @param {CellRange} expandingRange A new range.
      * @returns {boolean}
      */
   }, {
@@ -418,7 +445,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the vertical direction of the range.
+     * Gets the vertical direction of the selection.
      *
      * @returns {string} Returns one of the values: `N-S` (north->south), `S-N` (south->north).
      */
@@ -429,7 +456,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the horizontal direction of the range.
+     * Gets the horizontal direction of the selection.
      *
      * @returns {string} Returns one of the values: `W-E` (west->east), `E-W` (east->west).
      */
@@ -440,7 +467,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Flip the direction vertically. (e.g. `NW-SE` changes to `SW-NE`).
+     * Flips the direction of your range vertically (e.g., `NW-SE` changes to `SW-NE`).
      */
   }, {
     key: "flipDirectionVertically",
@@ -465,7 +492,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Flip the direction horizontally. (e.g. `NW-SE` changes to `NE-SW`).
+     * Flips the direction of your range horizontally (e.g., `NW-SE` changes to `NE-SW`).
      */
   }, {
     key: "flipDirectionHorizontally",
@@ -490,8 +517,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the top left (in LTR) or top right (in RTL) corner coordinates of this range. If the corner contains
-     * header coordinates (negative values), the corner coordinates will be normalized to 0.
+     * Gets the top-left (in LTR) or top-right (in RTL) corner coordinates of your range.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the corner coordinates are normalized to `0`.
      *
      * @returns {CellCoords}
      */
@@ -502,8 +531,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the top left corner coordinates of this range, no matter if the code runs in LTR or RTL document mode.
-     * If the corner contains header coordinates (negative values), the corner coordinates will be normalized to 0.
+     * Gets the top-left corner coordinates of your range,
+     * both in the LTR and RTL layout direction.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the corner coordinates are normalized to `0`.
      *
      * @returns {CellCoords}
      */
@@ -514,8 +546,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the bottom right (in LTR) or bottom left (in RTL) corner coordinates of this range. If the corner contains
-     * header coordinates (negative values), the corner coordinates will be normalized to 0.
+     * Gets the bottom right (in LTR) or bottom left (in RTL) corner coordinates of your range.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the corner coordinates are normalized to `0`.
      *
      * @returns {CellCoords}
      */
@@ -526,8 +560,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the bottom right corner coordinates of this range, no matter if the code runs in LTR or RTL document mode.
-     * If the corner contains header coordinates (negative values), the corner coordinates will be normalized to 0.
+     * Gets the bottom right corner coordinates of your range,
+     * both in the LTR and RTL layout direction.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the corner coordinates are normalized to `0`.
      *
      * @returns {CellCoords}
      */
@@ -538,8 +575,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the top right (in LTR) or top left (in RTL) corner coordinates of this range. If the corner contains
-     * header coordinates (negative values), the corner coordinates will be normalized to 0.
+     * Gets the top right (in LTR) or top left (in RTL) corner coordinates of your range.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the corner coordinates are normalized to `0`.
      *
      * @returns {CellCoords}
      */
@@ -550,8 +589,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the top right corner coordinates of this range, no matter if the code runs in LTR or RTL document mode.
-     * If the corner contains header coordinates (negative values), the corner coordinates will be normalized to 0.
+     * Gets the top right corner coordinates of your range,
+     * both in the LTR and RTL layout direction.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the corner coordinates are normalized to `0`.
      *
      * @returns {CellCoords}
      */
@@ -562,8 +604,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the bottom left (in LTR) or bottom right (in RTL) corner coordinates of this range. If the corner
-     * contains header coordinates (negative values), the corner coordinates will be normalized to 0.
+     * Gets the bottom left (in LTR) or bottom right (in RTL) corner coordinates of your range.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the corner coordinates are normalized to `0`.
      *
      * @returns {CellCoords}
      */
@@ -574,8 +618,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the bottom left corner coordinates of this range, no matter if the code runs in LTR or RTL document mode.
-     * If the corner contains header coordinates (negative values), the corner coordinates will be normalized to 0.
+     * Gets the bottom left corner coordinates of your range,
+     * both in the LTR and RTL layout direction.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the corner coordinates are normalized to `0`.
      *
      * @returns {CellCoords}
      */
@@ -586,8 +633,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the top left (in LTR) or top right (in RTL) corner coordinates of this range. If the corner
-     * contains header coordinates (negative values), then the top and start coordinates will be pointed to that header.
+     * Gets the top left (in LTR) or top right (in RTL) corner coordinates of your range.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the top and start coordinates are pointed to that header.
      *
      * @returns {CellCoords}
      */
@@ -598,9 +647,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the top left corner coordinates of this range, no matter if the code runs in LTR or RTL document mode.
-     * If the corner contains header coordinates (negative values), then the top and left coordinates will be
-     * pointed to that header.
+     * Gets the top left corner coordinates of your range,
+     * both in the LTR and RTL layout direction.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the top and left coordinates are pointed to that header.
      *
      * @returns {CellCoords}
      */
@@ -611,8 +662,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the bottom right (in LTR) or bottom left (in RTL) corner coordinates of this range. If the corner
-     * contains header coordinates (negative values), then the top and start coordinates will be pointed to that header.
+     * Gets the bottom right (in LTR) or bottom left (in RTL) corner coordinates of your range.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the top and start coordinates are pointed to that header.
      *
      * @returns {CellCoords}
      */
@@ -623,9 +676,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the bottom right corner coordinates of this range, no matter if the code runs in LTR or RTL document mode.
-     * If the corner contains header coordinates (negative values), then the top and left coordinates will be
-     * pointed to that header.
+     * Gets the bottom right corner coordinates of your range,
+     * both in the LTR and RTL layout direction.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the top and left coordinates are pointed to that header.
      *
      * @returns {CellCoords}
      */
@@ -636,8 +691,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the top right (in LTR) or top left (in RTL) corner coordinates of this range. If the corner
-     * contains header coordinates (negative values), then the top and start coordinates will be pointed to that header.
+     * Gets the top right (in LTR) or top left (in RTL) corner coordinates of your range.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the top and start coordinates are pointed to that header.
      *
      * @returns {CellCoords}
      */
@@ -648,9 +705,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the top right corner coordinates of this range, no matter if the code runs in LTR or RTL document mode.
-     * If the corner contains header coordinates (negative values), then the top and left coordinates will be
-     * pointed to that header.
+     * Gets the top right corner coordinates of your range,
+     * both in the LTR and RTL layout direction.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the top and left coordinates are pointed to that header.
      *
      * @returns {CellCoords}
      */
@@ -661,8 +720,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the bottom left (in LTR) or bottom right (in RTL) corner coordinates of this range. If the corner
-     * contains header coordinates (negative values), then the top and start coordinates will be pointed to that header.
+     * Gets the bottom left (in LTR) or bottom right (in RTL) corner coordinates of your range.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the top and start coordinates are pointed to that header.
      *
      * @returns {CellCoords}
      */
@@ -673,9 +734,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets the bottom left corner coordinates of this range, no matter if the code runs in LTR or RTL document mode.
-     * If the corner contains header coordinates (negative values), then the top and left coordinates will be
-     * pointed to that header.
+     * Gets the bottom left corner coordinates of your range,
+     * both in the LTR and RTL layout direction.
+     *
+     * If the corner contains header coordinates (negative values),
+     * the top and left coordinates are pointed to that header.
      *
      * @returns {CellCoords}
      */
@@ -686,10 +749,10 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Checks if coordinates match to one of the 4th corners of this range.
+     * Checks if a set of coordinates (`coords`) matches one of the 4 corners of your range.
      *
-     * @param {CellCoords} coords Cell coordinates to check.
-     * @param {CellRange} [expandedRange] The cells range to compare with.
+     * @param {CellCoords} coords Coordinates to check.
+     * @param {CellRange} [expandedRange] A range to compare with.
      * @returns {boolean}
      */
   }, {
@@ -702,11 +765,13 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Gets coordinates of the corner which is opposite to the matched. When the passed coordinates matched to the
-     * bottom-right corner of this range then the coordinates for top-left will be returned.
+     * Gets the coordinates of a range corner opposite to the provided `coords`.
      *
-     * @param {CellCoords} coords Cell coordinates to check.
-     * @param {CellRange} [expandedRange] The cells range to compare with.
+     * For example: if the `coords` coordinates match the bottom-right corner of your range,
+     * the coordinates of the top-left corner of your range are returned.
+     *
+     * @param {CellCoords} coords Coordinates to check.
+     * @param {CellRange} [expandedRange] A range to compare with.
      * @returns {CellCoords}
      */
   }, {
@@ -745,8 +810,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * @param {CellRange} range The cells range to compare with.
-     * @returns {Array}
+     * Indicates which borders (top, right, bottom, left) are shared between
+     * your `CellRange`instance and another `range` that's within your range.
+     *
+     * @param {CellRange} range A range to compare with.
+     * @returns {Array<'top' | 'right' | 'bottom' | 'left'>}
      */
   }, {
     key: "getBordersSharedWith",
@@ -783,9 +851,9 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Get inner selected cell coords defined by this range.
+     * Gets the coordinates of the inner cells of your range.
      *
-     * @returns {Array}
+     * @returns {CellCoords[]}
      */
   }, {
     key: "getInner",
@@ -804,9 +872,9 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Get all selected cell coords defined by this range.
+     * Gets the coordinates of all cells of your range.
      *
-     * @returns {Array}
+     * @returns {CellCoords[]}
      */
   }, {
     key: "getAll",
@@ -829,10 +897,11 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Runs a callback function against all cells in the range. You can break the iteration by returning
-     * `false` in the callback function.
+     * Runs a callback function on all cells within your range.
      *
-     * @param {Function} callback The callback function.
+     * You can break the iteration by returning `false` in the callback function.
+     *
+     * @param {function(number, number): boolean} callback A callback function.
      */
   }, {
     key: "forAll",
@@ -850,7 +919,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Clones the range coordinates.
+     * Clones your `CellRange` instance.
      *
      * @returns {CellRange}
      */
@@ -861,10 +930,16 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Convert CellRange to literal object.
+     * Converts your `CellRange` instance into an object literal with the following properties:
+     *
+     * - `from`
+     *    - `row`
+     *    - `col`
+     * - `to`
+     *    - `row`
+     *    - `col`
      *
-     * @returns {object} Returns a literal object with `from` and `to` properties which each of that object
-     *                  contains `row` and `col` keys.
+     * @returns {{from: {row: number, col: number}, to: {row: number, col: number}}} An object literal with `from` and `to` properties.
      */
   }, {
     key: "toObject",
@@ -876,12 +951,14 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Creates and returns a new instance of the CellCoords object. The object automatically inherits
-     * the LTR/RTL flag from this CellRange instance.
+     * Creates and returns a new instance of the `CellCoords` class.
+     *
+     * The new `CellCoords` instance automatically inherits the LTR/RTL flag
+     * from your `CellRange` instance.
      *
      * @private
-     * @param {number} row The row index.
-     * @param {number} column The column index.
+     * @param {number} row A row index.
+     * @param {number} column A column index.
      * @returns {CellCoords}
      */
   }, {