handsontable 11.1.0 → 12.1.0

package/shortcuts/keyObserver.mjs

@@ -0,0 +1,58 @@
+import "core-js/modules/es.array.iterator.js";
+import "core-js/modules/es.object.to-string.js";
+import "core-js/modules/es.set.js";
+import "core-js/modules/es.string.iterator.js";
+import "core-js/modules/web.dom-collections.iterator.js";
+
+/* eslint-disable jsdoc/require-description-complete-sentence */
+
+/**
+ * Create a key observer.
+ *
+ * @returns {object}
+ */
+export function createKeysObserver() {
+  var PRESSED_KEYS = new Set();
+  return {
+    /**
+     * Press a key.
+     *
+     * @param {string} key Names of the shortcut's keys,
+     * (coming from [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)),
+     * in lowercase or uppercase, unified across browsers
+     */
+    press: function press(key) {
+      PRESSED_KEYS.add(key);
+    },
+
+    /**
+     * Release a pressed key.
+     *
+     * @param {string} key Names of the shortcut's keys,
+     * (coming from [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)),
+     * in lowercase or uppercase, unified across browsers
+     */
+    release: function release(key) {
+      PRESSED_KEYS.delete(key);
+    },
+
+    /**
+     * Release all pressed keys.
+     */
+    releaseAll: function releaseAll() {
+      PRESSED_KEYS.clear();
+    },
+
+    /**
+     * Check if a key is pressed.
+     *
+     * @param {string} key Names of the shortcut's keys,
+     * (coming from [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)),
+     * in lowercase or uppercase, unified across browsers
+     * @returns {boolean}
+     */
+    isPressed: function isPressed(key) {
+      return PRESSED_KEYS.has(key);
+    }
+  };
+}

package/shortcuts/manager.d.ts

@@ -0,0 +1,10 @@
+import { Context } from './context';
+
+export interface ShortcutManager {
+  addContext(contextName: string): Context;
+  getActiveContextName(): string;
+  getContext(contextName: string): Context | undefined;
+  setActiveContextName(contextName: string): void;
+  isCtrlPressed(): boolean;
+  destroy(): void;
+}

package/shortcuts/manager.js

@@ -0,0 +1,185 @@
+"use strict";
+
+exports.__esModule = true;
+exports.createShortcutManager = void 0;
+
+var _uniqueMap = require("../utils/dataStructures/uniqueMap");
+
+var _context = require("./context");
+
+var _recorder = require("./recorder");
+
+/* eslint-disable jsdoc/require-description-complete-sentence */
+
+/**
+ * The `ShortcutManager` API lets you store and manage [keyboard shortcut contexts](@/guides/accessories-and-menus/keyboard-shortcuts.md#keyboard-shortcut-contexts) ([`ShortcutContext`](@/api/shortcutContext.md)).
+ *
+ * Each `ShortcutManager` object:
+ * - Stores and manages its own set of keyboard shortcut contexts.
+ * - Listens to the [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent) events and runs actions for them.
+ *
+ * @alias ShortcutManager
+ * @class ShortcutManager
+ * @param {object} options The manager's options
+ * @param {EventTarget} options.ownerWindow A starting `window` element
+ * @param {Function} options.handleEvent A condition on which `event` is handled.
+ * @param {Function} options.beforeKeyDown A hook fired before the `keydown` event is handled. You can use it to [block a keyboard shortcut's actions](@/guides/accessories-and-menus/keyboard-shortcuts.md#blocking-a-keyboard-shortcut-s-actions).
+ * @param {Function} options.afterKeyDown A hook fired after the `keydown` event is handled
+ */
+var createShortcutManager = function createShortcutManager(_ref) {
+  var ownerWindow = _ref.ownerWindow,
+      handleEvent = _ref.handleEvent,
+      beforeKeyDown = _ref.beforeKeyDown,
+      afterKeyDown = _ref.afterKeyDown;
+
+  /**
+   * A unique map that stores keyboard shortcut contexts.
+   *
+   * @type {UniqueMap}
+   */
+  var CONTEXTS = (0, _uniqueMap.createUniqueMap)({
+    errorIdExists: function errorIdExists(keys) {
+      return "The \"".concat(keys, "\" context name is already registered.");
+    }
+  });
+  /**
+   * The name of the active [`ShortcutContext`](@/api/shortcutContext.md).
+   *
+   * @type {string}
+   */
+
+  var activeContextName = 'grid';
+  /**
+   * Create a new [`ShortcutContext`](@/api/shortcutContext.md) object.
+   *
+   * @memberof ShortcutManager#
+   * @param {string} contextName The name of the new shortcut context
+   * @returns {object}
+   */
+
+  var addContext = function addContext(contextName) {
+    var context = (0, _context.createContext)(contextName);
+    CONTEXTS.addItem(contextName, context);
+    return context;
+  };
+  /**
+   * Get the ID of the active [`ShortcutContext`](@/api/shortcutContext.md).
+   *
+   * @memberof ShortcutManager#
+   * @returns {string}
+   */
+
+
+  var getActiveContextName = function getActiveContextName() {
+    return activeContextName;
+  };
+  /**
+   * Get a keyboard shortcut context by its name.
+   *
+   * @memberof ShortcutManager#
+   * @param {string} contextName The name of the shortcut context
+   * @returns {object|undefined} A [`ShortcutContext`](@/api/shortcutContext.md) object that stores registered shortcuts
+   */
+
+
+  var getContext = function getContext(contextName) {
+    return CONTEXTS.getItem(contextName);
+  };
+  /**
+   * Start listening to keyboard shortcuts within a given [`ShortcutContext`](@/api/shortcutContext.md).
+   *
+   * @memberof ShortcutManager#
+   * @param {string} contextName The name of the shortcut context
+   */
+
+
+  var setActiveContextName = function setActiveContextName(contextName) {
+    activeContextName = contextName;
+  };
+  /**
+   * This variable relates to the `captureCtrl` shortcut option,
+   * which allows for capturing the state of the Control/Meta modifier key.
+   * Some of the default keyboard shortcuts related to cell selection need this feature for working properly.
+   *
+   * @type {boolean}
+   */
+
+
+  var isCtrlKeySilenced = false;
+  /**
+   * Internal key recorder.
+   *
+   * @private
+   */
+
+  var keyRecorder = (0, _recorder.useRecorder)(ownerWindow, handleEvent, beforeKeyDown, afterKeyDown, function (event, keys) {
+    var activeContext = getContext(getActiveContextName());
+    var isExecutionCancelled = false;
+
+    if (!activeContext.hasShortcut(keys)) {
+      return isExecutionCancelled;
+    } // Processing just actions being in stack at the moment of shortcut pressing (without respecting additions/removals performed dynamically).
+
+
+    var shortcuts = activeContext.getShortcuts(keys);
+
+    for (var index = 0; index < shortcuts.length; index++) {
+      var _shortcuts$index = shortcuts[index],
+          callback = _shortcuts$index.callback,
+          runOnlyIf = _shortcuts$index.runOnlyIf,
+          preventDefault = _shortcuts$index.preventDefault,
+          stopPropagation = _shortcuts$index.stopPropagation,
+          captureCtrl = _shortcuts$index.captureCtrl;
+
+      if (runOnlyIf(event) !== false) {
+        isCtrlKeySilenced = captureCtrl;
+        isExecutionCancelled = callback(event, keys) === false;
+        isCtrlKeySilenced = false;
+
+        if (preventDefault) {
+          event.preventDefault();
+        }
+
+        if (stopPropagation) {
+          event.stopPropagation();
+        }
+
+        if (isExecutionCancelled) {
+          break;
+        }
+      }
+    }
+
+    return isExecutionCancelled;
+  });
+  keyRecorder.mount();
+  return {
+    addContext: addContext,
+    getActiveContextName: getActiveContextName,
+    getContext: getContext,
+    setActiveContextName: setActiveContextName,
+
+    /**
+     * Returns whether `control` or `meta` keys are pressed.
+     *
+     * @memberof ShortcutManager#
+     * @type {Function}
+     * @returns {boolean}
+     */
+    isCtrlPressed: function isCtrlPressed() {
+      return !isCtrlKeySilenced && (keyRecorder.isPressed('control') || keyRecorder.isPressed('meta'));
+    },
+
+    /**
+     * Destroy a context manager instance.
+     *
+     * @type {Function}
+     * @memberof ShortcutManager#
+     */
+    destroy: function destroy() {
+      return keyRecorder.unmount();
+    }
+  };
+};
+
+exports.createShortcutManager = createShortcutManager;

package/shortcuts/manager.mjs

@@ -0,0 +1,176 @@
+import { createUniqueMap } from "../utils/dataStructures/uniqueMap.mjs";
+import { createContext } from "./context.mjs";
+import { useRecorder } from "./recorder.mjs";
+/* eslint-disable jsdoc/require-description-complete-sentence */
+
+/**
+ * The `ShortcutManager` API lets you store and manage [keyboard shortcut contexts](@/guides/accessories-and-menus/keyboard-shortcuts.md#keyboard-shortcut-contexts) ([`ShortcutContext`](@/api/shortcutContext.md)).
+ *
+ * Each `ShortcutManager` object:
+ * - Stores and manages its own set of keyboard shortcut contexts.
+ * - Listens to the [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent) events and runs actions for them.
+ *
+ * @alias ShortcutManager
+ * @class ShortcutManager
+ * @param {object} options The manager's options
+ * @param {EventTarget} options.ownerWindow A starting `window` element
+ * @param {Function} options.handleEvent A condition on which `event` is handled.
+ * @param {Function} options.beforeKeyDown A hook fired before the `keydown` event is handled. You can use it to [block a keyboard shortcut's actions](@/guides/accessories-and-menus/keyboard-shortcuts.md#blocking-a-keyboard-shortcut-s-actions).
+ * @param {Function} options.afterKeyDown A hook fired after the `keydown` event is handled
+ */
+
+export var createShortcutManager = function createShortcutManager(_ref) {
+  var ownerWindow = _ref.ownerWindow,
+      handleEvent = _ref.handleEvent,
+      beforeKeyDown = _ref.beforeKeyDown,
+      afterKeyDown = _ref.afterKeyDown;
+
+  /**
+   * A unique map that stores keyboard shortcut contexts.
+   *
+   * @type {UniqueMap}
+   */
+  var CONTEXTS = createUniqueMap({
+    errorIdExists: function errorIdExists(keys) {
+      return "The \"".concat(keys, "\" context name is already registered.");
+    }
+  });
+  /**
+   * The name of the active [`ShortcutContext`](@/api/shortcutContext.md).
+   *
+   * @type {string}
+   */
+
+  var activeContextName = 'grid';
+  /**
+   * Create a new [`ShortcutContext`](@/api/shortcutContext.md) object.
+   *
+   * @memberof ShortcutManager#
+   * @param {string} contextName The name of the new shortcut context
+   * @returns {object}
+   */
+
+  var addContext = function addContext(contextName) {
+    var context = createContext(contextName);
+    CONTEXTS.addItem(contextName, context);
+    return context;
+  };
+  /**
+   * Get the ID of the active [`ShortcutContext`](@/api/shortcutContext.md).
+   *
+   * @memberof ShortcutManager#
+   * @returns {string}
+   */
+
+
+  var getActiveContextName = function getActiveContextName() {
+    return activeContextName;
+  };
+  /**
+   * Get a keyboard shortcut context by its name.
+   *
+   * @memberof ShortcutManager#
+   * @param {string} contextName The name of the shortcut context
+   * @returns {object|undefined} A [`ShortcutContext`](@/api/shortcutContext.md) object that stores registered shortcuts
+   */
+
+
+  var getContext = function getContext(contextName) {
+    return CONTEXTS.getItem(contextName);
+  };
+  /**
+   * Start listening to keyboard shortcuts within a given [`ShortcutContext`](@/api/shortcutContext.md).
+   *
+   * @memberof ShortcutManager#
+   * @param {string} contextName The name of the shortcut context
+   */
+
+
+  var setActiveContextName = function setActiveContextName(contextName) {
+    activeContextName = contextName;
+  };
+  /**
+   * This variable relates to the `captureCtrl` shortcut option,
+   * which allows for capturing the state of the Control/Meta modifier key.
+   * Some of the default keyboard shortcuts related to cell selection need this feature for working properly.
+   *
+   * @type {boolean}
+   */
+
+
+  var isCtrlKeySilenced = false;
+  /**
+   * Internal key recorder.
+   *
+   * @private
+   */
+
+  var keyRecorder = useRecorder(ownerWindow, handleEvent, beforeKeyDown, afterKeyDown, function (event, keys) {
+    var activeContext = getContext(getActiveContextName());
+    var isExecutionCancelled = false;
+
+    if (!activeContext.hasShortcut(keys)) {
+      return isExecutionCancelled;
+    } // Processing just actions being in stack at the moment of shortcut pressing (without respecting additions/removals performed dynamically).
+
+
+    var shortcuts = activeContext.getShortcuts(keys);
+
+    for (var index = 0; index < shortcuts.length; index++) {
+      var _shortcuts$index = shortcuts[index],
+          callback = _shortcuts$index.callback,
+          runOnlyIf = _shortcuts$index.runOnlyIf,
+          preventDefault = _shortcuts$index.preventDefault,
+          stopPropagation = _shortcuts$index.stopPropagation,
+          captureCtrl = _shortcuts$index.captureCtrl;
+
+      if (runOnlyIf(event) !== false) {
+        isCtrlKeySilenced = captureCtrl;
+        isExecutionCancelled = callback(event, keys) === false;
+        isCtrlKeySilenced = false;
+
+        if (preventDefault) {
+          event.preventDefault();
+        }
+
+        if (stopPropagation) {
+          event.stopPropagation();
+        }
+
+        if (isExecutionCancelled) {
+          break;
+        }
+      }
+    }
+
+    return isExecutionCancelled;
+  });
+  keyRecorder.mount();
+  return {
+    addContext: addContext,
+    getActiveContextName: getActiveContextName,
+    getContext: getContext,
+    setActiveContextName: setActiveContextName,
+
+    /**
+     * Returns whether `control` or `meta` keys are pressed.
+     *
+     * @memberof ShortcutManager#
+     * @type {Function}
+     * @returns {boolean}
+     */
+    isCtrlPressed: function isCtrlPressed() {
+      return !isCtrlKeySilenced && (keyRecorder.isPressed('control') || keyRecorder.isPressed('meta'));
+    },
+
+    /**
+     * Destroy a context manager instance.
+     *
+     * @type {Function}
+     * @memberof ShortcutManager#
+     */
+    destroy: function destroy() {
+      return keyRecorder.unmount();
+    }
+  };
+};

package/shortcuts/recorder.js

@@ -0,0 +1,192 @@
+"use strict";
+
+exports.__esModule = true;
+exports.useRecorder = useRecorder;
+
+require("core-js/modules/es.array.includes.js");
+
+require("core-js/modules/es.array.concat.js");
+
+require("core-js/modules/es.string.includes.js");
+
+var _keyObserver = require("./keyObserver");
+
+var _utils = require("./utils");
+
+var _event = require("../helpers/dom/event");
+
+var _browser = require("../helpers/browser");
+
+var MODIFIER_KEYS = ['meta', 'alt', 'shift', 'control'];
+var modifierKeysObserver = (0, _keyObserver.createKeysObserver)();
+/* eslint-disable jsdoc/require-description-complete-sentence */
+
+/**
+ * A key recorder, used for tracking key events.
+ *
+ * @param {EventTarget} ownerWindow A starting `window` element
+ * @param {Function} handleEvent A condition on which event is handled.
+ * @param {Function} beforeKeyDown A hook fired before the `keydown` event is handled.
+ * @param {Function} afterKeyDown A hook fired after the `keydown` event is handled
+ * @param {Function} callback `KeyEvent`'s listener's callback function
+ * @returns {object}
+ */
+
+function useRecorder(ownerWindow, handleEvent, beforeKeyDown, afterKeyDown, callback) {
+  /**
+   * Check if a pressed key is tracked or not.
+   *
+   * @param {string} pressedKey A pressed key
+   * @returns {boolean}
+   */
+  var isModifierKey = function isModifierKey(pressedKey) {
+    return MODIFIER_KEYS.includes(pressedKey);
+  };
+  /**
+   * Get every pressed modifier key from the performed `KeyboardEvent`.
+   *
+   * @private
+   * @param {KeyboardEvent} event The event object.
+   * @param {boolean} [mergeMetaKeys=false] If `true,` the function will return the "control" and "meta"
+   *                                        modifiers keys as the "control/meta" name. This allows creating
+   *                                        keyboard shortcuts with modifier key that trigger the shortcut
+   *                                        actions depend on the OS keyboard layout (the Meta key for macOS
+   *                                        and Control for non macOS system).
+   * @returns {string[]}
+   */
+
+
+  var getPressedModifierKeys = function getPressedModifierKeys(event) {
+    var mergeMetaKeys = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+    var pressedModifierKeys = [];
+
+    if (event.altKey) {
+      pressedModifierKeys.push('alt');
+    }
+
+    if (mergeMetaKeys && (event.ctrlKey || event.metaKey)) {
+      pressedModifierKeys.push('control/meta');
+    } else {
+      if (event.ctrlKey) {
+        pressedModifierKeys.push('control');
+      }
+
+      if (event.metaKey) {
+        pressedModifierKeys.push('meta');
+      }
+    }
+
+    if (event.shiftKey) {
+      pressedModifierKeys.push('shift');
+    }
+
+    return pressedModifierKeys;
+  };
+  /**
+   * `KeyboardEvent`'s callback function
+   *
+   * @private
+   * @param {KeyboardEvent} event The event object
+   */
+
+
+  var onkeydown = function onkeydown(event) {
+    if (handleEvent(event) === false) {
+      return;
+    }
+
+    var result = beforeKeyDown(event);
+
+    if (result === false || (0, _event.isImmediatePropagationStopped)(event)) {
+      return;
+    }
+
+    var pressedKey = (0, _utils.normalizeEventKey)(event.key);
+    var extraModifierKeys = [];
+
+    if (isModifierKey(pressedKey)) {
+      modifierKeysObserver.press(pressedKey);
+    } else {
+      extraModifierKeys = getPressedModifierKeys(event);
+    }
+
+    var pressedKeys = [pressedKey].concat(extraModifierKeys);
+    var isExecutionCancelled = callback(event, pressedKeys);
+
+    if (!isExecutionCancelled && ((0, _browser.isMacOS)() && extraModifierKeys.includes('meta') || !(0, _browser.isMacOS)() && extraModifierKeys.includes('control'))) {
+      // Trigger the callback for the virtual OS-dependent "control/meta" key
+      callback(event, [pressedKey].concat(getPressedModifierKeys(event, true)));
+    }
+
+    afterKeyDown(event);
+  };
+  /**
+   * `KeyboardEvent`'s callback function
+   *
+   * @private
+   * @param {KeyboardEvent} event The event object
+   */
+
+
+  var onkeyup = function onkeyup(event) {
+    if (handleEvent(event) === false) {
+      return;
+    }
+
+    var pressedKey = (0, _utils.normalizeEventKey)(event.key);
+
+    if (isModifierKey(pressedKey) === false) {
+      return;
+    }
+
+    modifierKeysObserver.release(pressedKey);
+  };
+  /**
+   * `FocusEvent`'s callback function
+   *
+   * @private
+   */
+
+
+  var onblur = function onblur() {
+    modifierKeysObserver.releaseAll();
+  };
+  /**
+   * Add event listeners to the starting window and its parents' windows.
+   */
+
+
+  var mount = function mount() {
+    var eventTarget = ownerWindow;
+
+    while (eventTarget) {
+      eventTarget.addEventListener('keydown', onkeydown);
+      eventTarget.addEventListener('keyup', onkeyup);
+      eventTarget.addEventListener('blur', onblur);
+      eventTarget = eventTarget.frameElement;
+    }
+  };
+  /**
+   * Remove event listeners from the starting window and its parents' windows.
+   */
+
+
+  var unmount = function unmount() {
+    var eventTarget = ownerWindow;
+
+    while (eventTarget) {
+      eventTarget.removeEventListener('keydown', onkeydown);
+      eventTarget.removeEventListener('keyup', onkeyup);
+      eventTarget.removeEventListener('blur', onblur);
+      eventTarget = eventTarget.frameElement;
+    }
+  };
+
+  return {
+    mount: mount,
+    unmount: unmount,
+    isPressed: function isPressed(key) {
+      return modifierKeysObserver.isPressed(key);
+    }
+  };
+}