feat: Implement modal tab behavior according to current APG recommendation

Author: jquense

src/Modal.tsx

@@ -26,6 +26,7 @@ import {
   type TransitionHandler,
 } from './ImperativeTransition.js';
 import { isEscKey } from './utils.js';
+import { getTabbableElementsOrSelf } from './tabbable.js';
 
 let manager: ModalManager;
 
@@ -304,7 +305,7 @@ const Modal: React.ForwardRefExoticComponent<
     const lastFocusRef = useRef<HTMLElement | null>(null);
 
     const focusTrap = useFocusTrap({
-      container: modal.dialog,
+      getContainer: () => modal.dialog,
       disabled: () => !enforceFocus || !modal.isTopModal(),
     });
 
@@ -349,7 +350,8 @@ const Modal: React.ForwardRefExoticComponent<
           !contains(modal.dialog, currentActiveElement)
         ) {
           lastFocusRef.current = currentActiveElement;
-          modal.dialog.focus();
+          const tabbables = getTabbableElementsOrSelf(modal.dialog);
+          tabbables[0]?.focus();
         }
       }
     });

src/tabbable.ts

@@ -64,6 +64,10 @@ const FOCUSABLE_SELECTOR = [
   '[contenteditable]:not([contenteditable="false"])',
 ].join(',');
 
+const isFocusable = (element: HTMLElement | SVGElement) =>
+  element.matches(FOCUSABLE_SELECTOR) &&
+  isFocusableElementMatchingSelector(element);
+
 export function getTabbableElements(
   container: Element | Document,
   startAt?: HTMLElement,
@@ -82,3 +86,12 @@ export function getTabbableElements(
 
   return items.filter(isTabbableElementMatchingSelector);
 }
+
+export function getTabbableElementsOrSelf(container: HTMLElement | SVGElement) {
+  const tabbables = getTabbableElements(container);
+  return tabbables.length
+    ? tabbables
+    : isFocusable(container)
+      ? [container]
+      : [];
+}

src/useFocusTrap.tsx

@@ -3,14 +3,14 @@ import { useRef } from 'react';
 import useWindow from './useWindow.js';
 import useMounted from '@restart/hooks/useMounted';
 import useEventCallback from '@restart/hooks/useEventCallback';
-import { getTabbableElements } from './tabbable.js';
+import { getTabbableElements, getTabbableElementsOrSelf } from './tabbable.js';
 import activeElement from 'dom-helpers/activeElement';
 
 export function useFocusTrap({
-  container,
+  getContainer,
   disabled,
 }: {
-  container: HTMLElement;
+  getContainer: () => HTMLElement | null;
   disabled?: () => boolean;
 }) {
   const ownerWindow = useWindow();
@@ -19,50 +19,29 @@ export function useFocusTrap({
   const listenersRef = useRef(new Set<(...args: any[]) => void>());
 
   const handleKeydown = useEventCallback((event: KeyboardEvent) => {
+    const container = getContainer();
+
     if (event.key !== 'Tab' || !container) {
       return;
     }
 
-    const tabbables = getTabbableElements(container);
-    const currentActiveElement = activeElement(ownerWindow?.document);
-
-    const isTabbingBackwards =
-      currentActiveElement === tabbables[0] && event.shiftKey;
+    const tabbables = getTabbableElementsOrSelf(container);
 
-    const isTabbingForward =
-      currentActiveElement === tabbables[tabbables.length - 1];
+    const firstTabbable = tabbables[0];
+    const lastTabbable = tabbables[tabbables.length - 1];
 
-    if (!isTabbingBackwards && !isTabbingForward) {
+    if (event.shiftKey && event.target === tabbables[0]) {
+      lastTabbable?.focus();
+      event.preventDefault();
       return;
     }
 
-    /**
-     * We want focus to move from the focus trapped container out of the document like
-     * it would if you tabbed from the end or start of the page.
-     *
-     * Generally this Just Works for tabbing forward out of the modal, as modals are often
-     * the last element in the document. In cases where it isn't or if you tabbed backwards
-     * we need to allow focus to move out of the document.
-     *
-     * This is done by way of a little "trick". `tab` events happen before focus moves so
-     * you can shift the focus to a new element and the tab will then move focus forward or backwards
-     * depending on the direction. We take advantage of this by moving focus to the first or last tabbable element
-     * in the document.
-     */
-    const bodyTabbables = getTabbableElements(
-      ownerWindow?.document ?? document!,
-    );
-
-    if (isTabbingBackwards) {
-      if (bodyTabbables[0] !== currentActiveElement) {
-        bodyTabbables[0]?.focus();
-      }
-    } else if (isTabbingForward) {
-      const lastTabbable = bodyTabbables[bodyTabbables.length - 1];
-
-      if (lastTabbable !== currentActiveElement) {
-        lastTabbable?.focus();
-      }
+    if (
+      (!event.shiftKey && event.target === lastTabbable) ||
+      !container.contains(event.target as Element)
+    ) {
+      firstTabbable?.focus();
+      event.preventDefault();
     }
   });
 
@@ -71,16 +50,17 @@ export function useFocusTrap({
       return;
     }
 
+    const container = getContainer();
     const currentActiveElement = activeElement(ownerWindow?.document);
 
     if (
       container &&
       currentActiveElement &&
       !container.contains(currentActiveElement)
     ) {
-      const tabbables = getTabbableElements(container);
+      const tabbables = getTabbableElementsOrSelf(container);
 
-      (tabbables[0] ?? container).focus();
+      tabbables[0]?.focus();
     }
   });
 
@@ -92,22 +72,26 @@ export function useFocusTrap({
     }
 
     ownerWindow.addEventListener('focus', handleFocus, { capture: true });
+    ownerWindow.addEventListener('blur', handleBlur);
     document.addEventListener('keydown', handleKeydown);
 
-    listenersRef.current.add(() =>
-      ownerWindow.removeEventListener('focus', handleFocus, { capture: true }),
-    );
-    listenersRef.current.add(() =>
-      document.removeEventListener('keydown', handleKeydown),
-    );
+    listenersRef.current.add(() => {
+      ownerWindow.removeEventListener('focus', handleFocus, { capture: true });
+      ownerWindow.removeEventListener('blur', handleBlur);
+      document.removeEventListener('keydown', handleKeydown);
+    });
 
     function handleFocus(event: FocusEvent) {
       console.log('handleFocus', event.target);
       // the timeout is necessary b/c this will run before the new modal is mounted
       // and so steals focus from it
       setTimeout(() => handleEnforceFocus(event));
     }
-  }, [container, handleEnforceFocus]);
+
+    function handleBlur(event: FocusEvent) {
+      console.log('handleBlur', event.target);
+    }
+  }, [handleEnforceFocus]);
 
   const stop = useCallback(() => {
     listenersRef.current.forEach((listener) => listener());

test/ModalSpec.tsx

@@ -342,16 +342,18 @@ describe('<Modal>', () => {
       render(
         <Modal show className="modal">
           <div>
-            <input autoFocus />
+            <input type="text" autoFocus />
           </div>
         </Modal>,
         { container: focusableContainer },
       );
 
       focusableContainer.focus();
 
+      const input = document.getElementsByTagName('input')[0];
+
       await waitFor(() => {
-        expect(document.activeElement!.classList.contains('modal')).toBe(true);
+        expect(document.activeElement).toEqual(input);
       });
     });
   });

www/docs/Modal.mdx

@@ -43,12 +43,18 @@ function Example() {
         <div>
           <h4 id="modal-1-label">Alert!</h4>
           <p>Some important content!</p>
-          <Button
-            onClick={() => setShow(false)}
-            className="float-right"
-          >
-            Close
-          </Button>
+
+          <div className="flex justify-end gap-4">
+            <Button onClick={() => setShow(false)}>
+              Close
+            </Button>
+            <Button
+              onClick={() => setShow(false)}
+              autoFocus
+            >
+              OK
+            </Button>
+          </div>
         </div>
       </Modal>
     </div>

www/src/LiveCodeblock.tsx

@@ -19,6 +19,7 @@ import Tooltip from './Tooltip';
 import Transition from 'react-transition-group/Transition';
 import scrollParent from 'dom-helpers/scrollParent';
 import '../src/css/transitions.css';
+import styled from '@emotion/styled';
 
 // @ts-ignore
 import styles from './LiveCodeBlock.module.css';
@@ -41,6 +42,7 @@ const LocalImports = {
   '../src/Dropdown': Dropdown,
   '../src/Tooltip': Tooltip,
   '../src/css/transitions.css': '',
+  '@emotion/styled': styled,
 };
 
 export interface Props