handsontable 17.1.0 → 18.0.0-rc2

package/core/hooks/constants.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @description
+ *
+ * ::: only-for javascript
+ * Handsontable events are the common interface that function in 2 ways: as __callbacks__ and as __hooks__.
+ * :::
+ *
+ * ::: only-for react
+ * This page lists all the **Handsontable hooks** – callbacks that let you react before or after an action occurs.
+ *
+ * Read more on the [Events and hooks](@/guides/getting-started/events-and-hooks/events-and-hooks.md) page.
+ * :::
+ *
+ * @example
+ *
+ * ::: only-for javascript
+ * ```js
+ * // using events as callbacks
+ * ...
+ * const hot1 = new Handsontable(document.getElementById('example1'), {
+ *   afterChange: function(changes, source) {
+ *     $.ajax({
+ *       url: "save.php',
+ *       data: change
+ *     });
+ *   }
+ * });
+ * ...
+ * ```
+ * :::
+ *
+ * ::: only-for react
+ * ```jsx
+ * <HotTable
+ *   afterChange={(changes, source) => {
+ *     fetch('save.php', {
+ *       method: 'POST',
+ *       headers: {
+ *         'Accept': 'application/json',
+ *         'Content-Type': 'application/json'
+ *       },
+ *       body: JSON.stringify(changes)
+ *     });
+ *   }}
+ * />
+ * :::
+ *
+ * ::: only-for angular
+ * ```ts
+ * settings = {
+ *   afterChange: (changes, source) => {
+ *     changes?.forEach(([row, prop, oldValue, newValue]) => {
+ *       // Some logic...
+ *     });
+ *   },
+ * };
+ * ```
+ *
+ * ```html
+ * <hot-table [settings]="settings" />
+ * ```
+ * :::
+ *
+ * ::: only-for javascript
+ * ```js
+ * // using events as plugin hooks
+ * ...
+ * const hot1 = new Handsontable(document.getElementById('example1'), {
+ *   myPlugin: true
+ * });
+ *
+ * const hot2 = new Handsontable(document.getElementById('example2'), {
+ *   myPlugin: false
+ * });
+ *
+ * // global hook
+ * Handsontable.hooks.add('afterChange', function() {
+ *   // Fired twice - for hot1 and hot2
+ *   if (this.getSettings().myPlugin) {
+ *     // function body - will only run for hot1
+ *   }
+ * });
+ *
+ * // local hook (has same effect as a callback)
+ * hot2.addHook('afterChange', function() {
+ *   // function body - will only run in #example2
+ * });
+ * ```
+ * :::
+ *
+ * ::: only-for react
+ * ```jsx
+ * const hotRef1 = useRef(null);
+ * const hotRef2 = useRef(null);
+ *
+ * // Using events as plugin hooks:
+ * ...
+ *
+ * <HotTable
+ *   ref={hotRef1}
+ *   myPlugin={true}
+ * });
+ *
+ * <HotTable
+ *   ref={hotRef2}
+ *   myPlugin={false}
+ * });
+ *
+ * ...
+ *
+ * const hot2 = hotRef2.current.hotInstance;
+ * // local hook (has same effect as a callback)
+ * hot2.addHook('afterChange', function() {
+ *   // function body - will only run in #example2
+ * });
+ *
+ * // global hook
+ * Handsontable.hooks.add('afterChange', function() {
+ *   // Fired twice - for hot1 and hot2
+ *   if (this.getSettings().myPlugin) {
+ *     // function body - will only run for first instance
+ *   }
+ * });
+ * :::
+ * ...
+ */
+export declare const REGISTERED_HOOKS: string[];
+/**
+ * The list of the hooks which are removed from the API. The warning message is printed out in
+ * the developer console when the hook is used.
+ *
+ * The Map key is represented by hook name and its value points to the Handsontable version
+ * in which it was removed.
+ *
+ * @type {Map<string, string>}
+ */
+export declare const REMOVED_HOOKS: Map<string, string>;
+/**
+ * The list of the hooks which are deprecated. The warning message is printed out in
+ * the developer console when the hook is used.
+ *
+ * The Map key is represented by hook name and its value keeps message which whould be
+ * printed out when the hook is used.
+ *
+ * Usage:
+ * ```js
+ * ...
+ * New Map([
+ *   ['beforeColumnExpand', 'The plugin hook "beforeColumnExpand" is deprecated. Use "beforeColumnExpand2" instead.'],
+ * ])
+ * ...
+ * ```
+ *
+ *
+ * @type {Map<string, string>}
+ */
+export declare const DEPRECATED_HOOKS: Map<string, string>;

package/core/hooks/constants.js

@@ -1,4 +1,4 @@
-/* eslint-disable jsdoc/require-description-complete-sentence */ /**
+/**
  * @description
  *
  * ::: only-for javascript
@@ -145,7 +145,7 @@ _export(exports, {
     }
 });
 const REGISTERED_HOOKS = [
-    /* eslint-disable jsdoc/require-description-complete-sentence */ /**
+    /**
    * Fired after resetting a cell's meta. This happens when the {@link Core#updateSettings} method is called.
    *
    * @event Hooks#afterCellMetaReset
@@ -600,6 +600,17 @@ const REGISTERED_HOOKS = [
    * @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
    */ 'afterOnCellMouseOut',
     /**
+   * Fired after the mouse cursor moves outside the visible viewport while a mouse button is held down
+   * (e.g. during a drag-to-scroll operation). The event fires once per mousemove tick for as long as
+   * the cursor remains outside the viewport.
+   *
+   * @event Hooks#afterOnCellMouseOverOutside
+   * @since 17.2.0
+   * @param {Event} event `mousemove` event object.
+   * @param {CellCoords} coords Visual coordinates of the nearest viewport-edge cell.
+   * @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
+   */ 'afterOnCellMouseOverOutside',
+    /**
    * Fired after one or more columns are removed.
    *
    * When consecutive columns are removed, this hook is fired once with the `amount` reflecting
@@ -1117,7 +1128,9 @@ const REGISTERED_HOOKS = [
    * @param {*} value Value which was under removed key of cell meta.
    */ 'afterRemoveCellMeta',
     /**
-   * Fired after cell data was changed.
+   * Fired after [`setDataAtCell`](@/api/core.md#setdataatcell) is called and changes are processed,
+   * before they are validated and applied to the data source.
+   * Use [`afterChange`](@/api/hooks.md#afterchange) if you need to react after the data has been written.
    *
    * @event Hooks#afterSetDataAtCell
    * @param {Array} changes An array of changes in format `[[row, column, oldValue, value], ...]`.
@@ -1125,8 +1138,9 @@ const REGISTERED_HOOKS = [
    *                          ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
    */ 'afterSetDataAtCell',
     /**
-   * Fired after cell data was changed.
-   * Called only when [`setDataAtRowProp`](@/api/core.md#setdataatrowprop) was executed.
+   * Fired after [`setDataAtRowProp`](@/api/core.md#setdataatrowprop) is called and changes are processed,
+   * before they are validated and applied to the data source.
+   * Use [`afterChange`](@/api/hooks.md#afterchange) if you need to react after the data has been written.
    *
    * @event Hooks#afterSetDataAtRowProp
    * @param {Array} changes An array of changes in format `[[row, prop, oldValue, value], ...]`.
@@ -1485,6 +1499,19 @@ const REGISTERED_HOOKS = [
    * @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
    */ 'beforeOnCellMouseOut',
     /**
+   * Fired when the mouse cursor moves outside the visible viewport while a mouse button is held down
+   * (e.g. during a drag-to-scroll operation), before selection changes are applied. Use the `controller`
+   * object to suppress row, column, or cell selection changes for this tick.
+   *
+   * @event Hooks#beforeOnCellMouseOverOutside
+   * @since 17.2.0
+   * @param {Event} event `mousemove` event object.
+   * @param {CellCoords} coords Visual coordinates of the nearest viewport-edge cell.
+   * @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
+   * @param {object} controller An object with properties `row`, `column` and `cell`. Each property contains
+   *                            a boolean value that allows or disallows changing the selection for that particular area.
+   */ 'beforeOnCellMouseOverOutside',
+    /**
    * Fired before one or more columns are about to be removed.
    *
    * @event Hooks#beforeRemoveCol
@@ -2218,7 +2245,7 @@ const REGISTERED_HOOKS = [
    * @param {number} newSize Calculated new column width.
    * @param {number} column Visual index of the resized column.
    * @param {boolean} isDoubleClick Flag that determines whether there was a double-click.
-   * @returns {number} Returns a new column size or `undefined`, if column size should be calculated automatically.
+   * @returns {number|false|undefined} Returns a new column size, `false` to cancel the resize, or `undefined` to keep the size set by the drag or auto-calculation.
    */ 'beforeColumnResize',
     /**
    * Fired by {@link ManualColumnResize} plugin after rendering the table with modified column sizes. This hook is
@@ -2237,7 +2264,7 @@ const REGISTERED_HOOKS = [
    * @param {number} newSize Calculated new row height.
    * @param {number} row Visual index of the resized row.
    * @param {boolean} isDoubleClick Flag that determines whether there was a double-click.
-   * @returns {number|undefined} Returns the new row size or `undefined` if row size should be calculated automatically.
+   * @returns {number|false|undefined} Returns a new row size, `false` to cancel the resize, or `undefined` to keep the size set by the drag or auto-calculation.
    */ 'beforeRowResize',
     /**
    * Fired by {@link ManualRowResize} plugin after rendering the table with modified row sizes. This hook is
@@ -3187,8 +3214,18 @@ const REMOVED_HOOKS = new Map([
     [
         'hiddenRow',
         '8.0.0'
+    ],
+    [
+        'persistentStateSave',
+        '17.0.0'
+    ],
+    [
+        'persistentStateLoad',
+        '17.0.0'
+    ],
+    [
+        'persistentStateReset',
+        '17.0.0'
     ]
 ]);
-const DEPRECATED_HOOKS = new Map([
-    []
-]);
+const DEPRECATED_HOOKS = new Map([]);

package/core/hooks/constants.mjs

@@ -1,4 +1,4 @@
-/* eslint-disable jsdoc/require-description-complete-sentence */ /**
+/**
  * @description
  *
  * ::: only-for javascript
@@ -124,7 +124,7 @@
  * :::
  * ...
  */ export const REGISTERED_HOOKS = [
-    /* eslint-disable jsdoc/require-description-complete-sentence */ /**
+    /**
    * Fired after resetting a cell's meta. This happens when the {@link Core#updateSettings} method is called.
    *
    * @event Hooks#afterCellMetaReset
@@ -579,6 +579,17 @@
    * @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
    */ 'afterOnCellMouseOut',
     /**
+   * Fired after the mouse cursor moves outside the visible viewport while a mouse button is held down
+   * (e.g. during a drag-to-scroll operation). The event fires once per mousemove tick for as long as
+   * the cursor remains outside the viewport.
+   *
+   * @event Hooks#afterOnCellMouseOverOutside
+   * @since 17.2.0
+   * @param {Event} event `mousemove` event object.
+   * @param {CellCoords} coords Visual coordinates of the nearest viewport-edge cell.
+   * @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
+   */ 'afterOnCellMouseOverOutside',
+    /**
    * Fired after one or more columns are removed.
    *
    * When consecutive columns are removed, this hook is fired once with the `amount` reflecting
@@ -1096,7 +1107,9 @@
    * @param {*} value Value which was under removed key of cell meta.
    */ 'afterRemoveCellMeta',
     /**
-   * Fired after cell data was changed.
+   * Fired after [`setDataAtCell`](@/api/core.md#setdataatcell) is called and changes are processed,
+   * before they are validated and applied to the data source.
+   * Use [`afterChange`](@/api/hooks.md#afterchange) if you need to react after the data has been written.
    *
    * @event Hooks#afterSetDataAtCell
    * @param {Array} changes An array of changes in format `[[row, column, oldValue, value], ...]`.
@@ -1104,8 +1117,9 @@
    *                          ([list of all available sources](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
    */ 'afterSetDataAtCell',
     /**
-   * Fired after cell data was changed.
-   * Called only when [`setDataAtRowProp`](@/api/core.md#setdataatrowprop) was executed.
+   * Fired after [`setDataAtRowProp`](@/api/core.md#setdataatrowprop) is called and changes are processed,
+   * before they are validated and applied to the data source.
+   * Use [`afterChange`](@/api/hooks.md#afterchange) if you need to react after the data has been written.
    *
    * @event Hooks#afterSetDataAtRowProp
    * @param {Array} changes An array of changes in format `[[row, prop, oldValue, value], ...]`.
@@ -1464,6 +1478,19 @@
    * @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
    */ 'beforeOnCellMouseOut',
     /**
+   * Fired when the mouse cursor moves outside the visible viewport while a mouse button is held down
+   * (e.g. during a drag-to-scroll operation), before selection changes are applied. Use the `controller`
+   * object to suppress row, column, or cell selection changes for this tick.
+   *
+   * @event Hooks#beforeOnCellMouseOverOutside
+   * @since 17.2.0
+   * @param {Event} event `mousemove` event object.
+   * @param {CellCoords} coords Visual coordinates of the nearest viewport-edge cell.
+   * @param {HTMLTableCellElement} TD Cell's TD (or TH) element.
+   * @param {object} controller An object with properties `row`, `column` and `cell`. Each property contains
+   *                            a boolean value that allows or disallows changing the selection for that particular area.
+   */ 'beforeOnCellMouseOverOutside',
+    /**
    * Fired before one or more columns are about to be removed.
    *
    * @event Hooks#beforeRemoveCol
@@ -2197,7 +2224,7 @@
    * @param {number} newSize Calculated new column width.
    * @param {number} column Visual index of the resized column.
    * @param {boolean} isDoubleClick Flag that determines whether there was a double-click.
-   * @returns {number} Returns a new column size or `undefined`, if column size should be calculated automatically.
+   * @returns {number|false|undefined} Returns a new column size, `false` to cancel the resize, or `undefined` to keep the size set by the drag or auto-calculation.
    */ 'beforeColumnResize',
     /**
    * Fired by {@link ManualColumnResize} plugin after rendering the table with modified column sizes. This hook is
@@ -2216,7 +2243,7 @@
    * @param {number} newSize Calculated new row height.
    * @param {number} row Visual index of the resized row.
    * @param {boolean} isDoubleClick Flag that determines whether there was a double-click.
-   * @returns {number|undefined} Returns the new row size or `undefined` if row size should be calculated automatically.
+   * @returns {number|false|undefined} Returns a new row size, `false` to cancel the resize, or `undefined` to keep the size set by the drag or auto-calculation.
    */ 'beforeRowResize',
     /**
    * Fired by {@link ManualRowResize} plugin after rendering the table with modified row sizes. This hook is
@@ -3174,9 +3201,21 @@
     [
         'hiddenRow',
         '8.0.0'
+    ],
+    [
+        'persistentStateSave',
+        '17.0.0'
+    ],
+    [
+        'persistentStateLoad',
+        '17.0.0'
+    ],
+    [
+        'persistentStateReset',
+        '17.0.0'
     ]
 ]);
-/* eslint-disable jsdoc/require-description-complete-sentence */ /**
+/**
  * The list of the hooks which are deprecated. The warning message is printed out in
  * the developer console when the hook is used.
  *
@@ -3194,6 +3233,4 @@
  *
  *
  * @type {Map<string, string>}
- */ /* eslint-enable jsdoc/require-description-complete-sentence */ export const DEPRECATED_HOOKS = new Map([
-    []
-]);
+ */ export const DEPRECATED_HOOKS = new Map([]);

package/core/hooks/index.d.mts

@@ -0,0 +1,2 @@
+export * from './index.js';
+export { default } from './index.js';