Fixes issue with Tooltip description id overriding existing description ids (#6200)

Co-authored-by: Copilot <[email protected]>

Author: owenniblock

.changeset/two-aliens-wait.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Fixes issue with Tooltip description id overriding existing description ids

packages/react/src/TooltipV2/Tooltip.features.stories.tsx

@@ -1,4 +1,4 @@
-import {IconButton, Button, Box, Link, ActionMenu, ActionList} from '..'
+import {IconButton, Button, Box, Link, ActionMenu, ActionList, VisuallyHidden} from '..'
 import Octicon from '../Octicon'
 import {Tooltip} from './Tooltip'
 import {SearchIcon, BookIcon, CheckIcon, TriangleDownIcon, GitBranchIcon, InfoIcon} from '@primer/octicons-react'
@@ -35,6 +35,16 @@ export const DescriptionType = () => (
   </Box>
 )
 
+// As a supplementary description for a button
+export const DescriptionTypeWithExternalDescription = () => (
+  <Box sx={{p: 5}}>
+    <Tooltip text="Supplementary text" direction="n">
+      <Button aria-describedby="external-description">Save</Button>
+    </Tooltip>
+    <VisuallyHidden id="external-description">External description</VisuallyHidden>
+  </Box>
+)
+
 // As a supplementary description for an IconButton
 export const IconButtonWithDescription = () => (
   <Box sx={{p: 5}}>

packages/react/src/TooltipV2/Tooltip.tsx

@@ -247,7 +247,21 @@ export const Tooltip = React.forwardRef(
             React.cloneElement(child as React.ReactElement<TriggerPropsType>, {
               ref: triggerRef,
               // If it is a type description, we use tooltip to describe the trigger
-              'aria-describedby': type === 'description' ? tooltipId : child.props['aria-describedby'],
+              'aria-describedby': (() => {
+                // If tooltip is not a description type, keep the original aria-describedby
+                if (type !== 'description') {
+                  return child.props['aria-describedby']
+                }
+
+                // If tooltip is a description type, append our tooltipId
+                const existingDescribedBy = child.props['aria-describedby']
+                if (existingDescribedBy) {
+                  return `${existingDescribedBy} ${tooltipId}`
+                }
+
+                // If no existing aria-describedby, use our tooltipId
+                return tooltipId
+              })(),
               // If it is a label type, we use tooltip to label the trigger
               'aria-labelledby': type === 'label' ? tooltipId : child.props['aria-labelledby'],
               onBlur: (event: React.FocusEvent) => {

packages/react/src/TooltipV2/__tests__/Tooltip.test.tsx

@@ -13,6 +13,15 @@ const TooltipComponent = (props: Omit<TooltipProps, 'text'> & {text?: string}) =
   </Tooltip>
 )
 
+const TooltipComponentWithExistingDescription = (props: Omit<TooltipProps, 'text'> & {text?: string}) => (
+  <>
+    <span id="external-description">External description</span>
+    <Tooltip text="Tooltip text" {...props}>
+      <Button aria-describedby="external-description">Button Text</Button>
+    </Tooltip>
+  </>
+)
+
 function ExampleWithActionMenu(actionMenuTrigger: React.ReactElement): JSX.Element {
   return (
     <ThemeProvider theme={theme}>
@@ -162,4 +171,16 @@ describe('Tooltip', () => {
     )
     expect(getByRole('button', {name: 'Overridden label'})).toBeInTheDocument()
   })
+
+  it('should append tooltip id to existing aria-describedby value on the trigger element', () => {
+    const {getByRole, getByText} = HTMLRender(<TooltipComponentWithExistingDescription />)
+    const triggerEL = getByRole('button')
+    const tooltipEl = getByText('Tooltip text')
+    const externalDescription = getByText('External description')
+
+    // Check that aria-describedby contains both the external description ID and the tooltip ID
+    const describedBy = triggerEL.getAttribute('aria-describedby')
+    expect(describedBy).toContain(externalDescription.id)
+    expect(describedBy).toContain(tooltipEl.id)
+  })
 })