handsontable 0.0.0-next-1b1acbd-20221123 → 0.0.0-next-561a94b-20221129

package/plugins/copyPaste/copyPaste.mjs

@@ -81,28 +81,25 @@ var META_HEAD = ['<meta name="generator" content="Handsontable"/>', '<style type
 /* eslint-disable jsdoc/require-description-complete-sentence */
 /**
  * @description
- * This plugin enables the copy/paste functionality in the Handsontable. The functionality works for API, Context Menu,
- * using keyboard shortcuts and menu bar from the browser.
- * Possible values:
- * * `true` (to enable default options),
- * * `false` (to disable completely).
+ * Copy, cut, and paste data by using the `CopyPaste` plugin.
  *
- * or an object with values:
- * * `'columnsLimit'` (see {@link CopyPaste#columnsLimit})
- * * `'rowsLimit'` (see {@link CopyPaste#rowsLimit})
- * * `'pasteMode'` (see {@link CopyPaste#pasteMode})
- * * `'copyColumnHeaders'`
- * * `'copyColumnGroupHeaders'`
- * * `'copyColumnHeadersOnly'`
- * * `'uiContainer'` (see {@link CopyPaste#uiContainer}).
+ * Control the `CopyPaste` plugin programmatically through its [API methods](#methods).
  *
- * See [the copy/paste demo](@/guides/cell-features/clipboard.md) for examples.
+ * The user can access the copy-paste features through:
+ * - The [context menu](@/guides/cell-features/clipboard.md#context-menu).
+ * - The [keyboard shortcuts](@/guides/cell-features/clipboard.md#related-keyboard-shortcuts).
+ * - The browser's menu bar.
+ *
+ * Read more:
+ * - [Guides: Clipboard](@/guides/cell-features/clipboard.md)
+ * - [Configuration options: `copyPaste`](@/api/options.md#copypaste)
  *
  * @example
  * ```js
- * // Enables the plugin with default values
+ * // enable the plugin with the default configuration
  * copyPaste: true,
- * // Enables the plugin with custom values
+ *
+ * // or, enable the plugin with a custom configuration
  * copyPaste: {
  *   columnsLimit: 25,
  *   rowsLimit: 50,
@@ -191,8 +188,10 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     key: "isEnabled",
     value:
     /**
-     * Checks if the plugin is enabled in the handsontable settings. This method is executed in {@link Hooks#beforeInit}
-     * hook and if it returns `true` then the {@link CopyPaste#enablePlugin} method is called.
+     * Checks if the [`CopyPaste`](#copypaste) plugin is enabled.
+     *
+     * This method gets called by Handsontable's [`beforeInit`](@/api/hooks.md#beforeinit) hook.
+     * If it returns `true`, the [`enablePlugin()`](#enableplugin) method gets called.
      *
      * @returns {boolean}
      */
@@ -201,7 +200,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Enables the plugin functionality for this Handsontable instance.
+     * Enables the [`CopyPaste`](#copypaste) plugin for your Handsontable instance.
      */
   }, {
     key: "enablePlugin",
@@ -246,9 +245,10 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Updates the plugin's state.
+     * Updates the state of the [`CopyPaste`](#copypaste) plugin.
      *
-     * This method is executed when [`updateSettings()`](@/api/core.md#updatesettings) is invoked with any of the following configuration options:
+     * Gets called when [`updateSettings()`](@/api/core.md#updatesettings)
+     * is invoked with any of the following configuration options:
      *  - [`copyPaste`](@/api/options.md#copypaste)
      *  - [`fragmentSelection`](@/api/options.md#fragmentselection)
      */
@@ -262,7 +262,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Disables the plugin functionality for this Handsontable instance.
+     * Disables the [`CopyPaste`](#copypaste) plugin for your Handsontable instance.
      */
   }, {
     key: "disablePlugin",
@@ -274,12 +274,18 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Copies the selected cell with or without column headers into the clipboard.
+     * Copies the contents of the selected cells (and/or their related column headers) to the system clipboard.
+     *
+     * Takes an optional parameter (`copyMode`) that defines the scope of copying:
+     *
+     * | `copyMode` value            | Description                                                     |
+     * | --------------------------- | --------------------------------------------------------------- |
+     * | `'cells-only'` (default)    | Copy the selected cells                                         |
+     * | `'with-column-headers'`     | - Copy the selected cells<br>- Copy the nearest column headers  |
+     * | `'with-all-column-headers'` | - Copy the selected cells<br>- Copy all related columns headers |
+     * | `'column-headers-only'`     | Copy the nearest column headers (without copying cells)         |
      *
-     * @param {'cells-only' | 'column-headers-only' | 'with-all-column-headers' | 'with-column-headers'} [copyMode='cells-only']
-     * Defines the data range to copy. Possible values: `cells-only` (copy selected cells only),
-     * `column-headers-only` (copy the most-bottom column headers only), `with-all-column-headers` (copy cells
-     * with all column headers levels) or `with-column-headers` (copy cells with the most-bottom column headers).
+     * @param {string} [copyMode='cells-only'] Copy mode.
      */
   }, {
     key: "copy",
@@ -293,7 +299,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Copies the selected cell/cells into the clipboard.
+     * Copies the contents of the selected cells.
      */
   }, {
     key: "copyCellsOnly",
@@ -301,7 +307,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
       this.copy('cells-only');
     }
     /**
-     * Copies only the most-bottom column headers into the clipboard.
+     * Copies the contents of column headers that are nearest to the selected cells.
      */
   }, {
     key: "copyColumnHeadersOnly",
@@ -309,7 +315,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
       this.copy('column-headers-only');
     }
     /**
-     * Copies the selected cell/cells and all column headers levels (including column group) into the clipboard.
+     * Copies the contents of the selected cells and all their related column headers.
      */
   }, {
     key: "copyWithAllColumnHeaders",
@@ -317,7 +323,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
       this.copy('with-column-group-headers');
     }
     /**
-     * Copies the selected cell/cells and most-bottom column headers into the clipboard.
+     * Copies the contents of the selected cells and their nearest column headers.
      */
   }, {
     key: "copyWithColumnHeaders",
@@ -326,7 +332,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Cuts the selected cell into the clipboard.
+     * Cuts the contents of the selected cells to the system clipboard.
      */
   }, {
     key: "cut",
@@ -338,10 +344,10 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Creates copyable text related to range objects.
+     * Converts the contents of multiple ranges (`ranges`) into a single string.
      *
      * @param {Array<{startRow: number, startCol: number, endRow: number, endCol: number}>} ranges Array of objects with properties `startRow`, `endRow`, `startCol` and `endCol`.
-     * @returns {string} Returns string which will be copied into clipboard.
+     * @returns {string} A string that will be copied to the clipboard.
      */
   }, {
     key: "getRangedCopyableData",
@@ -350,10 +356,10 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Creates copyable text related to range objects.
+     * Converts the contents of multiple ranges (`ranges`) into an array of arrays.
      *
      * @param {Array<{startRow: number, startCol: number, endRow: number, endCol: number}>} ranges Array of objects with properties `startRow`, `startCol`, `endRow` and `endCol`.
-     * @returns {Array[]} Returns array of arrays which will be copied into clipboard.
+     * @returns {Array[]} An array of arrays that will be copied to the clipboard.
      */
   }, {
     key: "getRangedData",
@@ -364,12 +370,12 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
         rows = _normalizeRanges.rows,
         columns = _normalizeRanges.columns;
 
-      // Concat all rows and columns data defined in ranges into one copyable string
+      // concatenate all rows and columns data defined in ranges into one copyable string
       arrayEach(rows, function (row) {
         var rowSet = [];
         arrayEach(columns, function (column) {
           if (row < 0) {
-            // 'row' as the second argument act here as 'headerLevel' argument
+            // `row` as the second argument acts here as the `headerLevel` argument
             rowSet.push(_this3.hot.getColHeader(column, row));
           } else {
             rowSet.push(_this3.hot.getCopyableData(row, column));
@@ -383,10 +389,10 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     /**
      * Simulates the paste action.
      *
-     * Due to security reasons, modern browsers disallow reading from the system clipboard.
+     * For security reasons, modern browsers don't allow reading from the system clipboard.
      *
-     * @param {string} pastableText Value as raw string to paste.
-     * @param {string} [pastableHtml=''] Value as HTML to paste.
+     * @param {string} pastableText The value to paste, as a raw string.
+     * @param {string} [pastableHtml=''] The value to paste, as HTML.
      */
   }, {
     key: "paste",
@@ -751,7 +757,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Destroys the plugin instance.
+     * Destroys the `CopyPaste` plugin instance.
      */
   }, {
     key: "destroy",
@@ -779,7 +785,7 @@ export var CopyPaste = /*#__PURE__*/function (_BasePlugin) {
     }
 
     /**
-     * Maximum number of columns than can be copied to clipboard using <kbd>**Ctrl**</kbd>/<kbd>**Cmd**</kbd> + <kbd>**C**</kbd>.
+     * The maximum number of columns than can be copied to the clipboard.
      *
      * @type {number}
      * @default Infinity

package/translations/indexMapper.js

@@ -255,10 +255,10 @@ var IndexMapper = /*#__PURE__*/function () {
     }
 
     /**
-     * Creates and register the new IndexMap for specified IndexMapper instance.
+     * Creates and registers a new `IndexMap` for a specified `IndexMapper` instance.
      *
-     * @param {string} indexName The uniq index name.
-     * @param {string} mapType The index map type (e.q. "hiding, "trimming", "physicalIndexToValue").
+     * @param {string} indexName A unique index name.
+     * @param {string} mapType The index map type (e.g., "hiding", "trimming", "physicalIndexToValue").
      * @param {*} [initValueOrFn] The initial value for the index map.
      * @returns {IndexMap}
      */

package/translations/indexMapper.mjs

@@ -250,10 +250,10 @@ export var IndexMapper = /*#__PURE__*/function () {
     }
 
     /**
-     * Creates and register the new IndexMap for specified IndexMapper instance.
+     * Creates and registers a new `IndexMap` for a specified `IndexMapper` instance.
      *
-     * @param {string} indexName The uniq index name.
-     * @param {string} mapType The index map type (e.q. "hiding, "trimming", "physicalIndexToValue").
+     * @param {string} indexName A unique index name.
+     * @param {string} mapType The index map type (e.g., "hiding", "trimming", "physicalIndexToValue").
      * @param {*} [initValueOrFn] The initial value for the index map.
      * @returns {IndexMap}
      */