handsontable 0.0.0-next-10cbf34-20221130 → 0.0.0-next-4a99ab8-20221201

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

@@ -18,11 +18,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; } }
 import CellCoords from "./../cell/coords.mjs";
+/* 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 _isRtl = /*#__PURE__*/new WeakMap();
 var CellRange = /*#__PURE__*/function () {
@@ -31,6 +44,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}
    */
 
@@ -38,12 +52,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}
    */
 
@@ -70,7 +86,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}
@@ -83,7 +99,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}
@@ -96,7 +112,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}
@@ -109,9 +125,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}
      */
   }, {
@@ -121,7 +140,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}
      */
@@ -132,7 +151,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}
      */
@@ -143,7 +162,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}
      */
@@ -154,7 +173,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}
      */
@@ -171,7 +190,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}
      */
@@ -188,7 +207,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}
      */
@@ -199,9 +218,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}
      */
   }, {
@@ -215,9 +235,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}
      */
   }, {
@@ -227,9 +247,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}
      */
   }, {
@@ -239,10 +259,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}
      */
   }, {
@@ -252,9 +273,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}
      */
   }, {
@@ -264,9 +285,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}
      */
   }, {
@@ -276,10 +297,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}
      */
   }, {
@@ -289,10 +312,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}
      */
   }, {
@@ -302,9 +327,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}
      */
   }, {
@@ -321,9 +348,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}
      */
   }, {
@@ -413,7 +440,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).
      */
@@ -424,7 +451,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).
      */
@@ -435,7 +462,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",
@@ -460,7 +487,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",
@@ -485,8 +512,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}
      */
@@ -497,8 +526,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}
      */
@@ -509,8 +541,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}
      */
@@ -521,8 +555,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}
      */
@@ -533,8 +570,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}
      */
@@ -545,8 +584,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}
      */
@@ -557,8 +599,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}
      */
@@ -569,8 +613,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}
      */
@@ -581,8 +628,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}
      */
@@ -593,9 +642,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}
      */
@@ -606,8 +657,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}
      */
@@ -618,9 +671,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}
      */
@@ -631,8 +686,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}
      */
@@ -643,9 +700,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}
      */
@@ -656,8 +715,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}
      */
@@ -668,9 +729,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}
      */
@@ -681,10 +744,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}
      */
   }, {
@@ -697,11 +760,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}
      */
   }, {
@@ -740,8 +805,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",
@@ -778,9 +846,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",
@@ -799,9 +867,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",
@@ -824,10 +892,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",
@@ -845,7 +914,7 @@ var CellRange = /*#__PURE__*/function () {
     }
 
     /**
-     * Clones the range coordinates.
+     * Clones your `CellRange` instance.
      *
      * @returns {CellRange}
      */
@@ -856,10 +925,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",
@@ -871,12 +946,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}
      */
   }, {

package/base.d.ts

@@ -1,3 +1,4 @@
 import Handsontable from './index';
 
+export * from './index';
 export default Handsontable;