feat: manage focus for accessible click/context popups

src/Popup/index.tsx

@@ -15,6 +15,10 @@ import PopupContent from './PopupContent';
 import useOffsetStyle from '../hooks/useOffsetStyle';
 import { useEvent } from '@rc-component/util';
 import type { PortalProps } from '@rc-component/portal';
+import {
+  focusPopupRootOrFirst,
+  handlePopupTabTrap,
+} from '../focusUtils';
 
 export interface MobileConfig {
   mask?: boolean;
@@ -85,6 +89,12 @@ export interface PopupProps {
 
   // Mobile
   mobile?: MobileConfig;
+
+  /**
+   * Move focus into the popup when it opens and return it to `target` when it closes.
+   * Tab cycles within the popup. Escape is handled by Portal `onEsc`.
+   */
+  focusPopup?: boolean;
 }
 
 const Popup = React.forwardRef<HTMLDivElement, PopupProps>((props, ref) => {
@@ -149,8 +159,13 @@ const Popup = React.forwardRef<HTMLDivElement, PopupProps>((props, ref) => {
     stretch,
     targetWidth,
     targetHeight,
+
+    focusPopup,
   } = props;
 
+  const rootRef = React.useRef<HTMLDivElement>(null);
+  const prevOpenRef = React.useRef(false);
+
   const popupContent = typeof popup === 'function' ? popup() : popup;
 
   // We can not remove holder only when motion finished.
@@ -208,12 +223,7 @@ const Popup = React.forwardRef<HTMLDivElement, PopupProps>((props, ref) => {
     offsetY,
   );
 
-  // ========================= Render =========================
-  if (!show) {
-    return null;
-  }
-
-  // >>>>> Misc
+  // >>>>> Misc (computed before conditional return; hooks must run every render)
   const miscStyle: React.CSSProperties = {};
   if (stretch) {
     if (stretch.includes('height') && targetHeight) {
@@ -232,6 +242,49 @@ const Popup = React.forwardRef<HTMLDivElement, PopupProps>((props, ref) => {
     miscStyle.pointerEvents = 'none';
   }
 
+  useLayoutEffect(() => {
+    if (!focusPopup) {
+      prevOpenRef.current = open;
+      return;
+    }
+
+    const root = rootRef.current;
+    const wasOpen = prevOpenRef.current;
+    prevOpenRef.current = open;
+
+    if (open && !wasOpen && root && isNodeVisible) {
+      focusPopupRootOrFirst(root);
+    } else if (!open && wasOpen && root) {
+      const active = document.activeElement as HTMLElement | null;
+      if (
+        target &&
+        active &&
+        (root === active || root.contains(active))
+      ) {
+        if (target.isConnected) {
+          target.focus();
+        }
+      }
+    }
+  }, [open, focusPopup, isNodeVisible, target]);
+
+  const onPopupKeyDownCapture = useEvent(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      if (!focusPopup || !open) {
+        return;
+      }
+      const root = rootRef.current;
+      if (root) {
+        handlePopupTabTrap(e, root);
+      }
+    },
+  );
+
+  // ========================= Render =========================
+  if (!show) {
+    return null;
+  }
+
   return (
     <Portal
       open={forceRender || isNodeVisible}
@@ -276,7 +329,7 @@ const Popup = React.forwardRef<HTMLDivElement, PopupProps>((props, ref) => {
 
                 return (
                   <div
-                    ref={composeRef(resizeObserverRef, ref, motionRef)}
+                    ref={composeRef(resizeObserverRef, ref, motionRef, rootRef)}
                     className={cls}
                     style={
                       {
@@ -295,6 +348,7 @@ const Popup = React.forwardRef<HTMLDivElement, PopupProps>((props, ref) => {
                     onPointerEnter={onPointerEnter}
                     onClick={onClick}
                     onPointerDownCapture={onPointerDownCapture}
+                    onKeyDownCapture={onPopupKeyDownCapture}
                   >
                     {arrow && (
                       <Arrow

src/UniqueProvider/index.tsx

@@ -223,6 +223,7 @@ const UniqueProvider = ({
             motion={mergedOptions.popupMotion}
             maskMotion={mergedOptions.maskMotion}
             getPopupContainer={mergedOptions.getPopupContainer}
+            focusPopup={mergedOptions.focusPopup}
           >
             <UniqueContainer
               prefixCls={prefixCls}

src/context.ts

@@ -36,6 +36,7 @@ export interface UniqueShowOptions {
   getPopupContainer?: TriggerProps['getPopupContainer'];
   getPopupClassNameFromAlign?: (align: AlignType) => string;
   onEsc?: PortalProps['onEsc'];
+  focusPopup?: boolean;
 }
 
 export interface UniqueContextProps {

src/focusUtils.ts

@@ -0,0 +1,91 @@
+import type * as React from 'react';
+
+const TABBABLE_SELECTOR =
+  'a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])';
+
+function isTabbable(el: HTMLElement, win: Window): boolean {
+  if (el.closest('[aria-hidden="true"]')) {
+    return false;
+  }
+  if ('disabled' in el && (el as HTMLButtonElement).disabled) {
+    return false;
+  }
+  if (el instanceof HTMLInputElement && el.type === 'hidden') {
+    return false;
+  }
+  const ti = el.getAttribute('tabindex');
+  if (ti !== null && Number(ti) < 0) {
+    return false;
+  }
+  const style = win.getComputedStyle(el);
+  if (style.display === 'none' || style.visibility === 'hidden') {
+    return false;
+  }
+  return true;
+}
+
+/** Visible, tabbable descendants inside `container` (in DOM order). */
+export function getTabbableElements(container: HTMLElement): HTMLElement[] {
+  const doc = container.ownerDocument;
+  const win = doc.defaultView!;
+  const nodeList = container.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR);
+  const list: HTMLElement[] = [];
+  for (let i = 0; i < nodeList.length; i += 1) {
+    const el = nodeList[i];
+    if (isTabbable(el, win)) {
+      list.push(el);
+    }
+  }
+  return list;
+}
+
+export function focusPopupRootOrFirst(
+  container: HTMLElement,
+): HTMLElement | null {
+  const tabbables = getTabbableElements(container);
+  if (tabbables.length) {
+    tabbables[0].focus();
+    return tabbables[0];
+  }
+  if (!container.hasAttribute('tabindex')) {
+    container.setAttribute('tabindex', '-1');
+  }
+  container.focus();
+  return container;
+}
+
+export function handlePopupTabTrap(
+  e: React.KeyboardEvent,
+  container: HTMLElement,
+): void {
+  if (e.key !== 'Tab' || e.defaultPrevented) {
+    return;
+  }
+
+  const list = getTabbableElements(container);
+  const active = document.activeElement as HTMLElement | null;
+
+  if (!active || !container.contains(active)) {
+    return;
+  }
+
+  if (list.length === 0) {
+    if (active === container) {
+      e.preventDefault();
+    }
+    return;
+  }
+
+  const first = list[0];
+  const last = list[list.length - 1];
+
+  if (!e.shiftKey) {
+    if (active === last || active === container) {
+      e.preventDefault();
+      first.focus();
+    }
+  } else if (active === first || active === container) {
+    e.preventDefault();
+    last.focus();
+  }
+}

src/index.tsx

@@ -130,6 +130,14 @@ export interface TriggerProps {
    */
   unique?: boolean;
 
+  /**
+   * When true, moves focus into the popup on open (first tabbable node or the popup root with
+   * `tabIndex={-1}`), restores focus to the trigger on close, and keeps Tab cycling inside the
+   * popup. When undefined, enabled for click / contextMenu / focus triggers unless `hover` is also
+   * a show action (so hover-only tooltips are unchanged).
+   */
+  focusPopup?: boolean;
+
   // ==================== Arrow ====================
   arrow?: boolean | ArrowTypeOuter;
 
@@ -211,6 +219,8 @@ export function generateTrigger(
       // Private
       mobile,
 
+      focusPopup: focusPopupProp,
+
       ...restProps
     } = props;
 
@@ -331,6 +341,24 @@ export function generateTrigger(
     // Support ref
     const isOpen = useEvent(() => mergedOpen);
 
+    const [showActions, hideActions] = useAction(
+      action,
+      showAction,
+      hideAction,
+    );
+
+    const mergedFocusPopup = React.useMemo(() => {
+      if (focusPopupProp !== undefined) {
+        return focusPopupProp;
+      }
+      return (
+        !showActions.has('hover') &&
+        (showActions.has('click') ||
+          showActions.has('contextMenu') ||
+          showActions.has('focus'))
+      );
+    }, [focusPopupProp, showActions]);
+
     // Extract common options for UniqueProvider
     const getUniqueOptions = useEvent((delay: number = 0) => ({
       popup,
@@ -354,6 +382,7 @@ export function generateTrigger(
       getPopupClassNameFromAlign,
       id,
       onEsc,
+      focusPopup: mergedFocusPopup,
     }));
 
     // Handle controlled state changes for UniqueProvider
@@ -472,12 +501,6 @@ export function generateTrigger(
       isMobile,
     );
 
-    const [showActions, hideActions] = useAction(
-      action,
-      showAction,
-      hideAction,
-    );
-
     const clickToShow = showActions.has('click');
     const clickToHide =
       hideActions.has('click') || hideActions.has('contextMenu');
@@ -838,6 +861,7 @@ export function generateTrigger(
               autoDestroy={mergedAutoDestroy}
               getPopupContainer={getPopupContainer}
               onEsc={onEsc}
+              focusPopup={mergedFocusPopup}
               // Arrow
               align={alignInfo}
               arrow={innerArrow}