IconButton: introduce tooltips on icon buttons behind the unsafeDisableTooltip prop for an incremental rollout

.changeset/smart-chefs-fail.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+IconButton: introduce tooltip behavior behind the prop `_enableTooltip_`

packages/react/src/Button/IconButton.features.stories.tsx

@@ -1,4 +1,4 @@
-import {HeartIcon} from '@primer/octicons-react'
+import {HeartIcon, InboxIcon} from '@primer/octicons-react'
 import React from 'react'
 import {IconButton} from '.'
 
@@ -19,3 +19,16 @@ export const Small = () => <IconButton size="small" icon={HeartIcon} aria-label=
 export const Medium = () => <IconButton size="medium" icon={HeartIcon} aria-label="Favorite" />
 
 export const Large = () => <IconButton size="large" icon={HeartIcon} aria-label="Favorite" />
+
+export const TooltipEnabled = () => (
+  <IconButton _enableTooltip_={true} icon={HeartIcon} variant="primary" aria-label="Favorite" />
+)
+
+export const WithDescription = () => (
+  <IconButton
+    _enableTooltip_={true}
+    icon={InboxIcon}
+    aria-label="Notifications"
+    description="You have no unread notifications."
+  />
+)

packages/react/src/Button/IconButton.tsx

@@ -4,20 +4,62 @@ import {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/po
 import {ButtonBase} from './ButtonBase'
 import {defaultSxProp} from '../utils/defaultSxProp'
 import {generateCustomSxProp} from './Button'
+import {Tooltip} from '../drafts/Tooltip/Tooltip'
 
-const IconButton = forwardRef(({sx: sxProp = defaultSxProp, icon: Icon, ...props}, forwardedRef): JSX.Element => {
-  let sxStyles = sxProp
-  // grap the button props that have associated data attributes in the styles
-  const {size} = props
+const IconButton = forwardRef(
+  (
+    {
+      sx: sxProp = defaultSxProp,
+      icon: Icon,
+      'aria-label': ariaLabel,
+      description,
+      disabled,
+      // This is a temporary prop to incrementally introduce tooltips to the IconButton component.
+      _enableTooltip_ = false,
+      ...props
+    },
+    forwardedRef,
+  ): JSX.Element => {
+    let sxStyles = sxProp
+    // grap the button props that have associated data attributes in the styles
+    const {size} = props
 
-  if (sxProp !== null && Object.keys(sxProp).length > 0) {
-    sxStyles = generateCustomSxProp({size}, sxProp)
-  }
+    if (sxProp !== null && Object.keys(sxProp).length > 0) {
+      sxStyles = generateCustomSxProp({size}, sxProp)
+    }
 
-  return (
-    // @ts-expect-error StyledButton wants both Anchor and Button refs
-    <ButtonBase icon={Icon} data-component="IconButton" sx={sxStyles} type="button" {...props} ref={forwardedRef} />
-  )
-}) as PolymorphicForwardRefComponent<'button' | 'a', IconButtonProps>
+    const displayTooltip = _enableTooltip_ && !disabled && ariaLabel
+
+    if (displayTooltip) {
+      return (
+        <Tooltip ref={forwardedRef} text={description ?? ariaLabel} type={description ? undefined : 'label'}>
+          <ButtonBase
+            icon={Icon}
+            data-component="IconButton"
+            sx={sxStyles}
+            type="button"
+            // If description is provided, we will use the tooltip to describe the button, so we need to keep the aria-label to label the button.
+            aria-label={description ? ariaLabel : undefined}
+            {...props}
+          />
+        </Tooltip>
+      )
+    } else {
+      return (
+        <ButtonBase
+          icon={Icon}
+          data-component="IconButton"
+          sx={sxStyles}
+          type="button"
+          aria-label={ariaLabel}
+          disabled={disabled}
+          {...props}
+          // @ts-expect-error StyledButton wants both Anchor and Button refs
+          ref={forwardedRef}
+        />
+      )
+    }
+  },
+) as PolymorphicForwardRefComponent<'button' | 'a', IconButtonProps>
 
 export {IconButton}

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

@@ -1,4 +1,4 @@
-import {SearchIcon} from '@primer/octicons-react'
+import {SearchIcon, HeartIcon} from '@primer/octicons-react'
 import {render, screen, fireEvent} from '@testing-library/react'
 import {axe} from 'jest-axe'
 import React from 'react'
@@ -113,4 +113,20 @@ describe('Button', () => {
     const position = screen.getByText('content').compareDocumentPosition(screen.getByTestId('trailingVisual'))
     expect(position).toBe(Node.DOCUMENT_POSITION_FOLLOWING)
   })
+
+  it('should render tooltip on an icon button when the _enableTooltip_ prop is passed true', () => {
+    const {getByRole, getByText} = render(<IconButton icon={HeartIcon} aria-label="Heart" _enableTooltip_={true} />)
+    const triggerEL = getByRole('button')
+    const tooltipEl = getByText('Heart')
+    expect(triggerEL).toHaveAttribute('aria-labelledby', tooltipEl.id)
+  })
+  it('should render description type tooltip on an icon button when the description prop is provided and the _enableTooltip_ prop is passed true', () => {
+    const {getByRole, getByText} = render(
+      <IconButton icon={HeartIcon} aria-label="Heart" description="Love is all around" _enableTooltip_={true} />,
+    )
+    const triggerEL = getByRole('button')
+    expect(triggerEL).toHaveAttribute('aria-label', 'Heart')
+    const tooltipEl = getByText('Love is all around')
+    expect(triggerEL).toHaveAttribute('aria-describedby', tooltipEl.id)
+  })
 })

packages/react/src/Button/types.ts

@@ -76,6 +76,8 @@ export type ButtonProps = {
 
 export type IconButtonProps = ButtonA11yProps & {
   icon: React.ElementType
+  _enableTooltip_?: boolean
+  description?: string
 } & Omit<ButtonBaseProps, 'aria-label' | 'aria-labelledby'>
 
 // adopted from React.AnchorHTMLAttributes