Overlay: Add role="dialog", focus trap to Overlay

.changeset/polite-taxis-sin.md

@@ -0,0 +1,7 @@
+---
+'@primer/react': minor
+---
+
+Overlay: Add `role="dialog"` and `aria-modal="true"` to the `Overlay` component, and implement a focus trap.
+
+

packages/react/src/Autocomplete/AutocompleteOverlay.tsx

@@ -53,6 +53,7 @@ function AutocompleteOverlay({
 
   return showMenu ? (
     <Overlay
+      role="none"
       returnFocusRef={inputRef}
       preventFocusOnOpen={true}
       onClickOutside={closeOptionList}

packages/react/src/Overlay/Overlay.docs.json

@@ -112,6 +112,12 @@
       "defaultValue": "",
       "description": "If defined, Overlays will be rendered in the named portal. See also `Portal`."
     },
+    {
+      "name": "focusTrap",
+      "type": "string",
+      "defaultValue": "true",
+      "description": "Determines if the `Overlay` recieves a focus trap or not"
+    },
     {
       "name": "sx",
       "type": "SystemStyleObject"

packages/react/src/Overlay/Overlay.test.tsx

@@ -1,4 +1,5 @@
 import React, {useRef, useState} from 'react'
+import type {AriaRole} from '../utils/types'
 import {Overlay, Box, Text} from '..'
 import {ButtonDanger, Button} from '../deprecated'
 import {render, waitFor, fireEvent} from '@testing-library/react'
@@ -12,8 +13,9 @@ import {NestedOverlays, MemexNestedOverlays, MemexIssueOverlay, PositionedOverla
 type TestComponentSettings = {
   initialFocus?: 'button'
   callback?: () => void
+  role?: AriaRole
 }
-const TestComponent = ({initialFocus, callback}: TestComponentSettings) => {
+const TestComponent = ({initialFocus, callback, role}: TestComponentSettings) => {
   const [isOpen, setIsOpen] = useState(false)
   const buttonRef = useRef<HTMLButtonElement>(null)
   const confirmButtonRef = useRef<HTMLButtonElement>(null)
@@ -39,6 +41,7 @@ const TestComponent = ({initialFocus, callback}: TestComponentSettings) => {
               ignoreClickRefs={[buttonRef]}
               onEscape={closeOverlay}
               onClickOutside={closeOverlay}
+              role={role}
               width="small"
             >
               <Box display="flex" flexDirection="column" p={2}>
@@ -281,4 +284,32 @@ describe('Overlay', () => {
     // if stopPropagation worked, mockHandler would not have been called
     expect(mockHandler).toHaveBeenCalledTimes(0)
   })
+
+  it('should provide `role="dialog"` and `aria-modal="true"`, if role is not provided', async () => {
+    const user = userEvent.setup()
+    const {getByText, getByRole} = render(<TestComponent />)
+
+    await user.click(getByText('open overlay'))
+
+    expect(getByRole('dialog')).toBeInTheDocument()
+  })
+
+  it('should not provide `dialog` roles if role is already provided', async () => {
+    const user = userEvent.setup()
+    const {getByText, queryByRole} = render(<TestComponent role="none" />)
+
+    await user.click(getByText('open overlay'))
+
+    expect(queryByRole('dialog')).not.toBeInTheDocument()
+    expect(queryByRole('none')).toBeInTheDocument()
+  })
+
+  it('should add `aria-modal` if `role="dialog"` is present', async () => {
+    const user = userEvent.setup()
+    const {getByText, queryByRole} = render(<TestComponent role="dialog" />)
+
+    await user.click(getByText('open overlay'))
+
+    expect(queryByRole('dialog')).toHaveAttribute('aria-modal')
+  })
 })

packages/react/src/Overlay/Overlay.tsx

@@ -13,6 +13,7 @@ import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
 import type {AnchorSide} from '@primer/behaviors'
 import {useTheme} from '../ThemeProvider'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
+import {useFocusTrap} from '../hooks/useFocusTrap'
 
 type StyledOverlayProps = {
   width?: keyof typeof widthMap
@@ -109,6 +110,7 @@ type BaseOverlayProps = {
   portalContainerName?: string
   preventFocusOnOpen?: boolean
   role?: AriaRole
+  focusTrap?: boolean
   children?: React.ReactNode
 }
 
@@ -133,12 +135,13 @@ type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
  * @param bottom Optional. Vertical bottom position of the overlay, relative to its closest positioned ancestor (often its `Portal`).
  * @param position Optional. Sets how an element is positioned in a document. Defaults to `absolute` positioning.
  * @param portalContainerName Optional. The name of the portal container to render the Overlay into.
+ * @param focusTrap Optional. Determines if the `Overlay` recieves a focus trap or not. Defaults to `true`.
  */
 const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
   (
     {
       onClickOutside,
-      role = 'none',
+      role,
       initialFocusRef,
       returnFocusRef,
       ignoreClickRefs,
@@ -155,6 +158,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
       preventFocusOnOpen,
       position,
       style: styleFromProps = {},
+      focusTrap = true,
       ...rest
     },
     forwardedRef,
@@ -200,12 +204,20 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
     // To be backwards compatible with the old Overlay, we need to set the left prop if x-position is not specified
     const leftPosition: React.CSSProperties = left === undefined && right === undefined ? {left: 0} : {left}
 
+    const nonDialog = role && role !== 'dialog' ? true : false
+
+    useFocusTrap({
+      containerRef: overlayRef,
+      disabled: !focusTrap || nonDialog,
+    })
+
     return (
       <Portal containerName={portalContainerName}>
         <StyledOverlay
           height={height}
           width={width}
-          role={role}
+          role={role || 'dialog'}
+          aria-modal={nonDialog ? undefined : 'true'}
           {...rest}
           ref={overlayRef}
           style={