fix(odyssey-react): improve keyboard focus behavior for Modal component

Author: kamalgill-okta

packages/odyssey-react/package.json

@@ -20,6 +20,7 @@
   },
   "dependencies": {
     "@okta/odyssey-react-theme": "^0.11.0",
+    "@react-aria/focus": "3.5.0",
     "choices.js": "^9.0.1"
   },
   "devDependencies": {

packages/odyssey-react/src/components/Modal/Modal.test.tsx

@@ -11,7 +11,7 @@
  */
 
 import React from "react";
-import { render, fireEvent, screen } from "@testing-library/react";
+import { render, fireEvent, screen, waitFor } from "@testing-library/react";
 import { Modal } from ".";
 
 const role = "dialog";
@@ -130,6 +130,52 @@ describe("Modal", () => {
     expect(handleClose).toHaveBeenCalledTimes(1);
   });
 
+  it("should initially focus on modal's dismiss icon when open", () => {
+    const handleClose = jest.fn();
+    render(
+      <div>
+        <button data-testid="modal-trigger">Open Modal</button>
+        <Modal open={false} onClose={handleClose} closeMessage={message}>
+          <Modal.Header>{modalHeading}</Modal.Header>
+        </Modal>
+      </div>
+    );
+    const triggerBtn = screen.getByTestId("modal-trigger");
+    triggerBtn && triggerBtn.click();
+    const dismissIcon = screen.getByTitle(message).closest("button");
+    waitFor(
+      () => {
+        expect(document.activeElement).toBe(dismissIcon);
+      },
+      { timeout: 200 }
+    );
+  });
+
+  it("should restore focus to original focused element when modal is closed", () => {
+    const handleClose = jest.fn();
+    render(
+      <div>
+        <button data-testid="modal-trigger">Open Modal</button>
+        <Modal open={false} onClose={handleClose} closeMessage={message}>
+          <Modal.Header>{modalHeading}</Modal.Header>
+        </Modal>
+      </div>
+    );
+    const triggerBtn = screen.getByTestId("modal-trigger");
+    triggerBtn && triggerBtn.focus();
+    triggerBtn.click();
+    expect(document.activeElement).toBe(triggerBtn);
+    const dismissIcon = screen.getByTitle(message).closest("button");
+    waitFor(
+      () => {
+        expect(document.activeElement).toBe(dismissIcon);
+        dismissIcon?.click();
+        expect(document.activeElement).toBe(triggerBtn);
+      },
+      { timeout: 200 }
+    );
+  });
+
   a11yCheck(() =>
     render(
       <Modal

packages/odyssey-react/src/components/Modal/Modal.tsx

@@ -18,16 +18,26 @@ import type {
   ReactText,
 } from "react";
 import { createPortal } from "react-dom";
+import { FocusScope } from "@react-aria/focus";
 import { withTheme } from "@okta/odyssey-react-theme";
+
 import { Box } from "../Box";
 import { Button as CoreButton } from "../Button";
 import type { ButtonProps as CoreButtonProps } from "../Button";
 import { Heading } from "../Heading";
-import { forwardRefWithStatics, useOid, useCx, useOmit } from "../../utils";
+import {
+  forwardRefWithStatics,
+  useCx,
+  useFocus,
+  useOid,
+  useOmit,
+} from "../../utils";
 import { CloseIcon } from "../Icon";
 import { theme } from "./Modal.theme";
 import styles from "./Modal.module.scss";
 
+type OptionalHTMLElement = HTMLElement | null;
+
 export type ModalProps = {
   /**
    * The modal content, should use the Static components provided by Modal (Modal.Header, Modal.Body and Modal.Footer)
@@ -81,6 +91,7 @@ interface ModalContext {
   modalHeadingId: string;
   closeMessage: string;
 }
+
 const ModalContext = createContext({} as ModalContext);
 
 /**
@@ -111,9 +122,14 @@ export const Modal = withTheme(
     const oid = useOid(id);
     const modalDialog = useRef<HTMLDivElement>(null);
     const componentClass = useCx(styles.root, { [styles.openState]: open });
-
-    if (open && onOpen) {
-      onOpen();
+    const { restoreFocus, setFocus } = useFocus();
+    const lastFocusedElemRef = useRef<OptionalHTMLElement>(null);
+
+    if (open) {
+      lastFocusedElemRef.current = setFocus(modalDialog.current);
+      onOpen && onOpen();
+    } else {
+      lastFocusedElemRef.current && restoreFocus(lastFocusedElemRef.current);
     }
 
     return createPortal(
@@ -126,15 +142,17 @@ export const Modal = withTheme(
           hidden={!open}
         >
           <div className={styles.overlay} tabIndex={-1}>
-            <div
-              className={styles.dialog}
-              role="dialog"
-              aria-modal="true"
-              aria-labelledby={modalHeadingId}
-              ref={modalDialog}
-            >
-              {children}
-            </div>
+            <FocusScope contain>
+              <div
+                className={styles.dialog}
+                role="dialog"
+                aria-modal="true"
+                aria-labelledby={modalHeadingId}
+                ref={modalDialog}
+              >
+                {children}
+              </div>
+            </FocusScope>
           </div>
         </Box>
       </ModalContext.Provider>,

packages/odyssey-react/src/utils/focusHandling.ts

@@ -0,0 +1,75 @@
+/*!
+ * Copyright (c) 2021-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+type OptionalHTMLElement = HTMLElement | null;
+
+interface UseFocusHook {
+  restoreFocus: (current: OptionalHTMLElement) => void;
+  setFocus: (elem: OptionalHTMLElement) => OptionalHTMLElement;
+}
+
+const FOCUSABLE_ITEMS = [
+  "button",
+  "[href]",
+  "input",
+  "select",
+  "textarea",
+  '[tabindex]:not([tabindex="-1"])',
+];
+
+const FOCUSABLE_ITEMS_SELECTOR = FOCUSABLE_ITEMS.join(",");
+
+/**
+ * Set focus on first focusable element inside node tree
+ * @param {HTMLElement} elem - parent element that contains focusable child elements
+ * @returns {void}
+ */
+function setFocus(elem: OptionalHTMLElement): OptionalHTMLElement {
+  if (!elem) {
+    return null;
+  }
+  const focusableItems: NodeListOf<HTMLElement> = elem.querySelectorAll(
+    FOCUSABLE_ITEMS_SELECTOR
+  );
+  // Capture original focused element before setting focus inside modal dialog
+  const lastFocusedElement = document.activeElement;
+  if (focusableItems.length > 0) {
+    requestAnimationFrame(() => {
+      // Focus on first focusable element inside dialog
+      focusableItems[0].focus();
+    });
+  }
+  return lastFocusedElement as OptionalHTMLElement;
+}
+
+/**
+ * Restore focus to element with original focus prior to opening modal dialog
+ * @param {OptionalHTMLElement} elem
+ */
+function restoreFocus(elem: OptionalHTMLElement): void {
+  if (elem && document.contains(elem)) {
+    requestAnimationFrame(() => {
+      elem.focus();
+    });
+  }
+}
+
+/**
+ * Custom React Hook to provide set/restore focus helper methods
+ * @returns {UseFocusHook}
+ */
+export function useFocus(): UseFocusHook {
+  return {
+    restoreFocus,
+    setFocus,
+  };
+}

packages/odyssey-react/src/utils/index.ts

@@ -15,4 +15,5 @@ export { forwardRefWithStatics } from "./forwardRefWithStatics";
 export { oid, useOid } from "./oid";
 export { omit, useOmit } from "./omit";
 export { toCamelCase, toPascalCase } from "./convertCase";
+export { useFocus } from "./focusHandling";
 export type { PolymorphicForwardRef } from "./polymorphic";

packages/odyssey-storybook/src/components/Modal/Modal.stories.tsx

@@ -75,6 +75,7 @@ const Template: Story<ModalProps> = () => {
   );
 };
 
+// Default state (modal is initially open)
 export const Default = Template.bind({});
 Default.args = {
   open: true,
@@ -83,3 +84,13 @@ Default.argTypes = {
   onOpen: { action: "modal/onOpen" },
   onClose: { action: "modal/onClose" },
 };
+
+// Unopened state (modal is initially closed)
+export const Unopened = Template.bind({});
+Unopened.args = {
+  open: false,
+};
+Unopened.argTypes = {
+  onOpen: { action: "modal/onOpen" },
+  onClose: { action: "modal/onClose" },
+};