handsontable 16.1.1 → 16.2.0-next-90d1117-20251117

package/{focusManager.mjs → focusManager/grid.mjs}

@@ -5,9 +5,9 @@ function _checkPrivateRedeclaration(e, t) { if (t.has(e)) throw new TypeError("C
 function _classPrivateFieldGet(s, a) { return s.get(_assertClassBrand(s, a)); }
 function _classPrivateFieldSet(s, a, r) { return s.set(_assertClassBrand(s, a), r), r; }
 function _assertClassBrand(e, t, n) { if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n; throw new TypeError("Private element is not present on this object"); }
-import { warn } from "./helpers/console.mjs";
-import { isHTMLElement, isOutsideInput } from "./helpers/dom/element.mjs";
-import { debounce } from "./helpers/function.mjs";
+import { warn } from "../helpers/console.mjs";
+import { isHTMLElement, isOutsideInput } from "../helpers/dom/element.mjs";
+import { debounce } from "../helpers/function.mjs";
 /**
  * Possible focus modes.
  * - CELL - The browser's focus stays on the lastly selected cell element.
@@ -22,23 +22,24 @@ const FOCUS_MODES = Object.freeze({
 });
 
 /**
- * Manages the browser's focus in the table.
+ * Manages the browser's focus in the table to achieve correct behavior for screen readers and
+ * IME editors.
  */
 var _hot = /*#__PURE__*/new WeakMap();
 var _focusMode = /*#__PURE__*/new WeakMap();
 var _refocusDelay = /*#__PURE__*/new WeakMap();
 var _refocusElementGetter = /*#__PURE__*/new WeakMap();
 var _debouncedSelect = /*#__PURE__*/new WeakMap();
-var _FocusManager_brand = /*#__PURE__*/new WeakSet();
-export class FocusManager {
+var _hasSelectionChange = /*#__PURE__*/new WeakMap();
+var _FocusGridManager_brand = /*#__PURE__*/new WeakSet();
+export class FocusGridManager {
   constructor(hotInstance) {
-    var _this = this;
     /**
      * Get and return the currently selected and highlighted cell/header element.
      *
      * @param {Function} callback Callback function to be called after the cell element is retrieved.
      */
-    _classPrivateMethodInitSpec(this, _FocusManager_brand);
+    _classPrivateMethodInitSpec(this, _FocusGridManager_brand);
     /**
      * The Handsontable instance.
      */
@@ -74,32 +75,47 @@ export class FocusManager {
      * @type {Map<number, Function>}
      */
     _classPrivateFieldInitSpec(this, _debouncedSelect, new Map());
-    const hotSettings = hotInstance.getSettings();
+    /**
+     * Flag to indicate if the selection has changed.
+     *
+     * @type {boolean}
+     */
+    _classPrivateFieldInitSpec(this, _hasSelectionChange, false);
     _classPrivateFieldSet(_hot, this, hotInstance);
+  }
+  init() {
+    var _this = this;
+    const hotSettings = _classPrivateFieldGet(_hot, this).getSettings();
     _classPrivateFieldSet(_focusMode, this, hotSettings.imeFastEdit ? FOCUS_MODES.MIXED : FOCUS_MODES.CELL);
     _classPrivateFieldGet(_hot, this).addHook('afterUpdateSettings', function () {
       for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
         args[_key] = arguments[_key];
       }
-      return _assertClassBrand(_FocusManager_brand, _this, _onUpdateSettings).call(_this, ...args);
+      return _assertClassBrand(_FocusGridManager_brand, _this, _onUpdateSettings).call(_this, ...args);
     });
     _classPrivateFieldGet(_hot, this).addHook('afterSelection', function () {
       for (var _len2 = arguments.length, args = new Array(_len2), _key2 = 0; _key2 < _len2; _key2++) {
         args[_key2] = arguments[_key2];
       }
-      return _assertClassBrand(_FocusManager_brand, _this, _focusCell).call(_this, ...args);
+      return _assertClassBrand(_FocusGridManager_brand, _this, _onAfterSelectionChange).call(_this, ...args);
     });
     _classPrivateFieldGet(_hot, this).addHook('afterSelectionFocusSet', function () {
       for (var _len3 = arguments.length, args = new Array(_len3), _key3 = 0; _key3 < _len3; _key3++) {
         args[_key3] = arguments[_key3];
       }
-      return _assertClassBrand(_FocusManager_brand, _this, _focusCell).call(_this, ...args);
+      return _assertClassBrand(_FocusGridManager_brand, _this, _onAfterSelectionChange).call(_this, ...args);
     });
     _classPrivateFieldGet(_hot, this).addHook('afterSelectionEnd', function () {
       for (var _len4 = arguments.length, args = new Array(_len4), _key4 = 0; _key4 < _len4; _key4++) {
         args[_key4] = arguments[_key4];
       }
-      return _assertClassBrand(_FocusManager_brand, _this, _focusEditorElement).call(_this, ...args);
+      return _assertClassBrand(_FocusGridManager_brand, _this, _focusEditorElement).call(_this, ...args);
+    });
+    _classPrivateFieldGet(_hot, this).addHook('afterRender', function () {
+      for (var _len5 = arguments.length, args = new Array(_len5), _key5 = 0; _key5 < _len5; _key5++) {
+        args[_key5] = arguments[_key5];
+      }
+      return _assertClassBrand(_FocusGridManager_brand, _this, _onAfterRender).call(_this, ...args);
     });
   }
 
@@ -192,7 +208,7 @@ export class FocusManager {
     if (selectedCell) {
       focusElement(selectedCell);
     } else {
-      _assertClassBrand(_FocusManager_brand, this, _getSelectedCell).call(this, element => focusElement(element));
+      _assertClassBrand(_FocusGridManager_brand, this, _getSelectedCell).call(this, element => focusElement(element));
     }
   }
 
@@ -241,7 +257,7 @@ function _getSelectedCell(callback) {
  * Manage the browser's focus after each cell selection change.
  */
 function _focusCell() {
-  _assertClassBrand(_FocusManager_brand, this, _getSelectedCell).call(this, selectedCell => {
+  _assertClassBrand(_FocusGridManager_brand, this, _getSelectedCell).call(this, selectedCell => {
     const {
       activeElement
     } = _classPrivateFieldGet(_hot, this).rootDocument;
@@ -260,12 +276,27 @@ function _focusCell() {
  * Manage the browser's focus after cell selection end.
  */
 function _focusEditorElement() {
-  _assertClassBrand(_FocusManager_brand, this, _getSelectedCell).call(this, selectedCell => {
+  _assertClassBrand(_FocusGridManager_brand, this, _getSelectedCell).call(this, selectedCell => {
     if (this.getFocusMode() === FOCUS_MODES.MIXED && (selectedCell === null || selectedCell === void 0 ? void 0 : selectedCell.nodeName) === 'TD') {
       this.refocusToEditorTextarea();
     }
   });
 }
+/**
+ * Handle the after selection change event.
+ */
+function _onAfterSelectionChange() {
+  _classPrivateFieldSet(_hasSelectionChange, this, true);
+}
+/**
+ * Focuses the cell after the render event when the selection has changed.
+ */
+function _onAfterRender() {
+  if (_classPrivateFieldGet(_hasSelectionChange, this)) {
+    _classPrivateFieldSet(_hasSelectionChange, this, false);
+    _assertClassBrand(_FocusGridManager_brand, this, _focusCell).call(this);
+  }
+}
 /**
  * Update the manager configuration after calling `updateSettings`.
  *

package/focusManager/index.d.ts

@@ -0,0 +1,2 @@
+export * from './grid';
+export * from './scopeManager';

package/focusManager/index.js

@@ -0,0 +1,20 @@
+"use strict";
+
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.for-each.js");
+exports.__esModule = true;
+var _exportNames = {
+  createFocusScopeManager: true,
+  FocusGridManager: true
+};
+var _scopeManager = require("./scopeManager");
+exports.createFocusScopeManager = _scopeManager.createFocusScopeManager;
+var _grid = require("./grid");
+exports.FocusGridManager = _grid.FocusGridManager;
+var _scopes = require("./scopes");
+Object.keys(_scopes).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _scopes[key]) return;
+  exports[key] = _scopes[key];
+});

package/focusManager/index.mjs

@@ -0,0 +1,20 @@
+import { createFocusScopeManager } from "./scopeManager.mjs";
+import { FocusGridManager } from "./grid.mjs";
+export * from "./scopes/index.mjs";
+/**
+ * @typedef {object} FocusScopeManager
+ * @property {function(): string | null} getActiveScopeId Returns the ID of the active scope.
+ * @property {function(string, HTMLElement, object): void} registerScope Registers a new focus scope.
+ * @property {function(string): void} unregisterScope Unregisters a scope by its ID.
+ * @property {function(string): void} activateScope Activates a focus scope by its ID.
+ * @property {function(string): void} deactivateScope Deactivates a scope by its ID.
+ * @property {function(): void} destroy Destroys the focus scope manager.
+ */
+/**
+ * Creates a focus scope manager instance for a Handsontable instance.
+ *
+ * @param {Core} hotInstance The Handsontable instance.
+ * @returns {FocusScopeManager} Focus scope manager object.
+ */
+export { createFocusScopeManager };
+export { FocusGridManager };

package/focusManager/scope.js

@@ -0,0 +1,133 @@
+"use strict";
+
+exports.__esModule = true;
+exports.createFocusScope = createFocusScope;
+var _focusDetector = require("./utils/focusDetector");
+var _constants = require("./constants");
+/**
+ * @typedef {object} FocusScope
+ * @property {function(): string} getType The type of the scope.
+ * @property {function(): boolean} hasContainerDetached Whether the container is detached from the root Handsontable wrapper element.
+ * @property {function(): string} getShortcutsContextName The name of the shortcuts context to switch to when the scope is activated.
+ * @property {function(): boolean} runOnlyIf Whether the scope is enabled or not depends on the custom logic.
+ * @property {function(): boolean} contains Whether the target element is within the scope.
+ * @property {function(): void} activate Activates the scope.
+ * @property {function(): void} deactivate Deactivates the scope.
+ * @property {function(): void} activateFocusCatchers Activates the focus catchers.
+ * @property {function(): void} deactivateFocusCatchers Deactivates the focus catchers.
+ * @property {function(): void} enable Enables the scope.
+ * @property {function(): void} disable Disables the scope.
+ * @property {function(): void} destroy Destroys the scope.
+ */
+/**
+ * Creates a focus scope with its own boundaries.
+ *
+ * @param {Core} hotInstance The Handsontable instance.
+ * @param {HTMLElement} container Container element for the scope.
+ * @param {object} [options] Configuration options.
+ * @param {string} [options.shortcutsContextName='grid'] The name of the shortcuts context to switch to when
+ * the scope is activated.
+ * @param {'modal' | 'inline'} [options.type='inline'] The type of the scope:<br/>
+ *   - `modal`: The scope is modal and blocks the rest of the grid from receiving focus.<br/>
+ *   - `inline`: The scope is inline and allows the rest of the grid to receive focus in the order of the rendered elements in the DOM.
+ * @param {function(): boolean} [options.runOnlyIf] Whether the scope is enabled or not depends on the custom logic.
+ * @param {function(HTMLElement): boolean} [options.contains] Whether the target element is within the scope. If the option is not
+ *  provided, the scope will be activated if the target element is within the container element.
+ * @param {function(): void} [options.onActivate] Callback function to be called when the scope is activated.
+ * The first argument is the source of the activation:<br/>
+ *   - `unknown`: The scope is activated by an unknown source.<br/>
+ *   - `click`: The scope is activated by a click event.<br/>
+ *   - `tab_from_above`: The scope is activated by a tab key press.<br/>
+ *   - `tab_from_below`: The scope is activated by a shift+tab key press.
+ * @param {function(): void} [options.onDeactivate] Callback function to be called when the scope is deactivated.
+ * @returns {FocusScope} Focus scope object with methods.
+ */
+function createFocusScope(hotInstance, container) {
+  let options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  const mergedOptions = {
+    shortcutsContextName: _constants.DEFAULT_SHORTCUTS_CONTEXT,
+    type: _constants.SCOPE_TYPES.INLINE,
+    contains: target => target === container || container.contains(target),
+    runOnlyIf: () => true,
+    ...options
+  };
+  const focusCatchers = (0, _focusDetector.installFocusDetector)(hotInstance, container);
+
+  /**
+   * Checks if the target element is within the scope boundaries.
+   *
+   * @param {HTMLElement} target The target element to check.
+   * @returns {boolean}
+   */
+  const contains = target => {
+    return mergedOptions.contains(target);
+  };
+
+  /**
+   * Disables the focus catchers.
+   */
+  const deactivateFocusCatchers = () => {
+    focusCatchers === null || focusCatchers === void 0 || focusCatchers.deactivate();
+  };
+
+  /**
+   * Enables the focus catchers.
+   */
+  const activateFocusCatchers = () => {
+    focusCatchers === null || focusCatchers === void 0 || focusCatchers.activate();
+  };
+
+  /**
+   * Activates the scope.
+   *
+   * @param {'unknown' | 'click' | 'tab_from_above' | 'tab_from_below'} activationSource The source of the activation.
+   */
+  const activate = function () {
+    var _mergedOptions$onActi;
+    let activationSource = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : _constants.FOCUS_SOURCES.UNKNOWN;
+    (_mergedOptions$onActi = mergedOptions.onActivate) === null || _mergedOptions$onActi === void 0 || _mergedOptions$onActi.call(mergedOptions, activationSource);
+  };
+
+  /**
+   * Deactivates the scope.
+   */
+  const deactivate = () => {
+    var _mergedOptions$onDeac;
+    (_mergedOptions$onDeac = mergedOptions.onDeactivate) === null || _mergedOptions$onDeac === void 0 || _mergedOptions$onDeac.call(mergedOptions);
+  };
+
+  /**
+   * Enables the scope so the scope container can be focused.
+   */
+  const enable = () => {
+    container.removeAttribute('inert');
+  };
+
+  /**
+   * Disables the scope so the scope container can't be focused.
+   */
+  const disable = () => {
+    container.setAttribute('inert', 'true');
+  };
+
+  /**
+   * Destroys the scope.
+   */
+  const destroy = () => {
+    focusCatchers === null || focusCatchers === void 0 || focusCatchers.destroy();
+  };
+  return {
+    getType: () => mergedOptions.type,
+    hasContainerDetached: () => !hotInstance.rootWrapperElement.contains(container),
+    getShortcutsContextName: () => mergedOptions.shortcutsContextName,
+    runOnlyIf: () => mergedOptions.runOnlyIf(),
+    contains,
+    activate,
+    deactivate,
+    activateFocusCatchers,
+    deactivateFocusCatchers,
+    enable,
+    disable,
+    destroy
+  };
+}

package/focusManager/scope.mjs

@@ -0,0 +1,129 @@
+import { installFocusDetector } from "./utils/focusDetector.mjs";
+import { SCOPE_TYPES, FOCUS_SOURCES, DEFAULT_SHORTCUTS_CONTEXT } from "./constants.mjs";
+/**
+ * @typedef {object} FocusScope
+ * @property {function(): string} getType The type of the scope.
+ * @property {function(): boolean} hasContainerDetached Whether the container is detached from the root Handsontable wrapper element.
+ * @property {function(): string} getShortcutsContextName The name of the shortcuts context to switch to when the scope is activated.
+ * @property {function(): boolean} runOnlyIf Whether the scope is enabled or not depends on the custom logic.
+ * @property {function(): boolean} contains Whether the target element is within the scope.
+ * @property {function(): void} activate Activates the scope.
+ * @property {function(): void} deactivate Deactivates the scope.
+ * @property {function(): void} activateFocusCatchers Activates the focus catchers.
+ * @property {function(): void} deactivateFocusCatchers Deactivates the focus catchers.
+ * @property {function(): void} enable Enables the scope.
+ * @property {function(): void} disable Disables the scope.
+ * @property {function(): void} destroy Destroys the scope.
+ */
+/**
+ * Creates a focus scope with its own boundaries.
+ *
+ * @param {Core} hotInstance The Handsontable instance.
+ * @param {HTMLElement} container Container element for the scope.
+ * @param {object} [options] Configuration options.
+ * @param {string} [options.shortcutsContextName='grid'] The name of the shortcuts context to switch to when
+ * the scope is activated.
+ * @param {'modal' | 'inline'} [options.type='inline'] The type of the scope:<br/>
+ *   - `modal`: The scope is modal and blocks the rest of the grid from receiving focus.<br/>
+ *   - `inline`: The scope is inline and allows the rest of the grid to receive focus in the order of the rendered elements in the DOM.
+ * @param {function(): boolean} [options.runOnlyIf] Whether the scope is enabled or not depends on the custom logic.
+ * @param {function(HTMLElement): boolean} [options.contains] Whether the target element is within the scope. If the option is not
+ *  provided, the scope will be activated if the target element is within the container element.
+ * @param {function(): void} [options.onActivate] Callback function to be called when the scope is activated.
+ * The first argument is the source of the activation:<br/>
+ *   - `unknown`: The scope is activated by an unknown source.<br/>
+ *   - `click`: The scope is activated by a click event.<br/>
+ *   - `tab_from_above`: The scope is activated by a tab key press.<br/>
+ *   - `tab_from_below`: The scope is activated by a shift+tab key press.
+ * @param {function(): void} [options.onDeactivate] Callback function to be called when the scope is deactivated.
+ * @returns {FocusScope} Focus scope object with methods.
+ */
+export function createFocusScope(hotInstance, container) {
+  let options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  const mergedOptions = {
+    shortcutsContextName: DEFAULT_SHORTCUTS_CONTEXT,
+    type: SCOPE_TYPES.INLINE,
+    contains: target => target === container || container.contains(target),
+    runOnlyIf: () => true,
+    ...options
+  };
+  const focusCatchers = installFocusDetector(hotInstance, container);
+
+  /**
+   * Checks if the target element is within the scope boundaries.
+   *
+   * @param {HTMLElement} target The target element to check.
+   * @returns {boolean}
+   */
+  const contains = target => {
+    return mergedOptions.contains(target);
+  };
+
+  /**
+   * Disables the focus catchers.
+   */
+  const deactivateFocusCatchers = () => {
+    focusCatchers === null || focusCatchers === void 0 || focusCatchers.deactivate();
+  };
+
+  /**
+   * Enables the focus catchers.
+   */
+  const activateFocusCatchers = () => {
+    focusCatchers === null || focusCatchers === void 0 || focusCatchers.activate();
+  };
+
+  /**
+   * Activates the scope.
+   *
+   * @param {'unknown' | 'click' | 'tab_from_above' | 'tab_from_below'} activationSource The source of the activation.
+   */
+  const activate = function () {
+    var _mergedOptions$onActi;
+    let activationSource = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : FOCUS_SOURCES.UNKNOWN;
+    (_mergedOptions$onActi = mergedOptions.onActivate) === null || _mergedOptions$onActi === void 0 || _mergedOptions$onActi.call(mergedOptions, activationSource);
+  };
+
+  /**
+   * Deactivates the scope.
+   */
+  const deactivate = () => {
+    var _mergedOptions$onDeac;
+    (_mergedOptions$onDeac = mergedOptions.onDeactivate) === null || _mergedOptions$onDeac === void 0 || _mergedOptions$onDeac.call(mergedOptions);
+  };
+
+  /**
+   * Enables the scope so the scope container can be focused.
+   */
+  const enable = () => {
+    container.removeAttribute('inert');
+  };
+
+  /**
+   * Disables the scope so the scope container can't be focused.
+   */
+  const disable = () => {
+    container.setAttribute('inert', 'true');
+  };
+
+  /**
+   * Destroys the scope.
+   */
+  const destroy = () => {
+    focusCatchers === null || focusCatchers === void 0 || focusCatchers.destroy();
+  };
+  return {
+    getType: () => mergedOptions.type,
+    hasContainerDetached: () => !hotInstance.rootWrapperElement.contains(container),
+    getShortcutsContextName: () => mergedOptions.shortcutsContextName,
+    runOnlyIf: () => mergedOptions.runOnlyIf(),
+    contains,
+    activate,
+    deactivate,
+    activateFocusCatchers,
+    deactivateFocusCatchers,
+    enable,
+    disable,
+    destroy
+  };
+}

package/focusManager/scopeManager.d.ts

@@ -0,0 +1,19 @@
+type FocusScopeType = 'modal' | 'inline';
+type FocusScopeActivationSource = 'unknown' | 'click' | 'tab_from_above' | 'tab_from_below';
+
+type FocusScopeOptions = {
+  shortcutsContextName?: string;
+  type?: FocusScopeType;
+  contains?: (target: HTMLElement) => boolean;
+  runOnlyIf?: () => boolean;
+  onActivate?: (focusSource: FocusScopeActivationSource) => void;
+  onDeactivate?: () => void;
+};
+
+export interface FocusScopeManager {
+  getActiveScopeId(): string | null;
+  registerScope(scopeId: string, container: HTMLElement, options?: FocusScopeOptions): void;
+  unregisterScope(scopeId: string): void;
+  activateScope(scopeId: string): void;
+  deactivateScope(scopeId: string): void;
+}