Merge branch 'master' into react-19-up

Author: li-jia-nan

.dumirc.ts

@@ -1,5 +1,6 @@
 // more config: https://d.umijs.org/config
 import { defineConfig } from 'dumi';
+import path from 'path';
 
 const basePath = process.env.GITHUB_ACTIONS ? '/util/' : '/';
 const publicPath = process.env.GITHUB_ACTIONS ? '/util/' : '/';
@@ -14,4 +15,7 @@ export default defineConfig({
   exportStatic: {},
   base: basePath,
   publicPath,
+  alias: {
+    'rc-util/es': path.resolve(__dirname, 'src'),
+  },
 });

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,40 @@
+import React, { useRef } from 'react';
+import { useLockFocus } from '../../src/Dom/focus';
+
+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>
+  );
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rc-component/util",
-  "version": "1.3.1",
+  "version": "1.7.0",
   "description": "Common Utils For React Component",
   "keywords": [
     "react",
@@ -53,7 +53,7 @@
     "@types/responselike": "^1.0.0",
     "@types/warning": "^3.0.0",
     "@umijs/fabric": "^3.0.0",
-    "cross-env": "^7.0.2",
+    "cross-env": "^10.1.0",
     "dumi": "^2.1.3",
     "eslint": "^8.54.0",
     "eslint-plugin-jest": "^29.0.1",

src/Dom/focus.ts

@@ -1,3 +1,4 @@
+import { useEffect } from 'react';
 import isVisible from './isVisible';
 
 type DisabledElement =
@@ -56,44 +57,137 @@ export function getFocusNodeList(node: HTMLElement, includePositive = false) {
   return res;
 }
 
-let lastFocusElement = null;
+export interface InputFocusOptions extends FocusOptions {
+  cursor?: 'start' | 'end' | 'all';
+}
+
+// Used for `rc-input` `rc-textarea` `rc-input-number`
+/**
+ * Focus element and set cursor position for input/textarea elements.
+ */
+export function triggerFocus(
+  element?: HTMLElement,
+  option?: InputFocusOptions,
+) {
+  if (!element) return;
+
+  element.focus(option);
+
+  // Selection content
+  const { cursor } = option || {};
+  if (
+    cursor &&
+    (element instanceof HTMLInputElement ||
+      element instanceof HTMLTextAreaElement)
+  ) {
+    const len = element.value.length;
+
+    switch (cursor) {
+      case 'start':
+        element.setSelectionRange(0, 0);
+        break;
+
+      case 'end':
+        element.setSelectionRange(len, len);
+        break;
 
-/** @deprecated Do not use since this may failed when used in async */
-export function saveLastFocusNode() {
-  lastFocusElement = document.activeElement;
+      default:
+        element.setSelectionRange(0, len);
+    }
+  }
+}
+
+// ======================================================
+// ==                    Lock Focus                    ==
+// ======================================================
+let lastFocusElement: HTMLElement | null = null;
+let focusElements: HTMLElement[] = [];
+
+function getLastElement() {
+  return focusElements[focusElements.length - 1];
 }
 
-/** @deprecated Do not use since this may failed when used in async */
-export function clearLastFocusNode() {
-  lastFocusElement = null;
+function hasFocus(element: HTMLElement) {
+  const { activeElement } = document;
+  return element === activeElement || element.contains(activeElement);
 }
 
-/** @deprecated Do not use since this may failed when used in async */
-export function backLastFocusNode() {
-  if (lastFocusElement) {
-    try {
-      // 元素可能已经被移动了
-      lastFocusElement.focus();
+function syncFocus() {
+  const lastElement = getLastElement();
+  const { activeElement } = document;
 
-      /* eslint-disable no-empty */
-    } catch (e) {
-      // empty
-    }
-    /* eslint-enable no-empty */
+  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;
   }
 }
 
-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();
+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]);
+}

src/KeyCode.ts

@@ -517,6 +517,26 @@ const KeyCode = {
         return false;
     }
   },
+
+  isEditableTarget: function isEditableTarget(e: KeyboardEvent) {
+    const target = e.target;
+
+    if (!(target instanceof HTMLElement)) {
+      return false;
+    }
+
+    const tagName = target.tagName;
+    if (
+      tagName === 'INPUT' ||
+      tagName === 'TEXTAREA' ||
+      tagName === 'SELECT' ||
+      target.isContentEditable
+    ) {
+      return true;
+    }
+
+    return false;
+  },
 };
 
 export default KeyCode;

src/index.ts

@@ -3,7 +3,7 @@ export { default as useMergedState } from './hooks/useMergedState';
 export { default as useControlledState } from './hooks/useControlledState';
 export { supportNodeRef, supportRef, useComposeRef } from './ref';
 export { default as get } from './utils/get';
-export { default as set, merge } from './utils/set';
+export { default as set, merge, mergeWith } from './utils/set';
 export { default as warning, noteOnce } from './warning';
 export { default as omit } from './omit';
 export { default as toArray } from './Children/toArray';

src/test/mergeWith.test.ts

@@ -0,0 +1,16 @@
+import { mergeWith } from '../utils/set';
+
+describe('mergeWith array merge', () => {
+  it('should keep existing array length when merging sparse updates', () => {
+    const allValues = { list: ['A', 'B', 'C', 'D'] };
+    const changedValues = { list: new Array(2) };
+    changedValues.list[1] = 'BB'; // 仅更新第 2 项，长度为 2
+
+    const merged = mergeWith([allValues, changedValues], {
+      prepareArray: current => [...(current || [])],
+    });
+
+    expect(merged.list).toEqual(['A', 'BB', 'C', 'D']);
+    expect(merged.list).toHaveLength(4);
+  });
+});

src/utils/set.ts

@@ -66,10 +66,25 @@ function createEmpty<T>(source: T) {
 
 const keys = typeof Reflect === 'undefined' ? Object.keys : Reflect.ownKeys;
 
+// ================================ Merge ================================
+export type MergeFn = (current: any, next: any) => any;
+
 /**
- * Merge objects which will create
+ * Merge multiple objects. Support custom merge logic.
+ * @param sources object sources
+ * @param config.prepareArray Customize array prepare function.
+ * It will return empty [] by default.
+ * So when match array, it will auto be override with next array in sources.
  */
-export function merge<T extends object>(...sources: T[]) {
+export function mergeWith<T extends object>(
+  sources: T[],
+  config: {
+    prepareArray?: MergeFn;
+  } = {},
+) {
+  const { prepareArray } = config;
+  const finalPrepareArray: MergeFn = prepareArray || (() => []);
+
   let clone = createEmpty(sources[0]);
 
   sources.forEach(src => {
@@ -89,14 +104,16 @@ export function merge<T extends object>(...sources: T[]) {
 
           if (isArr) {
             // Array will always be override
-            clone = set(clone, path, []);
+            clone = set(clone, path, finalPrepareArray(originValue, value));
           } else if (!originValue || typeof originValue !== 'object') {
             // Init container if not exist
             clone = set(clone, path, createEmpty(value));
           }
 
           keys(value).forEach(key => {
-            internalMerge([...path, key], loopSet);
+            if (Object.getOwnPropertyDescriptor(value, key).enumerable) {
+              internalMerge([...path, key], loopSet);
+            }
           });
         }
       } else {
@@ -109,3 +126,11 @@ export function merge<T extends object>(...sources: T[]) {
 
   return clone;
 }
+
+/**
+ * Merge multiple objects into a new single object.
+ * Arrays will be replaced by default.
+ */
+export function merge<T extends object>(...sources: T[]) {
+  return mergeWith(sources);
+}