feat: Support useLockFocus

docs/demo/focus.md

@@ -0,0 +1,9 @@
+---
+title: Focus Utils
+---
+
+# Focus Utils Demo
+
+Demonstrates the usage of focus-related utility functions.
+
+<code src="../examples/focus.tsx"></code>

docs/examples/focus.tsx

@@ -0,0 +1,41 @@
+import React, { useRef } from 'react';
+import { useLockFocus } from '../../src/Dom/focus';
+import './focus.css';
+
+export default function FocusDemo() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [locking, setLocking] = React.useState(true);
+
+  useLockFocus(locking, () => containerRef.current);
+
+  return (
+    <div style={{ padding: 32 }} className="focus-demo">
+      <h2>Focus Utils Demo</h2>
+
+      {/* External buttons */}
+      <button onClick={() => setLocking(!locking)}>
+        Lock ({String(locking)})
+      </button>
+
+      {/* Middle container - Tab key cycling is limited within this area */}
+      <div
+        ref={containerRef}
+        tabIndex={0}
+        style={{
+          border: '2px solid green',
+          padding: 24,
+          margin: 16,
+          borderRadius: 8,
+          backgroundColor: '#f0f8ff',
+        }}
+      >
+        <button>Container Button 1</button>
+        <button>Container Button 2</button>
+        <button>Container Button 3</button>
+      </div>
+
+      {/* External buttons */}
+      <button>External Button 2</button>
+    </div>
+  );
+}

src/Dom/focus.ts

@@ -1,3 +1,4 @@
+import { useEffect } from 'react';
 import isVisible from './isVisible';
 
 type DisabledElement =
@@ -56,48 +57,6 @@ export function getFocusNodeList(node: HTMLElement, includePositive = false) {
   return res;
 }
 
-let lastFocusElement = null;
-
-/** @deprecated Do not use since this may failed when used in async */
-export function saveLastFocusNode() {
-  lastFocusElement = document.activeElement;
-}
-
-/** @deprecated Do not use since this may failed when used in async */
-export function clearLastFocusNode() {
-  lastFocusElement = null;
-}
-
-/** @deprecated Do not use since this may failed when used in async */
-export function backLastFocusNode() {
-  if (lastFocusElement) {
-    try {
-      // 元素可能已经被移动了
-      lastFocusElement.focus();
-
-      /* eslint-disable no-empty */
-    } catch (e) {
-      // empty
-    }
-    /* eslint-enable no-empty */
-  }
-}
-
-export function limitTabRange(node: HTMLElement, e: KeyboardEvent) {
-  if (e.keyCode === 9) {
-    const tabNodeList = getFocusNodeList(node);
-    const lastTabNode = tabNodeList[e.shiftKey ? 0 : tabNodeList.length - 1];
-    const leavingTab =
-      lastTabNode === document.activeElement || node === document.activeElement;
-
-    if (leavingTab) {
-      const target = tabNodeList[e.shiftKey ? tabNodeList.length - 1 : 0];
-      target.focus();
-      e.preventDefault();
-    }
-  }
-}
-
 export interface InputFocusOptions extends FocusOptions {
   cursor?: 'start' | 'end' | 'all';
 }
@@ -137,3 +96,98 @@ export function triggerFocus(
     }
   }
 }
+
+// ======================================================
+// ==                    Lock Focus                    ==
+// ======================================================
+let lastFocusElement: HTMLElement | null = null;
+let focusElements: HTMLElement[] = [];
+
+function getLastElement() {
+  return focusElements[focusElements.length - 1];
+}
+
+function hasFocus(element: HTMLElement) {
+  const { activeElement } = document;
+  return element === activeElement || element.contains(activeElement);
+}
+
+function syncFocus() {
+  const lastElement = getLastElement();
+  const { activeElement } = document;
+
+  if (lastElement && !hasFocus(lastElement)) {
+    const focusableList = getFocusNodeList(lastElement);
+
+    const matchElement = focusableList.includes(lastFocusElement as HTMLElement)
+      ? lastFocusElement
+      : focusableList[0];
+
+    matchElement?.focus();
+  } else {
+    lastFocusElement = activeElement as HTMLElement;
+  }
+}
+
+function onWindowKeyDown(e: KeyboardEvent) {
+  if (e.key === 'Tab') {
+    const { activeElement } = document;
+    const lastElement = getLastElement();
+    const focusableList = getFocusNodeList(lastElement);
+    const last = focusableList[focusableList.length - 1];
+
+    if (e.shiftKey && activeElement === focusableList[0]) {
+      // Tab backward on first focusable element
+      lastFocusElement = last;
+    } else if (!e.shiftKey && activeElement === last) {
+      // Tab forward on last focusable element
+      lastFocusElement = focusableList[0];
+    }
+  }
+}
+
+/**
+ * Lock focus in the element.
+ * It will force back to the first focusable element when focus leaves the element.
+ */
+export function lockFocus(element: HTMLElement): VoidFunction {
+  if (element) {
+    // Refresh focus elements
+    focusElements = focusElements.filter(ele => ele !== element);
+    focusElements.push(element);
+
+    // Just add event since it will de-duplicate
+    window.addEventListener('focusin', syncFocus);
+    window.addEventListener('keydown', onWindowKeyDown, true);
+    syncFocus();
+  }
+
+  // Always return unregister function
+  return () => {
+    lastFocusElement = null;
+    focusElements = focusElements.filter(ele => ele !== element);
+    if (focusElements.length === 0) {
+      window.removeEventListener('focusin', syncFocus);
+      window.removeEventListener('keydown', onWindowKeyDown, true);
+    }
+  };
+}
+
+/**
+ * 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.
+ */
+export function useLockFocus(
+  lock: boolean,
+  getElement: () => HTMLElement | null,
+) {
+  useEffect(() => {
+    if (lock) {
+      const element = getElement();
+      if (element) {
+        return lockFocus(element);
+      }
+    }
+  }, [lock]);
+}

tests/focus.test.ts → tests/focus.test.tsx

@@ -1,6 +1,8 @@
 /* eslint-disable class-methods-use-this */
+import React, { useRef } from 'react';
+import { render } from '@testing-library/react';
 import { spyElementPrototype } from '../src/test/domHook';
-import { getFocusNodeList, triggerFocus } from '../src/Dom/focus';
+import { getFocusNodeList, triggerFocus, useLockFocus } from '../src/Dom/focus';
 
 describe('focus', () => {
   beforeAll(() => {
@@ -56,4 +58,42 @@ describe('focus', () => {
     focusSpy.mockRestore();
     setSelectionRangeSpy.mockRestore();
   });
+
+  describe('useLockFocus', () => {
+    const TestComponent: React.FC<{ lock: boolean }> = ({ lock }) => {
+      const elementRef = useRef<HTMLDivElement>(null);
+      useLockFocus(lock, () => elementRef.current);
+
+      return (
+        <>
+          <button data-testid="outer-button">Outer</button>
+          <div ref={elementRef} data-testid="focus-container" tabIndex={0}>
+            <input key="input1" data-testid="input1" />
+            <button key="button1" data-testid="button1">
+              Button
+            </button>
+          </div>
+        </>
+      );
+    };
+
+    it('should restore focus to range when focusing other elements', () => {
+      const { getByTestId } = render(<TestComponent lock={true} />);
+
+      const focusContainer = getByTestId('focus-container');
+      const input1 = getByTestId('input1') as HTMLInputElement;
+
+      // Should focus to first focusable element after lock
+      expect(document.activeElement).toBe(focusContainer);
+
+      // Focus inside container first
+      input1.focus();
+      expect(document.activeElement).toBe(input1);
+
+      // Focus outer button
+      const outerButton = getByTestId('outer-button') as HTMLButtonElement;
+      outerButton.focus();
+      expect(document.activeElement).toBe(input1);
+    });
+  });
 });