handsontable 14.6.1 → 15.0.0-next-fdd4480-20241205

package/{pluginHooks.js → core/hooks/constants.mjs}

@@ -1,18 +1,3 @@
-"use strict";
-
-exports.__esModule = true;
-require("core-js/modules/es.error.cause.js");
-require("core-js/modules/es.array.push.js");
-require("core-js/modules/es.array.unscopables.flat-map.js");
-var _array = require("./helpers/array");
-var _object = require("./helpers/object");
-var _string = require("./helpers/string");
-var _console = require("./helpers/console");
-var _templateLiteralTag = require("./helpers/templateLiteralTag");
-var _function = require("./helpers/function");
-function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
-function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
-function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 /* eslint-disable jsdoc/require-description-complete-sentence */
 /**
  * @description
@@ -125,8 +110,7 @@ function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e =
  * ...
  */
 
-// @TODO: Move plugin description hooks to plugin?
-const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-sentence */
+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.
  *
@@ -556,6 +540,10 @@ const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-s
  * @since 14.0.0
  * @event Hooks#beforeViewportScrollVertically
  * @param {number} visualRow Visual row index.
+ * @param {'auto' | 'top' | 'bottom'} [snapping='auto'] If `'top'`, viewport is scrolled to show
+ * the cell on the top of the table. If `'bottom'`, viewport is scrolled to show the cell on
+ * the bottom of the table. When `'auto'`, the viewport is scrolled only when the row is outside of
+ * the viewport.
  * @returns {number | boolean} Returns modified row index (or the same as passed in the method argument) to which
  * the viewport will be scrolled. If the returned value is `false`, the scrolling will be canceled.
  */
@@ -567,6 +555,9 @@ const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-s
  * @since 14.0.0
  * @event Hooks#beforeViewportScrollHorizontally
  * @param {number} visualColumn Visual column index.
+ * @param {'auto' | 'start' | 'end'} [snapping='auto'] If `'start'`, viewport is scrolled to show
+ * the cell on the left of the table. If `'end'`, viewport is scrolled to show the cell on the right of
+ * the table. When `'auto'`, the viewport is scrolled only when the column is outside of the viewport.
  * @returns {number | boolean} Returns modified column index (or the same as passed in the method argument) to which
  * the viewport will be scrolled. If the returned value is `false`, the scrolling will be canceled.
  */
@@ -878,6 +869,15 @@ const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-s
  * @param {string} [source] String that identifies source of hook call.
  */
 'afterSetSourceDataAtCell',
+/**
+ * Fired after a theme is enabled, changed, or disabled.
+ *
+ * @since 15.0.0
+ * @event Hooks#afterSetTheme
+ * @param {string|boolean|undefined} themeName The theme name.
+ * @param {boolean} firstRun `true` if it's the initial setting of the theme, `false` otherwise.
+ */
+'afterSetTheme',
 /**
  * Fired after calling the [`updateSettings`](@/api/core.md#updatesettings) method.
  *
@@ -1381,6 +1381,7 @@ const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-s
  * @event Hooks#modifyColWidth
  * @param {number} width Current column width.
  * @param {number} column Visual column index.
+ * @param {string} [source] String that identifies source of hook call.
  */
 'modifyColWidth',
 /**
@@ -1417,6 +1418,7 @@ const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-s
  * @event Hooks#modifyRowHeight
  * @param {number} height Row height.
  * @param {number} row Visual row index.
+ * @param {string} [source] String that identifies source of hook call.
  */
 'modifyRowHeight',
 /**
@@ -1469,9 +1471,22 @@ const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-s
  * @param {boolean} topmost If set to `true`, it returns the TD element from the topmost overlay. For example,
  *                          if the wanted cell is in the range of fixed rows, it will return a TD element
  *                          from the `top` overlay.
+ * @param {string} source String that identifies how this coords change will be processed. Possible values:
+ *                        `meta` the change will affect the cell meta and data; `render` the change will affect the
+ *                        DOM element that will be returned by the `getCell` method.
  * @returns {undefined|number[]}
  */
 'modifyGetCellCoords',
+/**
+ * Used to modify the returned cell coordinates of clicked cells (TD or TH elements).
+ *
+ * @event Hooks#modifyGetCoordsElement
+ * @since 14.6.0
+ * @param {number} row Visual row index.
+ * @param {number} column Visual column index.
+ * @returns {undefined|number[]}
+ */
+'modifyGetCoordsElement',
 /**
  * Used to modify the cell coordinates when the table is activated (going into the listen mode).
  *
@@ -2637,15 +2652,6 @@ const REGISTERED_HOOKS = [/* eslint-disable jsdoc/require-description-complete-s
  */
 'modifyAutoColumnSizeSeed'];
 
-/**
- * Template warning message for removed hooks.
- *
- * @type {string}
- */
-const REMOVED_MESSAGE = (0, _templateLiteralTag.toSingleLine)`The plugin hook "[hookName]" was removed in Handsontable [removedInVersion].\x20
-  Please consult release notes https://github.com/handsontable/handsontable/releases/tag/[removedInVersion] to\x20
-  learn about the migration path.`;
-
 /**
  * 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.
@@ -2655,7 +2661,7 @@ const REMOVED_MESSAGE = (0, _templateLiteralTag.toSingleLine)`The plugin hook "[
  *
  * @type {Map<string, string>}
  */
-const REMOVED_HOOKS = new Map([['modifyRow', '8.0.0'], ['modifyCol', '8.0.0'], ['unmodifyRow', '8.0.0'], ['unmodifyCol', '8.0.0'], ['skipLengthCache', '8.0.0'], ['hiddenColumn', '8.0.0'], ['hiddenRow', '8.0.0']]);
+export const REMOVED_HOOKS = new Map([['modifyRow', '8.0.0'], ['modifyCol', '8.0.0'], ['unmodifyRow', '8.0.0'], ['unmodifyCol', '8.0.0'], ['skipLengthCache', '8.0.0'], ['hiddenColumn', '8.0.0'], ['hiddenRow', '8.0.0']]);
 
 /* eslint-disable jsdoc/require-description-complete-sentence */
 /**
@@ -2678,465 +2684,4 @@ const REMOVED_HOOKS = new Map([['modifyRow', '8.0.0'], ['modifyCol', '8.0.0'], [
  * @type {Map<string, string>}
  */
 /* eslint-enable jsdoc/require-description-complete-sentence */
-const DEPRECATED_HOOKS = new Map([[]]);
-const callbackOrder = new WeakMap();
-class Hooks {
-  static getSingleton() {
-    return getGlobalSingleton();
-  }
-
-  /**
-   * @type {object}
-   */
-
-  /**
-   *
-   */
-  constructor() {
-    _defineProperty(this, "globalBucket", void 0);
-    this.globalBucket = this.createEmptyBucket();
-  }
-
-  /**
-   * Returns a new object with empty handlers related to every registered hook name.
-   *
-   * @returns {object} The empty bucket object.
-   *
-   * @example
-   * ```js
-   * Handsontable.hooks.createEmptyBucket();
-   * // Results:
-   * {
-   * ...
-   * afterCreateCol: [],
-   * afterCreateRow: [],
-   * beforeInit: [],
-   * ...
-   * }
-   * ```
-   */
-  createEmptyBucket() {
-    const bucket = Object.create(null);
-
-    // eslint-disable-next-line no-return-assign
-    (0, _array.arrayEach)(REGISTERED_HOOKS, hook => {
-      bucket[hook] = [];
-      this.initOrderMap(bucket, hook);
-    });
-    return bucket;
-  }
-
-  /**
-   * Get hook bucket based on the context of the object or if argument is `undefined`, get the global hook bucket.
-   *
-   * @param {object} [context=null] A Handsontable instance.
-   * @returns {object} Returns a global or Handsontable instance bucket.
-   */
-  getBucket() {
-    let context = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : null;
-    if (context) {
-      if (!context.pluginHookBucket) {
-        context.pluginHookBucket = this.createEmptyBucket();
-      }
-      return context.pluginHookBucket;
-    }
-    return this.globalBucket;
-  }
-
-  /**
-   * Adds a listener (globally or locally) to a specified hook name.
-   * If the `context` parameter is provided, the hook will be added only to the instance it references.
-   * Otherwise, the callback will be used everytime the hook fires on any Handsontable instance.
-   * You can provide an array of callback functions as the `callback` argument, this way they will all be fired
-   * once the hook is triggered.
-   *
-   * @see Core#addHook
-   * @param {string} key Hook name.
-   * @param {Function|Array} callback Callback function or an array of functions.
-   * @param {object} [context=null] The context for the hook callback to be added - a Handsontable instance or leave empty.
-   * @param {number} [orderIndex] Order index of the callback.
-   *                              If > 0, the callback will be added after the others, for example, with an index of 1, the callback will be added before the ones with an index of 2, 3, etc., but after the ones with an index of 0 and lower.
-   *                              If < 0, the callback will be added before the others, for example, with an index of -1, the callback will be added after the ones with an index of -2, -3, etc., but before the ones with an index of 0 and higher.
-   *                              If 0 or no order index is provided, the callback will be added between the "negative" and "positive" indexes.
-   * @returns {Hooks} Instance of Hooks.
-   *
-   * @example
-   * ```js
-   * // single callback, added locally
-   * Handsontable.hooks.add('beforeInit', myCallback, hotInstance);
-   *
-   * // single callback, added globally
-   * Handsontable.hooks.add('beforeInit', myCallback);
-   *
-   * // multiple callbacks, added locally
-   * Handsontable.hooks.add('beforeInit', [myCallback, anotherCallback], hotInstance);
-   *
-   * // multiple callbacks, added globally
-   * Handsontable.hooks.add('beforeInit', [myCallback, anotherCallback]);
-   * ```
-   */
-  add(key, callback) {
-    let context = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
-    let orderIndex = arguments.length > 3 ? arguments[3] : undefined;
-    if (Array.isArray(callback)) {
-      (0, _array.arrayEach)(callback, c => this.add(key, c, context));
-    } else {
-      if (REMOVED_HOOKS.has(key)) {
-        (0, _console.warn)((0, _string.substitute)(REMOVED_MESSAGE, {
-          hookName: key,
-          removedInVersion: REMOVED_HOOKS.get(key)
-        }));
-      }
-      if (DEPRECATED_HOOKS.has(key)) {
-        (0, _console.warn)(DEPRECATED_HOOKS.get(key));
-      }
-      const bucket = this.getBucket(context);
-      if (typeof bucket[key] === 'undefined') {
-        this.register(key);
-        bucket[key] = [];
-        this.initOrderMap(bucket, key);
-      }
-      callback.skip = false;
-      if (bucket[key].indexOf(callback) === -1) {
-        // only add a hook if it has not already been added (adding the same hook twice is now silently ignored)
-        let foundInitialHook = false;
-        if (callback.initialHook) {
-          (0, _array.arrayEach)(bucket[key], (cb, i) => {
-            if (cb.initialHook) {
-              bucket[key][i] = callback;
-              foundInitialHook = true;
-              return false;
-            }
-          });
-        }
-        if (!foundInitialHook) {
-          bucket[key].push(callback);
-        }
-      }
-      this.setCallbackOrderIndex(bucket, key, callback, orderIndex);
-      this.orderBucketByOrderIndex(bucket, key);
-    }
-    return this;
-  }
-
-  /**
-   * Adds a listener to a specified hook. After the hook runs this listener will be automatically removed from the bucket.
-   *
-   * @see Core#addHookOnce
-   * @param {string} key Hook/Event name.
-   * @param {Function|Array} callback Callback function.
-   * @param {object} [context=null] A Handsontable instance.
-   * @param {number} [orderIndex] Order index of the callback.
-   *                              If > 0, the callback will be added after the others, for example, with an index of 1, the callback will be added before the ones with an index of 2, 3, etc., but after the ones with an index of 0 and lower.
-   *                              If < 0, the callback will be added before the others, for example, with an index of -1, the callback will be added after the ones with an index of -2, -3, etc., but before the ones with an index of 0 and higher.
-   *                              If 0 or no order index is provided, the callback will be added between the "negative" and "positive" indexes.
-   *
-   * @example
-   * ```js
-   * Handsontable.hooks.once('beforeInit', myCallback, hotInstance);
-   * ```
-   */
-  once(key, callback) {
-    let context = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
-    let orderIndex = arguments.length > 3 ? arguments[3] : undefined;
-    if (Array.isArray(callback)) {
-      (0, _array.arrayEach)(callback, c => this.once(key, c, context));
-    } else {
-      callback.runOnce = true;
-      this.add(key, callback, context, orderIndex);
-    }
-  }
-
-  /**
-   * Removes a listener from a hook with a given name. If the `context` argument is provided, it removes a listener from a local hook assigned to the given Handsontable instance.
-   *
-   * @see Core#removeHook
-   * @param {string} key Hook/Event name.
-   * @param {Function} callback Callback function (needs the be the function that was previously added to the hook).
-   * @param {object} [context=null] Handsontable instance.
-   * @returns {boolean} Returns `true` if hook was removed, `false` otherwise.
-   *
-   * @example
-   * ```js
-   * Handsontable.hooks.remove('beforeInit', myCallback);
-   * ```
-   */
-  remove(key, callback) {
-    let context = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
-    const bucket = this.getBucket(context);
-    if (typeof bucket[key] !== 'undefined') {
-      if (bucket[key].indexOf(callback) >= 0) {
-        callback.skip = true;
-        return true;
-      }
-    }
-    return false;
-  }
-
-  /**
-   * Checks whether there are any registered listeners for the provided hook name.
-   * If the `context` parameter is provided, it only checks for listeners assigned to the given Handsontable instance.
-   *
-   * @param {string} key Hook name.
-   * @param {object} [context=null] A Handsontable instance.
-   * @returns {boolean} `true` for success, `false` otherwise.
-   */
-  has(key) {
-    let context = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
-    const bucket = this.getBucket(context);
-    return !!(bucket[key] !== undefined && bucket[key].length);
-  }
-
-  /**
-   * Runs all local and global callbacks assigned to the hook identified by the `key` parameter.
-   * It returns either a return value from the last called callback or the first parameter (`p1`) passed to the `run` function.
-   *
-   * @see Core#runHooks
-   * @param {object} context Handsontable instance.
-   * @param {string} key Hook/Event name.
-   * @param {*} [p1] Parameter to be passed as an argument to the callback function.
-   * @param {*} [p2] Parameter to be passed as an argument to the callback function.
-   * @param {*} [p3] Parameter to be passed as an argument to the callback function.
-   * @param {*} [p4] Parameter to be passed as an argument to the callback function.
-   * @param {*} [p5] Parameter to be passed as an argument to the callback function.
-   * @param {*} [p6] Parameter to be passed as an argument to the callback function.
-   * @returns {*} Either a return value from the last called callback or `p1`.
-   *
-   * @example
-   * ```js
-   * Handsontable.hooks.run(hot, 'beforeInit');
-   * ```
-   */
-  run(context, key, p1, p2, p3, p4, p5, p6) {
-    {
-      const globalHandlers = this.globalBucket[key];
-      const length = globalHandlers ? globalHandlers.length : 0;
-      let index = 0;
-      if (length) {
-        // Do not optimise this loop with arrayEach or arrow function! If you do You'll decrease perf because of GC.
-        while (index < length) {
-          if (!globalHandlers[index] || globalHandlers[index].skip) {
-            index += 1;
-            /* eslint-disable no-continue */
-            continue;
-          }
-          const res = (0, _function.fastCall)(globalHandlers[index], context, p1, p2, p3, p4, p5, p6);
-          if (res !== undefined) {
-            // eslint-disable-next-line no-param-reassign
-            p1 = res;
-          }
-          if (globalHandlers[index] && globalHandlers[index].runOnce) {
-            this.remove(key, globalHandlers[index]);
-          }
-          index += 1;
-        }
-      }
-    }
-    {
-      const localHandlers = this.getBucket(context)[key];
-      const length = localHandlers ? localHandlers.length : 0;
-      let index = 0;
-      if (length) {
-        // Do not optimise this loop with arrayEach or arrow function! If you do You'll decrease perf because of GC.
-        while (index < length) {
-          if (!localHandlers[index] || localHandlers[index].skip) {
-            index += 1;
-            /* eslint-disable no-continue */
-            continue;
-          }
-          const res = (0, _function.fastCall)(localHandlers[index], context, p1, p2, p3, p4, p5, p6);
-          if (res !== undefined) {
-            // eslint-disable-next-line no-param-reassign
-            p1 = res;
-          }
-          if (localHandlers[index] && localHandlers[index].runOnce) {
-            this.remove(key, localHandlers[index], context);
-          }
-          index += 1;
-        }
-      }
-    }
-    return p1;
-  }
-
-  /**
-   * Destroy all listeners connected to the context. If no context is provided, the global listeners will be destroyed.
-   *
-   * @param {object} [context=null] A Handsontable instance.
-   * @example
-   * ```js
-   * // destroy the global listeners
-   * Handsontable.hooks.destroy();
-   *
-   * // destroy the local listeners
-   * Handsontable.hooks.destroy(hotInstance);
-   * ```
-   */
-  destroy() {
-    let context = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : null;
-    // eslint-disable-next-line no-return-assign
-    (0, _object.objectEach)(this.getBucket(context), (value, key, bucket) => bucket[key].length = 0);
-  }
-
-  /**
-   * Registers a hook name (adds it to the list of the known hook names). Used by plugins.
-   * It is not necessary to call register, but if you use it, your plugin hook will be used returned by
-   * the `getRegistered` method. (which itself is used in the [demo](@/guides/getting-started/events-and-hooks/events-and-hooks.md)).
-   *
-   * @param {string} key The hook name.
-   *
-   * @example
-   * ```js
-   * Handsontable.hooks.register('myHook');
-   * ```
-   */
-  register(key) {
-    if (!this.isRegistered(key)) {
-      REGISTERED_HOOKS.push(key);
-    }
-  }
-
-  /**
-   * Deregisters a hook name (removes it from the list of known hook names).
-   *
-   * @param {string} key The hook name.
-   *
-   * @example
-   * ```js
-   * Handsontable.hooks.deregister('myHook');
-   * ```
-   */
-  deregister(key) {
-    if (this.isRegistered(key)) {
-      REGISTERED_HOOKS.splice(REGISTERED_HOOKS.indexOf(key), 1);
-    }
-  }
-
-  /**
-   * Returns a boolean value depending on if a hook by such name has been removed or deprecated.
-   *
-   * @param {string} hookName The hook name to check.
-   * @returns {boolean} Returns `true` if the provided hook name was marked as deprecated or
-   * removed from API, `false` otherwise.
-   * @example
-   * ```js
-   * Handsontable.hooks.isDeprecated('skipLengthCache');
-   *
-   * // Results:
-   * true
-   * ```
-   */
-  isDeprecated(hookName) {
-    return DEPRECATED_HOOKS.has(hookName) || REMOVED_HOOKS.has(hookName);
-  }
-
-  /**
-   * Returns a boolean depending on if a hook by such name has been registered.
-   *
-   * @param {string} hookName The hook name to check.
-   * @returns {boolean} `true` for success, `false` otherwise.
-   * @example
-   * ```js
-   * Handsontable.hooks.isRegistered('beforeInit');
-   *
-   * // Results:
-   * true
-   * ```
-   */
-  isRegistered(hookName) {
-    return REGISTERED_HOOKS.indexOf(hookName) >= 0;
-  }
-
-  /**
-   * Returns an array of registered hooks.
-   *
-   * @returns {Array} An array of registered hooks.
-   *
-   * @example
-   * ```js
-   * Handsontable.hooks.getRegistered();
-   *
-   * // Results:
-   * [
-   * ...
-   *   'beforeInit',
-   *   'beforeRender',
-   *   'beforeSetRangeEnd',
-   *   'beforeDrawBorders',
-   *   'beforeChange',
-   * ...
-   * ]
-   * ```
-   */
-  getRegistered() {
-    return REGISTERED_HOOKS;
-  }
-
-  /**
-   * Sets the order index of the callback in the bucket object.
-   *
-   * @private
-   * @param {object} bucket The bucket object.
-   * @param {string} key Hook name.
-   * @param {Function} callback Callback function.
-   * @param {number|undefined} orderIndex Order index of the callback.
-   */
-  setCallbackOrderIndex(bucket, key, callback, orderIndex) {
-    const normalizedOrderIndex = Number.isInteger(orderIndex) ? orderIndex : 0;
-    const orderMap = this.getCallbackOrderMap(bucket, key);
-    orderMap.set(normalizedOrderIndex, [...(orderMap.get(normalizedOrderIndex) || []), callback]);
-  }
-
-  /**
-   * Reorders the callbacks in the bucket object by their order index.
-   *
-   * @private
-   * @param {objcet} bucket The bucket object.
-   * @param {string} key Hook name.
-   */
-  orderBucketByOrderIndex(bucket, key) {
-    const orderMap = this.getCallbackOrderMap(bucket, key);
-    if (orderMap === undefined || orderMap.size === 0 || orderMap.size === 1 && orderMap.has(0)) {
-      return;
-    }
-    bucket[key] = [...orderMap].sort((a, b) => a[0] - b[0]).flatMap(_ref => {
-      let [, callbacks] = _ref;
-      return callbacks;
-    });
-  }
-
-  /**
-   * Extends the bucket object with the order property.
-   *
-   * @private
-   * @param {object} bucket The bucket object.
-   * @param {string} hook The hook name.
-   */
-  initOrderMap(bucket, hook) {
-    if (!callbackOrder.has(bucket)) {
-      callbackOrder.set(bucket, []);
-    }
-    callbackOrder.get(bucket)[hook] = new Map();
-  }
-
-  /**
-   * Returns the order map for the provided hook.
-   *
-   * @private
-   * @param {object} bucket The bucket object.
-   * @param {string} hook The hook name.
-   * @returns {Map<number, Array<Function>>} Returns the order map for the provided hook.
-   */
-  getCallbackOrderMap(bucket, hook) {
-    return callbackOrder.get(bucket)[hook];
-  }
-}
-const globalSingleton = new Hooks();
-
-/**
- * @returns {Hooks}
- */
-function getGlobalSingleton() {
-  return globalSingleton;
-}
-var _default = exports.default = Hooks;
+export const DEPRECATED_HOOKS = new Map([[]]);