fix: restore modal launcher focus for MenuButton refs (#22161)

adamalston · web-flow · commit c466ab9a2f99 · 2026-05-05T22:48:48.000Z
diff --git a/packages/react/src/components/Modal/Modal-test.js b/packages/react/src/components/Modal/Modal-test.js
@@ -15,6 +15,8 @@ import { FeatureFlags } from '../FeatureFlags';
 import { ModalPresence, withModalPresence } from './ModalPresence';
 import OverflowMenu from '../OverflowMenu';
 import OverflowMenuItem from '../OverflowMenuItem';
+import { MenuButton } from '../MenuButton';
+import { MenuItem } from '../Menu';
 
 const prefix = 'cds';
 
@@ -49,7 +51,7 @@ describe.each([
     Component: ModalWithPresenceContext,
     isPresence: true,
   },
-])('$title', ({ Component, isPresence }) => {
+])('$title', ({ Component, isPresence, title }) => {
   it('should add extra classes that are passed via className', () => {
     render(
       <Component data-testid="modal-1" className="custom-class">
@@ -582,6 +584,58 @@ describe.each([
     expect(button).toHaveFocus();
   });
 
+  it('should focus `MenuButton` trigger on close when `launcherButtonRef` is `MenuButton`', async () => {
+    const ModalExample = () => {
+      const launcherButtonRef = useRef(null);
+      const [isOpen, setIsOpen] = useState(false);
+
+      return (
+        <>
+          <MenuButton label="Actions" ref={launcherButtonRef}>
+            <MenuItem label="Open modal" onClick={() => setIsOpen(true)} />
+          </MenuButton>
+          <Component
+            data-testid="modal"
+            launcherButtonRef={launcherButtonRef}
+            open={isOpen}
+            onRequestClose={() => setIsOpen(false)}
+          />
+        </>
+      );
+    };
+
+    render(<ModalExample />);
+
+    await userEvent.click(screen.getByRole('button', { name: 'Actions' }));
+    await userEvent.click(screen.getByRole('menuitem', { name: 'Open modal' }));
+
+    expect(screen.getByTestId('modal')).toHaveClass(
+      'cds--layer-one',
+      'cds--modal',
+      'cds--modal-tall',
+      'is-visible',
+      ...(title === 'Modal with presence context'
+        ? ['cds--modal--enable-presence']
+        : []),
+      { exact: true }
+    );
+
+    await userEvent.click(screen.getByRole('button', { name: 'Close' }));
+
+    if (isPresence) {
+      expect(screen.queryByTestId('modal')).not.toBeInTheDocument();
+    } else {
+      expect(screen.getByTestId('modal')).toHaveClass(
+        'cds--layer-one',
+        'cds--modal',
+        'cds--modal-tall',
+        { exact: true }
+      );
+    }
+
+    expect(screen.getByRole('button', { name: 'Actions' })).toHaveFocus();
+  });
+
   describe('enable-dialog-element feature flag', () => {
     it('should bring launcherButtonRef element into focus on close when the ref is defined', async () => {
       const ModalExample = () => {
diff --git a/packages/react/src/components/Modal/Modal.tsx b/packages/react/src/components/Modal/Modal.tsx
@@ -8,6 +8,7 @@
 import PropTypes, { type Validator } from 'prop-types';
 import React, {
   cloneElement,
+  useCallback,
   useContext,
   useEffect,
   useRef,
@@ -34,6 +35,7 @@ import { useMergedRefs } from '../../internal/useMergedRefs';
 import { usePrefix } from '../../internal/usePrefix';
 import { usePreviousValue } from '../../internal/usePreviousValue';
 import { keys, match } from '../../internal/keyboard';
+import { selectorTabbable } from '../../internal/keyboard/navigation';
 import { IconButton } from '../IconButton';
 import { noopFn } from '../../internal/noopFn';
 import { Text } from '../Text';
@@ -122,7 +124,7 @@ export interface ModalProps extends HTMLAttributes<HTMLDivElement> {
   /**
    * Provide a ref to return focus to once the modal is closed.
    */
-  launcherButtonRef?: RefObject<HTMLButtonElement | null>;
+  launcherButtonRef?: RefObject<HTMLElement | null>;
 
   /**
    * Specify the description for the loading text
@@ -585,6 +587,17 @@ const ModalDialog = React.forwardRef(function ModalDialog(
     }
   }, [open, prefix, enableDialogElement]);
 
+  const focusLauncherButton = useCallback(() => {
+    if (!launcherButtonRef || !launcherButtonRef.current) return;
+
+    const { current: launcherButton } = launcherButtonRef;
+    const focusTarget = launcherButton.matches(selectorTabbable)
+      ? launcherButton
+      : launcherButton.querySelector<HTMLElement>(selectorTabbable);
+
+    focusTarget?.focus();
+  }, [launcherButtonRef]);
+
   useEffect(() => {
     if (
       !enableDialogElement &&
@@ -594,23 +607,29 @@ const ModalDialog = React.forwardRef(function ModalDialog(
       launcherButtonRef
     ) {
       setTimeout(() => {
-        if ('current' in launcherButtonRef) {
-          launcherButtonRef.current?.focus();
-        }
+        focusLauncherButton();
       });
     }
-  }, [open, prevOpen, launcherButtonRef, enableDialogElement, enablePresence]);
+  }, [
+    open,
+    prevOpen,
+    launcherButtonRef,
+    enableDialogElement,
+    enablePresence,
+    focusLauncherButton,
+  ]);
+
   // Focus launcherButtonRef on unmount
   useEffect(() => {
     const launcherButton = launcherButtonRef?.current;
     return () => {
       if (enablePresence && launcherButton) {
         setTimeout(() => {
-          launcherButton.focus();
+          focusLauncherButton();
         });
       }
     };
-  }, [enablePresence, launcherButtonRef]);
+  }, [enablePresence, launcherButtonRef, focusLauncherButton]);
 
   useEffect(() => {
     if (!enableDialogElement) {
@@ -964,16 +983,16 @@ Modal.propTypes = {
     PropTypes.func,
     PropTypes.shape({
       current: PropTypes.oneOfType([
-        // `PropTypes.instanceOf(HTMLButtonElement)` alone won't work because
-        // `HTMLButtonElement` is not defined in the test environment even
+        // `PropTypes.instanceOf(HTMLElement)` alone won't work because
+        // `HTMLElement` is not defined in the test environment even
         // though `testEnvironment` is set to `jsdom`.
-        typeof HTMLButtonElement !== 'undefined'
-          ? PropTypes.instanceOf(HTMLButtonElement)
+        typeof HTMLElement !== 'undefined'
+          ? PropTypes.instanceOf(HTMLElement)
           : PropTypes.any,
         PropTypes.oneOf([null]),
       ]).isRequired,
     }),
-  ]) as Validator<RefObject<HTMLButtonElement | null>>,
+  ]) as Validator<RefObject<HTMLElement | null>>,
 
   /**
    * Specify the description for the loading text
