Replace useRefObjectAsForwardedRef with useMergedRefs internally

.changeset/combined-refs-hook.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Update internal implementations of combined refs to improve performance and add support for React 19 callback refs

.changeset/early-ravens-visit.md

@@ -0,0 +1,7 @@
+---
+"@primer/react": minor
+---
+
+- New: Exposes new `useMergedRefs` hook that can merge two refs into a single combined ref
+- Deprecates `useRefObjectAsForwardedRef`; see doc comment for migration instructions
+- Deprecates `useProvidedRefOrCreate`; see doc comment for migration instructions

packages/react/src/Autocomplete/Autocomplete.test.tsx

@@ -150,6 +150,7 @@ describe('Autocomplete', () => {
       const inputNode = getByLabelText(AUTOCOMPLETE_LABEL)
 
       expect(inputNode.getAttribute('aria-expanded')).not.toBe('true')
+      inputNode.focus()
       fireEvent.click(inputNode)
       fireEvent.keyDown(inputNode, {key: 'ArrowDown'})
 

packages/react/src/Autocomplete/AutocompleteInput.tsx

@@ -3,7 +3,7 @@ import React, {useCallback, useContext, useEffect, useState} from 'react'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import {AutocompleteContext, AutocompleteInputContext} from './AutocompleteContext'
 import TextInput from '../TextInput'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import type {ComponentProps} from '../utils/types'
 import useSafeTimeout from '../hooks/useSafeTimeout'
 
@@ -43,7 +43,7 @@ const AutocompleteInput = React.forwardRef(
     }
     const {activeDescendantRef, id, inputRef, setInputValue, setShowMenu, showMenu} = autocompleteContext
     const {autocompleteSuggestion = '', inputValue = '', isMenuDirectlyActivated} = inputContext
-    useRefObjectAsForwardedRef(forwardedRef, inputRef)
+    const mergedRef = useMergedRefs(forwardedRef, inputRef)
     const [highlightRemainingText, setHighlightRemainingText] = useState<boolean>(true)
     const {safeSetTimeout} = useSafeTimeout()
 
@@ -160,7 +160,7 @@ const AutocompleteInput = React.forwardRef(
         onKeyDown={handleInputKeyDown}
         onKeyPress={onInputKeyPress}
         onKeyUp={handleInputKeyUp}
-        ref={inputRef}
+        ref={mergedRef}
         aria-controls={`${id}-listbox`}
         aria-autocomplete="both"
         role="combobox"

packages/react/src/Autocomplete/AutocompleteOverlay.tsx

@@ -5,7 +5,7 @@ import type {OverlayProps} from '../Overlay'
 import Overlay from '../Overlay'
 import type {ComponentProps} from '../utils/types'
 import {AutocompleteContext} from './AutocompleteContext'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import VisuallyHidden from '../_VisuallyHidden'
 
 import classes from './AutocompleteOverlay.module.css'
@@ -57,7 +57,7 @@ function AutocompleteOverlay({
     [showMenu, selectedItemLength],
   )
 
-  useRefObjectAsForwardedRef(scrollContainerRef, floatingElementRef)
+  const mergedRef = useMergedRefs(scrollContainerRef, floatingElementRef)
 
   const closeOptionList = useCallback(() => {
     setShowMenu(false)
@@ -73,7 +73,7 @@ function AutocompleteOverlay({
       preventFocusOnOpen={true}
       onClickOutside={closeOptionList}
       onEscape={closeOptionList}
-      ref={floatingElementRef as React.RefObject<HTMLDivElement>}
+      ref={mergedRef}
       top={position?.top}
       left={position?.left}
       className={clsx(classes.Overlay, className)}

packages/react/src/Banner/Banner.tsx

@@ -3,7 +3,7 @@ import React, {forwardRef, useEffect} from 'react'
 import {AlertIcon, InfoIcon, StopIcon, CheckCircleIcon, XIcon} from '@primer/octicons-react'
 import {Button, IconButton, type ButtonProps} from '../Button'
 import {VisuallyHidden} from '../VisuallyHidden'
-import {useMergedRefs} from '../internal/hooks/useMergedRefs'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import {useId} from '../hooks/useId'
 import classes from './Banner.module.css'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'

packages/react/src/Button/ButtonBase.tsx

@@ -1,7 +1,7 @@
 import React, {forwardRef, type JSX} from 'react'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import type {ButtonProps} from './types'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import {VisuallyHidden} from '../VisuallyHidden'
 import Spinner from '../Spinner'
 import CounterLabel from '../CounterLabel'
@@ -51,7 +51,7 @@ const ButtonBase = forwardRef(({children, as: Component = 'button', ...props}, f
   } = props
 
   const innerRef = React.useRef<HTMLButtonElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, innerRef)
+  const combinedRefs = useMergedRefs(forwardedRef, innerRef)
 
   const uuid = useId(id)
   const loadingAnnouncementID = `${uuid}-loading-announcement`
@@ -87,8 +87,7 @@ const ButtonBase = forwardRef(({children, as: Component = 'button', ...props}, f
       <Component
         aria-disabled={loading ? true : undefined}
         {...rest}
-        // @ts-ignore temporary disable as we migrate to css modules, until we remove PolymorphicForwardRefComponent
-        ref={innerRef}
+        ref={combinedRefs}
         className={clsx(classes.ButtonBase, className)}
         data-block={block ? 'block' : null}
         data-inactive={inactive ? true : undefined}

packages/react/src/Details/Details.tsx

@@ -2,7 +2,7 @@ import React, {useEffect, type ComponentPropsWithoutRef, type ReactElement} from
 import {warning} from '../utils/warning'
 import {clsx} from 'clsx'
 import classes from './Details.module.css'
-import {useMergedRefs} from '../internal/hooks/useMergedRefs'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 
 const Root = React.forwardRef<HTMLDetailsElement, DetailsProps>(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

packages/react/src/Dialog/Dialog.tsx

@@ -7,7 +7,7 @@ import {XIcon} from '@primer/octicons-react'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {FocusKeys} from '@primer/behaviors'
 import Portal from '../Portal'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import {useId} from '../hooks/useId'
 import {ScrollableRegion} from '../ScrollableRegion'
 import type {ResponsiveValue} from '../hooks/useResponsiveValue'
@@ -289,7 +289,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
   })
 
   const dialogRef = useRef<HTMLDivElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, dialogRef)
+  const mergedRef = useMergedRefs(forwardedRef, dialogRef)
   const backdropRef = useRef<HTMLDivElement>(null)
 
   useFocusTrap({
@@ -362,7 +362,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
           }}
         >
           <div
-            ref={dialogRef}
+            ref={mergedRef}
             role={role}
             aria-labelledby={dialogLabelId}
             aria-describedby={dialogDescriptionId}

packages/react/src/Heading/Heading.tsx

@@ -1,6 +1,6 @@
 import {clsx} from 'clsx'
 import React, {forwardRef, useEffect} from 'react'
-import {useRefObjectAsForwardedRef} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import type {ComponentProps} from '../utils/types'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './Heading.module.css'
@@ -14,7 +14,7 @@ type StyledHeadingProps = {
 
 const Heading = forwardRef(({as: Component = 'h2', className, variant, ...props}, forwardedRef) => {
   const innerRef = React.useRef<HTMLHeadingElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, innerRef)
+  const mergedRef = useMergedRefs(forwardedRef, innerRef)
 
   if (__DEV__) {
     /**
@@ -32,7 +32,7 @@ const Heading = forwardRef(({as: Component = 'h2', className, variant, ...props}
     }, [innerRef])
   }
 
-  return <Component className={clsx(className, classes.Heading)} data-variant={variant} {...props} ref={innerRef} />
+  return <Component className={clsx(className, classes.Heading)} data-variant={variant} {...props} ref={mergedRef} />
 }) as PolymorphicForwardRefComponent<HeadingLevels, StyledHeadingProps>
 
 Heading.displayName = 'Heading'

packages/react/src/Link/Link.tsx

@@ -1,6 +1,6 @@
 import {clsx} from 'clsx'
 import React, {useEffect, type ForwardedRef, type ElementRef} from 'react'
-import {useRefObjectAsForwardedRef} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import classes from './Link.module.css'
 import type {ComponentProps} from '../utils/types'
 import {type PolymorphicProps, fixedForwardRef} from '../utils/modern-polymorphic'
@@ -20,7 +20,7 @@ export const UnwrappedLink = <As extends React.ElementType = 'a'>(
 ) => {
   const {as: Component = 'a', className, inline, hoverColor, ...restProps} = props
   const innerRef = React.useRef<ElementRef<As>>(null)
-  useRefObjectAsForwardedRef(ref, innerRef)
+  const mergedRef = useMergedRefs(ref, innerRef)
 
   if (__DEV__) {
     /**
@@ -53,8 +53,7 @@ export const UnwrappedLink = <As extends React.ElementType = 'a'>(
       data-inline={inline}
       data-hover-color={hoverColor}
       {...restProps}
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      ref={innerRef as any}
+      ref={mergedRef}
     />
   )
 }

packages/react/src/Overlay/Overlay.tsx

@@ -5,7 +5,7 @@ import type {AriaRole, Merge} from '../utils/types'
 import type {TouchOrMouseEvent} from '../hooks'
 import {useOverlay} from '../hooks'
 import Portal from '../Portal'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import type {AnchorSide} from '@primer/behaviors'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './Overlay.module.css'
@@ -192,7 +192,7 @@ const Overlay = React.forwardRef<HTMLDivElement, internalOverlayProps>(
   ): ReactElement<any> => {
     const cssAnchorPositioning = useFeatureFlag('primer_react_css_anchor_positioning')
     const overlayRef = useRef<HTMLDivElement>(null)
-    useRefObjectAsForwardedRef(forwardedRef, overlayRef)
+    const mergedRef = useMergedRefs(forwardedRef, overlayRef)
     const slideAnimationDistance = 8 // var(--base-size-8), hardcoded to do some math
     const slideAnimationEasing = 'cubic-bezier(0.33, 1, 0.68, 1)'
 
@@ -236,7 +236,7 @@ const Overlay = React.forwardRef<HTMLDivElement, internalOverlayProps>(
         role={role}
         width={width}
         data-reflow-container={!preventOverflow ? true : undefined}
-        ref={overlayRef}
+        ref={mergedRef}
         left={leftPosition}
         right={right}
         height={height}

packages/react/src/PageLayout/PageLayout.tsx

@@ -1,7 +1,7 @@
 import React, {memo, useRef} from 'react'
 import {clsx} from 'clsx'
 import {useId} from '../hooks/useId'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import type {ResponsiveValue} from '../hooks/useResponsiveValue'
 import {isResponsiveValue} from '../hooks/useResponsiveValue'
 import {useSlots} from '../hooks/useSlots'
@@ -838,7 +838,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
         currentWidth: controlledWidth,
       })
 
-    useRefObjectAsForwardedRef(forwardRef, paneRef)
+    const mergedRef = useMergedRefs(forwardRef, paneRef)
 
     const hasOverflow = useOverflow(paneRef)
 
@@ -887,7 +887,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
           position={positionProp}
         />
         <div
-          ref={paneRef}
+          ref={mergedRef}
           // Suppress hydration mismatch for --pane-width when localStorage
           // provides a width that differs from the server-rendered default.
           // Not needed when onResizeEnd is provided (localStorage isn't read).
@@ -1136,7 +1136,7 @@ const Sidebar = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLay
         constrainToViewport: true,
       })
 
-    useRefObjectAsForwardedRef(forwardRef, sidebarRef)
+    const mergedRef = useMergedRefs(forwardRef, sidebarRef)
 
     const hasOverflow = useOverflow(sidebarRef)
 
@@ -1192,7 +1192,7 @@ const Sidebar = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLay
           />
         )}
         <div
-          ref={sidebarRef}
+          ref={mergedRef}
           // Suppress hydration mismatch for --pane-width when localStorage
           // provides a width that differs from the server-rendered default.
           suppressHydrationWarning={resizable === true && !!widthStorageKey}

packages/react/src/TextInputWithTokens/TextInputWithTokens.tsx

@@ -3,7 +3,7 @@ import {isFocusable} from '@primer/behaviors/utils'
 import type {FocusEventHandler, KeyboardEventHandler, MouseEventHandler, RefObject} from 'react'
 import React, {useRef, useState} from 'react'
 import {isValidElementType} from 'react-is'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {useId} from '../hooks/useId'
 import Text from '../Text'
@@ -108,7 +108,7 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
   const ref = useRef<HTMLInputElement>(null)
 
   const selectedValuesDescriptionId = useId()
-  useRefObjectAsForwardedRef(forwardedRef, ref)
+  const mergedRef = useMergedRefs(forwardedRef, ref)
   const [selectedTokenIndex, setSelectedTokenIndex] = useState<number | undefined>()
   const [tokensAreTruncated, setTokensAreTruncated] = useState<boolean>(Boolean(visibleTokenCount))
   const selectedTokenTexts = tokens
@@ -310,7 +310,7 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
       >
         <div className={styles.InputWrapper}>
           <UnstyledTextInput
-            ref={ref}
+            ref={mergedRef}
             disabled={disabled}
             onFocus={handleInputFocus}
             onBlur={handleInputBlur}

packages/react/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -218,6 +218,7 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "useFormControlForwardedProps",
   "useId",
   "useIsomorphicLayoutEffect",
+  "useMergedRefs",
   "useOnEscapePress",
   "useOnOutsideClick",
   "useOpenAndCloseFocus",

packages/react/src/deprecated/DialogV1/Dialog.tsx

@@ -2,7 +2,7 @@ import React, {forwardRef, useRef, type HTMLAttributes} from 'react'
 import {IconButton} from '../../Button'
 import useDialog from '../../hooks/useDialog'
 import type {ComponentProps} from '../../utils/types'
-import {useRefObjectAsForwardedRef} from '../../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../../hooks/useMergedRefs'
 import {XIcon} from '@primer/octicons-react'
 import {clsx} from 'clsx'
 import classes from './Dialog.module.css'
@@ -48,7 +48,7 @@ const Dialog = forwardRef<HTMLDivElement, InternalDialogProps>(
   ) => {
     const overlayRef = useRef(null)
     const modalRef = useRef<HTMLDivElement>(null)
-    useRefObjectAsForwardedRef(forwardedRef, modalRef)
+    const mergedRef = useMergedRefs(forwardedRef, modalRef)
     const closeButtonRef = useRef(null)
 
     const onCloseClick = () => {
@@ -73,7 +73,7 @@ const Dialog = forwardRef<HTMLDivElement, InternalDialogProps>(
         <span className={classes.Overlay} ref={overlayRef} />
         <Component
           tabIndex={-1}
-          ref={modalRef}
+          ref={mergedRef}
           role="dialog"
           aria-modal="true"
           {...props}