Replace forwarded ref instances of useProvidedRefOrCreate with useMergedRefs

packages/react/src/ActionList/ActionList.test.tsx

@@ -2,6 +2,7 @@ import {describe, it, expect, vi} from 'vitest'
 import {render as HTMLRender} from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import {ActionList} from '.'
+import {createRef} from 'react'
 import {ActionListContainerContext} from './ActionListContainerContext'
 import {implementsClassName} from '../utils/testing'
 import classes from './ActionList.module.css'
@@ -606,3 +607,33 @@ describe('ActionList with role="tree"', () => {
     expect(container.querySelector('[data-component="ActionList"]')).not.toHaveAttribute('data-item-gap')
   })
 })
+
+describe('ActionList forwarded ref (primer_react_merged_forwarded_refs)', () => {
+  for (const enabled of [true, false]) {
+    describe(`with the flag ${enabled ? 'enabled' : 'disabled'}`, () => {
+      it('forwards a ref object to the element', () => {
+        const ref = createRef<HTMLUListElement>()
+        HTMLRender(
+          <FeatureFlags flags={{primer_react_merged_forwarded_refs: enabled}}>
+            <ActionList ref={ref}>
+              <ActionList.Item>Item</ActionList.Item>
+            </ActionList>
+          </FeatureFlags>,
+        )
+        expect(ref.current).toBeInstanceOf(HTMLElement)
+      })
+
+      it('calls a callback ref with the element', () => {
+        const refCallback = vi.fn()
+        HTMLRender(
+          <FeatureFlags flags={{primer_react_merged_forwarded_refs: enabled}}>
+            <ActionList ref={refCallback}>
+              <ActionList.Item>Item</ActionList.Item>
+            </ActionList>
+          </FeatureFlags>,
+        )
+        expect(refCallback.mock.calls.some(([el]) => el instanceof HTMLElement)).toBe(true)
+      })
+    })
+  }
+})

packages/react/src/ActionList/List.tsx

@@ -1,11 +1,11 @@
-import React, {type JSX} from 'react'
+import React, {useRef, type JSX} from 'react'
 import {fixedForwardRef} from '../utils/modern-polymorphic'
 import {ActionListContainerContext} from './ActionListContainerContext'
 import {useSlots} from '../hooks/useSlots'
 import {Heading} from './Heading'
 import {useId} from '../hooks/useId'
 import {ListContext, type ActionListProps} from './shared'
-import {useProvidedRefOrCreate} from '../hooks'
+import {useMergedRefs, useProvidedRefOrCreate} from '../hooks'
 import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
 import {clsx} from 'clsx'
 import classes from './ActionList.module.css'
@@ -43,7 +43,14 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
 
   const ariaLabelledBy = slots.heading ? (slots.heading.props.id ?? headingId) : listLabelledBy
   const listRole = role || listRoleFromContainer
-  const listRef = useProvidedRefOrCreate(forwardedRef as React.RefObject<HTMLUListElement>)
+  const mergedRefEnabled = useFeatureFlag('primer_react_merged_forwarded_refs')
+  const listRef = useRef<HTMLElement>(null)
+  const mergedRef = useMergedRefs(listRef, forwardedRef)
+  // Feature-flag scaffolding for `primer_react_merged_forwarded_refs`.
+  // At graduation: remove the three declarations below, and replace all instances of `readRef` with `listRef` and `appliedRef` with `mergedRef`.
+  const providedOrCreatedRef = useProvidedRefOrCreate(forwardedRef as React.RefObject<HTMLElement>)
+  const readRef = mergedRefEnabled ? listRef : providedOrCreatedRef
+  const appliedRef = mergedRefEnabled ? mergedRef : providedOrCreatedRef
   const itemGapEnabled = useFeatureFlag('primer_react_action_list_item_gap') && container === 'NavList'
 
   let enableFocusZone = false
@@ -52,7 +59,7 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
 
   useFocusZone({
     disabled: !enableFocusZone,
-    containerRef: listRef,
+    containerRef: readRef,
     bindKeys: FocusKeys.ArrowVertical | FocusKeys.HomeAndEnd | FocusKeys.PageUpDown,
     focusOutBehavior:
       listRole === 'menu' || container === 'SelectPanel' || container === 'FilteredActionList' ? 'wrap' : undefined,
@@ -84,7 +91,7 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
   // Two querySelector calls after render is trivially cheap compared to what the browser
   // was doing on every DOM mutation with `:has()`.
   useIsomorphicLayoutEffect(() => {
-    const list = listRef.current
+    const list = readRef.current
     if (!list) return
     const hasMixed =
       list.querySelector('[data-has-description="true"]') !== null &&
@@ -105,7 +112,7 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
         className={clsx(classes.ActionList, className)}
         role={listRole}
         aria-labelledby={ariaLabelledBy}
-        ref={listRef}
+        ref={appliedRef}
         data-component="ActionList"
         data-dividers={showDividers}
         data-variant={variant}

packages/react/src/AnchoredOverlay/AnchoredOverlay.test.tsx

@@ -765,3 +765,49 @@ describe('AnchoredOverlay anchor element replacement', () => {
     expect(newAnchor.style.getPropertyValue('anchor-name')).toBe(anchorName)
   })
 })
+
+describe('AnchoredOverlay overlay forwarded ref (primer_react_merged_forwarded_refs)', () => {
+  for (const enabled of [true, false]) {
+    describe(`with the flag ${enabled ? 'enabled' : 'disabled'}`, () => {
+      it('forwards a ref object to the overlay', () => {
+        const ref = createRef<HTMLDivElement>()
+        render(
+          <FeatureFlags flags={{primer_react_merged_forwarded_refs: enabled}}>
+            <BaseStyles>
+              <AnchoredOverlay
+                open
+                onClose={() => {}}
+                onOpen={() => {}}
+                renderAnchor={props => <Button {...props}>Anchor</Button>}
+                overlayProps={{ref}}
+              >
+                <button type="button">Child</button>
+              </AnchoredOverlay>
+            </BaseStyles>
+          </FeatureFlags>,
+        )
+        expect(ref.current).toBeInstanceOf(HTMLDivElement)
+      })
+
+      it('calls a callback ref with the overlay', () => {
+        const refCallback = vi.fn()
+        render(
+          <FeatureFlags flags={{primer_react_merged_forwarded_refs: enabled}}>
+            <BaseStyles>
+              <AnchoredOverlay
+                open
+                onClose={() => {}}
+                onOpen={() => {}}
+                renderAnchor={props => <Button {...props}>Anchor</Button>}
+                overlayProps={{ref: refCallback}}
+              >
+                <button type="button">Child</button>
+              </AnchoredOverlay>
+            </BaseStyles>
+          </FeatureFlags>,
+        )
+        expect(refCallback.mock.calls.some(([el]) => el instanceof HTMLDivElement)).toBe(true)
+      })
+    })
+  }
+})

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx

@@ -6,7 +6,7 @@ import type {FocusTrapHookSettings} from '../hooks/useFocusTrap'
 import {useFocusTrap} from '../hooks/useFocusTrap'
 import type {FocusZoneHookSettings} from '../hooks/useFocusZone'
 import {useFocusZone} from '../hooks/useFocusZone'
-import {useAnchoredPosition, useProvidedRefOrCreate, useRenderForcingRef} from '../hooks'
+import {useAnchoredPosition, useMergedRefs, useProvidedRefOrCreate, useRenderForcingRef} from '../hooks'
 import {useId} from '../hooks/useId'
 import type {AnchorPosition, PositionSettings} from '@primer/behaviors'
 import {type ResponsiveValue} from '../hooks/useResponsiveValue'
@@ -207,7 +207,9 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
     setAnchorElement(anchorRef.current)
   }
   const [overlayRef, updateOverlayRef] = useRenderForcingRef<HTMLDivElement>()
+  const mergedRefEnabled = useFeatureFlag('primer_react_merged_forwarded_refs')
   const [overlayElement, setOverlayElement] = useState<HTMLDivElement | null>(null)
+  const mergedOverlayRef = useMergedRefs(updateOverlayRef, useMergedRefs(overlayProps?.ref, setOverlayElement))
   const anchorId = useId(externalAnchorId)
 
   const onClickOutside = useCallback(() => onClose?.('click-outside'), [onClose])
@@ -436,13 +438,17 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
           {...(shouldRenderAsPopover ? {popover: 'manual'} : {})}
           {...restOverlayProps}
           {...(shouldRenderAsPopover ? {id: popoverId} : {})}
-          ref={node => {
-            if (overlayProps?.ref) {
-              assignRef(overlayProps.ref, node)
-            }
-            updateOverlayRef(node)
-            setOverlayElement(node)
-          }}
+          ref={
+            mergedRefEnabled
+              ? mergedOverlayRef
+              : node => {
+                  setOverlayElement(node)
+                  if (overlayProps?.ref) {
+                    assignRef(overlayProps.ref, node)
+                  }
+                  updateOverlayRef(node)
+                }
+          }
           data-anchor-position={cssAnchorPositioning}
           data-side={cssAnchorPositioning ? side : position?.anchorSide}
         >

packages/react/src/Autocomplete/AutocompleteInput.tsx

@@ -56,13 +56,19 @@ const AutocompleteInput = React.forwardRef(
 
     const handleInputBlur: FocusEventHandler<HTMLInputElement> = useCallback(
       event => {
-        onBlur && onBlur(event)
+        onBlur?.(event)
 
-        // HACK: wait a tick and check the focused element before hiding the autocomplete menu
-        // this prevents the menu from hiding when the user is clicking an option in the Autoselect.Menu,
-        // but still hides the menu when the user blurs the input by tabbing out or clicking somewhere else on the page
+        // HACK: wait a tick before hiding the menu so click interactions can complete.
+        // Use the blur event's relatedTarget to determine whether focus is moving into the
+        // autocomplete menu; if not, hide the menu when focus leaves the input.
         safeSetTimeout(() => {
-          if (document.activeElement !== inputRef.current) {
+          const nextFocusedElement = event.relatedTarget as Node | null
+          const menuElement = document.getElementById(`${id}-listbox`)
+
+          if (
+            !nextFocusedElement ||
+            (nextFocusedElement !== menuElement && !menuElement?.contains(nextFocusedElement))
+          ) {
             setShowMenu(false)
 
             // Reset the input's value to the text the user actually typed rather than leaving the
@@ -75,11 +81,11 @@ const AutocompleteInput = React.forwardRef(
           }
         }, 0)
       },
-      [onBlur, setShowMenu, inputRef, safeSetTimeout, autocompleteSuggestion, inputValue],
+      [onBlur, setShowMenu, inputRef, safeSetTimeout, autocompleteSuggestion, inputValue, id],
     )
 
     const handleInputChange: ChangeEventHandler<HTMLInputElement> = event => {
-      onChange && onChange(event)
+      onChange?.(event)
       setInputValue(event.currentTarget.value)
       if (!showMenu) {
         setShowMenu(true)
@@ -88,7 +94,7 @@ const AutocompleteInput = React.forwardRef(
 
     const handleInputKeyDown: KeyboardEventHandler<HTMLInputElement> = useCallback(
       event => {
-        onKeyDown && onKeyDown(event)
+        onKeyDown?.(event)
 
         if (event.key === 'Backspace') {
           setHighlightRemainingText(false)
@@ -107,7 +113,7 @@ const AutocompleteInput = React.forwardRef(
 
     const handleInputKeyUp: KeyboardEventHandler<HTMLInputElement> = useCallback(
       event => {
-        onKeyUp && onKeyUp(event)
+        onKeyUp?.(event)
 
         if (event.key === 'Backspace') {
           setHighlightRemainingText(true)
@@ -118,12 +124,11 @@ const AutocompleteInput = React.forwardRef(
 
     const onInputKeyPress: KeyboardEventHandler<HTMLInputElement> = useCallback(
       event => {
-        onKeyPress && onKeyPress(event)
+        onKeyPress?.(event)
         if (showMenu && event.key === 'Enter' && activeDescendantRef.current) {
           event.preventDefault()
           event.nativeEvent.stopImmediatePropagation()
 
-          // Forward Enter key press to active descendant so that item gets activated
           const activeDescendantEvent = new KeyboardEvent(event.type, event.nativeEvent)
           activeDescendantRef.current.dispatchEvent(activeDescendantEvent)
         }
@@ -136,17 +141,10 @@ const AutocompleteInput = React.forwardRef(
         return
       }
 
-      // resets input value to being empty after a selection has been made
       if (!autocompleteSuggestion) {
         inputRef.current.value = inputValue
       }
 
-      // TODO: fix bug where this function prevents `onChange` from being triggered if the highlighted item text
-      //       is the same as what I'm typing
-      //       e.g.: typing 'tw' highlights 'two', but when I 'two', the text input change does not get triggered
-      // Only apply the inline autocomplete suggestion while the input is focused. Without this guard,
-      // the suggestion can be re-applied to the DOM after the input is blurred, which would restore
-      // the full suggestion the user was editing away from. See https://github.com/primer/react/issues/4275
       const isInputFocused = document.activeElement === inputRef.current
 
       if (
@@ -163,7 +161,6 @@ const AutocompleteInput = React.forwardRef(
         }
       }
 
-      // calling this useEffect when `highlightRemainingText` changes breaks backspace functionality
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [autocompleteSuggestion, inputValue, inputRef, isMenuDirectlyActivated])
 

packages/react/src/ButtonGroup/ButtonGroup.test.tsx

@@ -1,6 +1,8 @@
 import {render, screen} from '@testing-library/react'
 import ButtonGroup from './ButtonGroup'
-import {describe, expect, it} from 'vitest'
+import {createRef} from 'react'
+import {FeatureFlags} from '../FeatureFlags'
+import {describe, expect, it, vi} from 'vitest'
 import {implementsClassName} from '../utils/testing'
 import classes from './ButtonGroup.module.css'
 
@@ -22,3 +24,33 @@ describe('ButtonGroup', () => {
     expect(screen.getByRole('toolbar')).toBeInTheDocument()
   })
 })
+
+describe('ButtonGroup forwarded ref (primer_react_merged_forwarded_refs)', () => {
+  for (const enabled of [true, false]) {
+    describe(`with the flag ${enabled ? 'enabled' : 'disabled'}`, () => {
+      it('forwards a ref object to the element', () => {
+        const ref = createRef<HTMLDivElement>()
+        render(
+          <FeatureFlags flags={{primer_react_merged_forwarded_refs: enabled}}>
+            <ButtonGroup ref={ref}>
+              <button type="button">A</button>
+            </ButtonGroup>
+          </FeatureFlags>,
+        )
+        expect(ref.current).toBeInstanceOf(HTMLDivElement)
+      })
+
+      it('calls a callback ref with the element', () => {
+        const refCallback = vi.fn()
+        render(
+          <FeatureFlags flags={{primer_react_merged_forwarded_refs: enabled}}>
+            <ButtonGroup ref={refCallback}>
+              <button type="button">A</button>
+            </ButtonGroup>
+          </FeatureFlags>,
+        )
+        expect(refCallback.mock.calls.some(([el]) => el instanceof HTMLDivElement)).toBe(true)
+      })
+    })
+  }
+})

packages/react/src/ButtonGroup/ButtonGroup.tsx

@@ -1,8 +1,9 @@
-import React, {type PropsWithChildren} from 'react'
+import React, {useRef, type PropsWithChildren} from 'react'
 import classes from './ButtonGroup.module.css'
 import {clsx} from 'clsx'
 import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
-import {useProvidedRefOrCreate} from '../hooks'
+import {useMergedRefs, useProvidedRefOrCreate} from '../hooks'
+import {useFeatureFlag} from '../FeatureFlags'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 
 export type ButtonGroupProps = PropsWithChildren<{
@@ -16,24 +17,31 @@ const ButtonGroup = React.forwardRef(function ButtonGroup(
   {as: BaseComponent = 'div', children, className, role, ...rest},
   forwardRef,
 ) {
+  const mergedRefEnabled = useFeatureFlag('primer_react_merged_forwarded_refs')
+  const buttonRef = useRef<HTMLDivElement>(null)
+  const mergedRef = useMergedRefs(buttonRef, forwardRef)
+  // Feature-flag scaffolding for `primer_react_merged_forwarded_refs`.
+  // At graduation: remove the three declarations below, and replace all instances of `readRef` with `buttonRef` and `appliedRef` with `mergedRef`.
+  const providedOrCreatedRef = useProvidedRefOrCreate(forwardRef as React.RefObject<HTMLDivElement | null>)
+  const readRef = mergedRefEnabled ? buttonRef : providedOrCreatedRef
+  const appliedRef = mergedRefEnabled ? mergedRef : providedOrCreatedRef
   const buttons = React.Children.map(children, (child, index) => (
     <div key={index} className={classes.Item}>
       {child}
     </div>
   ))
-  const buttonRef = useProvidedRefOrCreate(forwardRef as React.RefObject<HTMLDivElement | null>)
 
   useFocusZone({
-    containerRef: buttonRef,
+    containerRef: readRef,
     disabled: role !== 'toolbar',
     bindKeys: FocusKeys.ArrowHorizontal,
     focusOutBehavior: 'wrap',
   })
 
   return (
     <BaseComponent
-      //@ts-expect-error it needs a non nullable ref
-      ref={buttonRef}
+      // @ts-expect-error it needs a non nullable ref
+      ref={appliedRef}
       className={clsx(className, classes.ButtonGroup)}
       role={role}
       {...rest}