Add support for initial focus ref to Dialog 2 (#4729)

* Add support for initial focus ref to Dialog 2

* add test and docs

* Create seven-phones-talk.md

.changeset/seven-phones-talk.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+Dialog2: Add support for "InitialFocusRef" that allows to specify an element that should receive focus when the dialog opens.

packages/react/src/Dialog/Dialog.docs.json

@@ -59,6 +59,11 @@
       "name": "returnFocusRef",
       "type": "React.RefObject<HTMLElement>",
       "describedby": "Return focus to this element when the Dialog closes, instead of the element that had focus immediately before the Dialog opened"
+    },
+    {
+      "name": "initialFocusRef",
+      "type": "React.RefObject<HTMLElement>",
+      "description": "Focus this element when the Dialog opens"
     }
   ],
   "subcomponents": []

packages/react/src/Dialog/Dialog.features.stories.tsx

@@ -1,5 +1,5 @@
 import React, {useState, useRef, useCallback} from 'react'
-import {Box, TextInput, Text, Button} from '..'
+import {Box, TextInput, Text, Button, ActionList} from '..'
 import type {DialogProps, DialogWidth, DialogHeight} from './Dialog'
 import {Dialog} from './Dialog'
 
@@ -304,3 +304,29 @@ export const ReturnFocusRef = () => {
     </React.Suspense>
   )
 }
+
+export const NewIssues = () => {
+  const [isOpen, setIsOpen] = useState(false)
+  const onDialogClose = useCallback(() => setIsOpen(false), [])
+  const initialFocusRef = useRef(null)
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Show dialog</Button>
+      {isOpen ? (
+        <Dialog
+          initialFocusRef={initialFocusRef}
+          onClose={onDialogClose}
+          title="New issue"
+          renderBody={() => (
+            <ActionList>
+              <ActionList.LinkItem ref={initialFocusRef} href="https://github.com">
+                Item 1
+              </ActionList.LinkItem>
+              <ActionList.LinkItem href="https://github.com">Link</ActionList.LinkItem>
+            </ActionList>
+          )}
+        ></Dialog>
+      ) : null}
+    </>
+  )
+}

packages/react/src/Dialog/Dialog.test.tsx

@@ -209,3 +209,21 @@ describe('Dialog', () => {
     expect(getByRole('button', {name: 'return focus to (button 2)'})).toHaveFocus()
   })
 })
+
+it('automatically focuses the element that is specified as initialFocusRef', () => {
+  const initialFocusRef = React.createRef<HTMLAnchorElement>()
+  const {getByRole} = render(
+    <Dialog
+      initialFocusRef={initialFocusRef}
+      onClose={() => {}}
+      title="New issue"
+      renderBody={() => (
+        <a ref={initialFocusRef} href="https://github.com">
+          Item 1
+        </a>
+      )}
+    ></Dialog>,
+  )
+
+  expect(getByRole('link')).toHaveFocus()
+})

packages/react/src/Dialog/Dialog.tsx

@@ -138,6 +138,11 @@ export interface DialogProps extends SxProp {
    * instead of the element that had focus immediately before the Dialog opened
    */
   returnFocusRef?: React.RefObject<HTMLElement>
+
+  /**
+   * The element to focus when the Dialog opens
+   */
+  initialFocusRef?: React.RefObject<HTMLElement>
 }
 
 /**
@@ -403,6 +408,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
     footerButtons = [],
     position = defaultPosition,
     returnFocusRef,
+    initialFocusRef,
     sx,
   } = props
   const dialogLabelId = useId()
@@ -429,7 +435,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
 
   useFocusTrap({
     containerRef: dialogRef,
-    initialFocusRef: autoFocusedFooterButtonRef,
+    initialFocusRef: initialFocusRef ?? autoFocusedFooterButtonRef,
     restoreFocusOnCleanUp: returnFocusRef?.current ? false : true,
     returnFocusRef,
   })

packages/react/src/__tests__/Dialog.test.tsx

@@ -4,7 +4,7 @@ import {render as HTMLRender, fireEvent} from '@testing-library/react'
 import axe from 'axe-core'
 import {behavesAsComponent, checkExports} from '../utils/testing'
 
-/* Dialog Version 2 */
+/* Dialog Version 1*/
 
 const comp = (
   <Dialog isOpen onDismiss={() => null} aria-labelledby="header">