feat(Modal): add launcherButtonRef prop to handle focus on close

e2e/components/Modal/Modal-test.avt.e2e.js

@@ -31,12 +31,12 @@ test.describe('Modal @avt', () => {
       },
     });
 
+    const button = page.getByRole('button', { name: 'Launch modal' });
+
     // Open the modal via keyboard navigation
     await page.keyboard.press('Tab');
-    await expect(
-      page.getByRole('button', { name: 'Launch modal' })
-    ).toBeFocused();
-    page.getByRole('button', { name: 'Launch modal' }).press('Enter');
+    await expect(button).toBeFocused();
+    button.press('Enter');
 
     // The first interactive item in the modal should be focused once the modal is open
     await expect(
@@ -67,9 +67,8 @@ test.describe('Modal @avt', () => {
 
     // The modal should no longer be open/visisble
     await expect(page.getByRole('dialog')).not.toBeVisible();
-    // Focus moves to the body
-    // TODO: on close of the modal, focus should return to the element that opened the modal, see https://github.com/carbon-design-system/carbon/issues/13680
-    await expect(page.locator('body')).toBeFocused();
+    // Focus moves to the button that opened the Modal
+    await expect(button).toBeFocused();
   });
 
   test('danger modal - keyboard nav', async ({ page }) => {

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -1406,6 +1406,26 @@ Map {
       "isFullWidth": Object {
         "type": "bool",
       },
+      "launcherButtonRef": Object {
+        "args": Array [
+          Array [
+            Object {
+              "type": "func",
+            },
+            Object {
+              "args": Array [
+                Object {
+                  "current": Object {
+                    "type": "any",
+                  },
+                },
+              ],
+              "type": "shape",
+            },
+          ],
+        ],
+        "type": "oneOfType",
+      },
       "onClose": Object {
         "type": "func",
       },
@@ -4710,6 +4730,26 @@ Map {
       "isFullWidth": Object {
         "type": "bool",
       },
+      "launcherButtonRef": Object {
+        "args": Array [
+          Array [
+            Object {
+              "type": "func",
+            },
+            Object {
+              "args": Array [
+                Object {
+                  "current": Object {
+                    "type": "any",
+                  },
+                },
+              ],
+              "type": "shape",
+            },
+          ],
+        ],
+        "type": "oneOfType",
+      },
       "modalAriaLabel": Object {
         "type": "string",
       },

packages/react/src/components/ComposedModal/ComposedModal.stories.js

@@ -136,7 +136,7 @@ export const PassiveModal = () => {
 };
 
 export const WithStateManager = () => {
-  const closeButton = useRef();
+  const button = useRef();
 
   /**
    * Simple state manager for modals.
@@ -161,7 +161,7 @@ export const WithStateManager = () => {
   return (
     <ModalStateManager
       renderLauncher={({ setOpen }) => (
-        <Button ref={closeButton} onClick={() => setOpen(true)}>
+        <Button ref={button} onClick={() => setOpen(true)}>
           Launch composed modal
         </Button>
       )}>
@@ -170,10 +170,8 @@ export const WithStateManager = () => {
           open={open}
           onClose={() => {
             setOpen(false);
-            setTimeout(() => {
-              closeButton.current.focus();
-            });
-          }}>
+          }}
+          launcherButtonRef={button}>
           <ModalHeader label="Account resources" title="Add a custom domain" />
           <ModalBody>
             <p style={{ marginBottom: '1rem' }}>

packages/react/src/components/ComposedModal/ComposedModal.tsx

@@ -7,6 +7,7 @@ import React, {
   type HTMLAttributes,
   type ReactNode,
   type ReactElement,
+  type RefObject,
 } from 'react';
 import { isElement } from 'react-is';
 import PropTypes from 'prop-types';
@@ -147,6 +148,11 @@ export interface ComposedModalProps extends HTMLAttributes<HTMLDivElement> {
    */
   isFullWidth?: boolean;
 
+  /**
+   * Provide a ref to return focus to once the modal is closed.
+   */
+  launcherButtonRef?: RefObject<HTMLButtonElement>;
+
   /**
    * Specify an optional handler for closing modal.
    * Returning `false` here prevents closing modal.
@@ -194,6 +200,7 @@ const ComposedModal = React.forwardRef<HTMLDivElement, ComposedModalProps>(
       selectorPrimaryFocus,
       selectorsFloatingMenus,
       size,
+      launcherButtonRef,
       ...rest
     },
     ref
@@ -304,6 +311,14 @@ const ComposedModal = React.forwardRef<HTMLDivElement, ComposedModalProps>(
       }
     });
 
+    useEffect(() => {
+      if (!open && launcherButtonRef) {
+        setTimeout(() => {
+          launcherButtonRef?.current?.focus();
+        });
+      }
+    }, [open, launcherButtonRef]);
+
     useEffect(() => {
       const initialFocus = (focusContainerElement) => {
         const containerElement = focusContainerElement || innerModal.current;
@@ -407,6 +422,17 @@ ComposedModal.propTypes = {
    */
   isFullWidth: PropTypes.bool,
 
+  /**
+   * Provide a ref to return focus to once the modal is closed.
+   */
+  // @ts-expect-error: Invalid derived type
+  launcherButtonRef: PropTypes.oneOfType([
+    PropTypes.func,
+    PropTypes.shape({
+      current: PropTypes.any,
+    }),
+  ]),
+
   /**
    * Specify an optional handler for closing modal.
    * Returning `false` here prevents closing modal.

packages/react/src/components/Modal/Modal.js

@@ -49,6 +49,7 @@ const Modal = React.forwardRef(function Modal(
     closeButtonLabel,
     preventCloseOnClickOutside, // eslint-disable-line
     isFullWidth,
+    launcherButtonRef,
     ...rest
   },
   ref
@@ -174,6 +175,14 @@ const Modal = React.forwardRef(function Modal(
     toggleClass(document.body, `${prefix}--body--with-modal-open`, open);
   }, [open, prefix]);
 
+  useEffect(() => {
+    if (!open && launcherButtonRef) {
+      setTimeout(() => {
+        launcherButtonRef?.current?.focus();
+      });
+    }
+  }, [open, launcherButtonRef]);
+
   useEffect(() => {
     const initialFocus = (focusContainerElement) => {
       const containerElement = focusContainerElement || innerModal.current;
@@ -362,6 +371,16 @@ Modal.propTypes = {
    */
   isFullWidth: PropTypes.bool,
 
+  /**
+   * Provide a ref to return focus to once the modal is closed.
+   */
+  launcherButtonRef: PropTypes.oneOfType([
+    PropTypes.func,
+    PropTypes.shape({
+      current: PropTypes.any,
+    }),
+  ]),
+
   /**
    * Specify a label to be read by screen readers on the modal root node
    */

packages/react/src/components/Modal/Modal.stories.js

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, { useState } from 'react';
+import React, { useState, useRef } from 'react';
 import ReactDOM from 'react-dom';
 import { action } from '@storybook/addon-actions';
 import Modal from './Modal';
@@ -379,13 +379,19 @@ export const WithStateManager = () => {
       </>
     );
   };
+
+  const button = useRef();
+
   return (
     <ModalStateManager
       renderLauncher={({ setOpen }) => (
-        <Button onClick={() => setOpen(true)}>Launch modal</Button>
+        <Button ref={button} onClick={() => setOpen(true)}>
+          Launch modal
+        </Button>
       )}>
       {({ open, setOpen }) => (
         <Modal
+          launcherButtonRef={button}
           modalHeading="Add a custom domain"
           modalLabel="Account resources"
           primaryButtonText="Add"