@rc-component/util 1.8.1 → 1.9.0

package/es/Dom/focus.d.ts

@@ -9,11 +9,13 @@ export declare function triggerFocus(element?: HTMLElement, option?: InputFocusO
 /**
  * Lock focus in the element.
  * It will force back to the first focusable element when focus leaves the element.
+ * @param id - A stable ID for this lock instance
  */
-export declare function lockFocus(element: HTMLElement): VoidFunction;
+export declare function lockFocus(element: HTMLElement, id: string): VoidFunction;
 /**
  * Lock focus within an element.
  * When locked, focus will be restricted to focusable elements within the specified element.
  * If multiple elements are locked, only the last locked element will be effective.
+ * @returns A function to mark an element as ignored, which will temporarily allow focus on that element even if it's outside the locked area.
  */
-export declare function useLockFocus(lock: boolean, getElement: () => HTMLElement | null): void;
+export declare function useLockFocus(lock: boolean, getElement: () => HTMLElement | null): [ignoreElement: (ele: HTMLElement) => void];

package/es/Dom/focus.js

@@ -1,5 +1,6 @@
 import { useEffect } from 'react';
 import isVisible from "./isVisible";
+import useId from "../hooks/useId";
 function focusable(node, includePositive = false) {
   if (isVisible(node)) {
     const nodeName = node.nodeName.toLowerCase();
@@ -72,9 +73,29 @@ export function triggerFocus(element, option) {
 // ======================================================
 let lastFocusElement = null;
 let focusElements = [];
+// Map stable ID to lock element
+const idToElementMap = new Map();
+// Map stable ID to ignored element
+const ignoredElementMap = new Map();
 function getLastElement() {
   return focusElements[focusElements.length - 1];
 }
+function isIgnoredElement(element) {
+  const lastElement = getLastElement();
+  if (element && lastElement) {
+    // Find the ID that maps to the last element
+    let lockId;
+    for (const [id, ele] of idToElementMap.entries()) {
+      if (ele === lastElement) {
+        lockId = id;
+        break;
+      }
+    }
+    const ignoredEle = ignoredElementMap.get(lockId);
+    return !!ignoredEle && (ignoredEle === element || ignoredEle.contains(element));
+  }
+  return false;
+}
 function hasFocus(element) {
   const {
     activeElement
@@ -86,10 +107,17 @@ function syncFocus() {
   const {
     activeElement
   } = document;
+
+  // If current focus is on an ignored element, don't force it back
+  if (isIgnoredElement(activeElement)) {
+    return;
+  }
   if (lastElement && !hasFocus(lastElement)) {
     const focusableList = getFocusNodeList(lastElement);
     const matchElement = focusableList.includes(lastFocusElement) ? lastFocusElement : focusableList[0];
-    matchElement?.focus();
+    matchElement?.focus({
+      preventScroll: true
+    });
   } else {
     lastFocusElement = activeElement;
   }
@@ -115,9 +143,13 @@ function onWindowKeyDown(e) {
 /**
  * Lock focus in the element.
  * It will force back to the first focusable element when focus leaves the element.
+ * @param id - A stable ID for this lock instance
  */
-export function lockFocus(element) {
+export function lockFocus(element, id) {
   if (element) {
+    // Store the mapping between ID and element
+    idToElementMap.set(id, element);
+
     // Refresh focus elements
     focusElements = focusElements.filter(ele => ele !== element);
     focusElements.push(element);
@@ -132,6 +164,8 @@ export function lockFocus(element) {
   return () => {
     lastFocusElement = null;
     focusElements = focusElements.filter(ele => ele !== element);
+    idToElementMap.delete(id);
+    ignoredElementMap.delete(id);
     if (focusElements.length === 0) {
       window.removeEventListener('focusin', syncFocus);
       window.removeEventListener('keydown', onWindowKeyDown, true);
@@ -143,14 +177,23 @@ export function lockFocus(element) {
  * Lock focus within an element.
  * When locked, focus will be restricted to focusable elements within the specified element.
  * If multiple elements are locked, only the last locked element will be effective.
+ * @returns A function to mark an element as ignored, which will temporarily allow focus on that element even if it's outside the locked area.
  */
 export function useLockFocus(lock, getElement) {
+  const id = useId();
   useEffect(() => {
     if (lock) {
       const element = getElement();
       if (element) {
-        return lockFocus(element);
+        return lockFocus(element, id);
       }
     }
-  }, [lock]);
+  }, [lock, id]);
+  const ignoreElement = ele => {
+    if (ele) {
+      // Set the ignored element using stable ID
+      ignoredElementMap.set(id, ele);
+    }
+  };
+  return [ignoreElement];
 }

package/lib/Dom/focus.d.ts

@@ -9,11 +9,13 @@ export declare function triggerFocus(element?: HTMLElement, option?: InputFocusO
 /**
  * Lock focus in the element.
  * It will force back to the first focusable element when focus leaves the element.
+ * @param id - A stable ID for this lock instance
  */
-export declare function lockFocus(element: HTMLElement): VoidFunction;
+export declare function lockFocus(element: HTMLElement, id: string): VoidFunction;
 /**
  * Lock focus within an element.
  * When locked, focus will be restricted to focusable elements within the specified element.
  * If multiple elements are locked, only the last locked element will be effective.
+ * @returns A function to mark an element as ignored, which will temporarily allow focus on that element even if it's outside the locked area.
  */
-export declare function useLockFocus(lock: boolean, getElement: () => HTMLElement | null): void;
+export declare function useLockFocus(lock: boolean, getElement: () => HTMLElement | null): [ignoreElement: (ele: HTMLElement) => void];

package/lib/Dom/focus.js

@@ -9,6 +9,7 @@ exports.triggerFocus = triggerFocus;
 exports.useLockFocus = useLockFocus;
 var _react = require("react");
 var _isVisible = _interopRequireDefault(require("./isVisible"));
+var _useId = _interopRequireDefault(require("../hooks/useId"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 function focusable(node, includePositive = false) {
   if ((0, _isVisible.default)(node)) {
@@ -82,9 +83,29 @@ function triggerFocus(element, option) {
 // ======================================================
 let lastFocusElement = null;
 let focusElements = [];
+// Map stable ID to lock element
+const idToElementMap = new Map();
+// Map stable ID to ignored element
+const ignoredElementMap = new Map();
 function getLastElement() {
   return focusElements[focusElements.length - 1];
 }
+function isIgnoredElement(element) {
+  const lastElement = getLastElement();
+  if (element && lastElement) {
+    // Find the ID that maps to the last element
+    let lockId;
+    for (const [id, ele] of idToElementMap.entries()) {
+      if (ele === lastElement) {
+        lockId = id;
+        break;
+      }
+    }
+    const ignoredEle = ignoredElementMap.get(lockId);
+    return !!ignoredEle && (ignoredEle === element || ignoredEle.contains(element));
+  }
+  return false;
+}
 function hasFocus(element) {
   const {
     activeElement
@@ -96,10 +117,17 @@ function syncFocus() {
   const {
     activeElement
   } = document;
+
+  // If current focus is on an ignored element, don't force it back
+  if (isIgnoredElement(activeElement)) {
+    return;
+  }
   if (lastElement && !hasFocus(lastElement)) {
     const focusableList = getFocusNodeList(lastElement);
     const matchElement = focusableList.includes(lastFocusElement) ? lastFocusElement : focusableList[0];
-    matchElement?.focus();
+    matchElement?.focus({
+      preventScroll: true
+    });
   } else {
     lastFocusElement = activeElement;
   }
@@ -125,9 +153,13 @@ function onWindowKeyDown(e) {
 /**
  * Lock focus in the element.
  * It will force back to the first focusable element when focus leaves the element.
+ * @param id - A stable ID for this lock instance
  */
-function lockFocus(element) {
+function lockFocus(element, id) {
   if (element) {
+    // Store the mapping between ID and element
+    idToElementMap.set(id, element);
+
     // Refresh focus elements
     focusElements = focusElements.filter(ele => ele !== element);
     focusElements.push(element);
@@ -142,6 +174,8 @@ function lockFocus(element) {
   return () => {
     lastFocusElement = null;
     focusElements = focusElements.filter(ele => ele !== element);
+    idToElementMap.delete(id);
+    ignoredElementMap.delete(id);
     if (focusElements.length === 0) {
       window.removeEventListener('focusin', syncFocus);
       window.removeEventListener('keydown', onWindowKeyDown, true);
@@ -153,14 +187,23 @@ function lockFocus(element) {
  * Lock focus within an element.
  * When locked, focus will be restricted to focusable elements within the specified element.
  * If multiple elements are locked, only the last locked element will be effective.
+ * @returns A function to mark an element as ignored, which will temporarily allow focus on that element even if it's outside the locked area.
  */
 function useLockFocus(lock, getElement) {
+  const id = (0, _useId.default)();
   (0, _react.useEffect)(() => {
     if (lock) {
       const element = getElement();
       if (element) {
-        return lockFocus(element);
+        return lockFocus(element, id);
       }
     }
-  }, [lock]);
+  }, [lock, id]);
+  const ignoreElement = ele => {
+    if (ele) {
+      // Set the ignored element using stable ID
+      ignoredElementMap.set(id, ele);
+    }
+  };
+  return [ignoreElement];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rc-component/util",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Common Utils For React Component",
   "keywords": [
     "react",