IconButton: Add keyshortcuts prop to allow labelling and describing…

… support for keyboard shortcut (through tooltips) (#4707)

* Add keyboard shortcut labelling and describing support for icon buttons (through tooltip)

* lint fix

* Create metal-cycles-appear.md

* test(vrt): update snapshots

* test(vrt): update snapshots

* disable animations in playwright tests

* test(vrt): update snapshots

* add docs

---------

Co-authored-by: broccolinisoup <broccolinisoup@users.noreply.github.com>

.changeset/metal-cycles-appear.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+IconButton: Add `keyshortcuts` prop to allow labelling and describing support for keyboard shortcut (through tooltips)

e2e/components/IconButton.test.ts

@@ -308,4 +308,67 @@ test.describe('IconButton', () => {
       })
     }
   })
+  test.describe('Keyshortcuts', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'components-iconbutton-features--keyshortcuts',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          await page.keyboard.press('Tab') // focus on icon button
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `IconButton.Keyshortcuts.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'components-iconbutton-features--keyshortcuts',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await page.keyboard.press('Tab') // focus on icon button
+          await expect(page).toHaveNoViolations()
+        })
+      })
+    }
+  })
+
+  test.describe('Keyshortcuts on Description', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'components-iconbutton-features--keyshortcuts-on-description',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          await page.keyboard.press('Tab') // focus on icon button
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `IconButton.Keyshortcuts on Description.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'components-iconbutton-features--keyshortcuts-on-description',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await page.keyboard.press('Tab') // focus on icon button
+          await expect(page).toHaveNoViolations()
+        })
+      })
+    }
+  })
 })

packages/react/src/Button/IconButton.docs.json

@@ -42,10 +42,17 @@
       "defaultValue": "",
       "description": "Use an aria label to describe the functionality of the button. Please refer to [our guidance on alt text](https://primer.style/guides/accessibility/alternative-text-for-images) for tips on writing good alternative text."
     },
+    {
+      "name": "keyshortcuts",
+      "type": "string",
+      "defaultValue": "",
+      "required": false,
+      "description": "Keyboard shortcuts that trigger the button. Keyboard shortcut will be appended to the accessible name or description (depending on the tooltip type) of the button with a comma (i.e. Bold, Command+B) and it will be displayed in the tooltip."
+    },
     {
       "name": "sx",
       "type": "SystemStyleObject"
     }
   ],
   "subcomponents": []
-}
+}

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

@@ -1,4 +1,4 @@
-import {HeartIcon, InboxIcon, ChevronDownIcon} from '@primer/octicons-react'
+import {HeartIcon, InboxIcon, ChevronDownIcon, BoldIcon} from '@primer/octicons-react'
 import React from 'react'
 import {IconButton} from '.'
 import {ActionMenu} from '../ActionMenu'
@@ -88,3 +88,17 @@ export const AsAMenuAnchor = () => (
     </ActionMenu.Overlay>
   </ActionMenu>
 )
+
+export const KeyshortcutsOnDescription = () => (
+  <IconButton
+    unsafeDisableTooltip={false}
+    icon={InboxIcon}
+    aria-label="Notifications"
+    description="You have unread notifications"
+    keyshortcuts="G+N"
+  />
+)
+
+export const Keyshortcuts = () => (
+  <IconButton unsafeDisableTooltip={false} icon={BoldIcon} aria-label="Bold" keyshortcuts="Command+B" />
+)

packages/react/src/Button/IconButton.tsx

@@ -18,6 +18,7 @@ const IconButton = forwardRef(
       tooltipDirection,
       // This is planned to be a temporary prop until the default tooltip on icon buttons are fully rolled out.
       unsafeDisableTooltip = false,
+      keyshortcuts,
       ...props
     },
     forwardedRef,
@@ -53,10 +54,13 @@ const IconButton = forwardRef(
         />
       )
     } else {
+      // Does it have keyshortcuts?
+      const tooltipSuffix = keyshortcuts ? `, ${keyshortcuts}` : ''
+      const tooltipText = description ?? ariaLabel
       return (
         <Tooltip
           ref={forwardedRef}
-          text={description ?? ariaLabel}
+          text={`${tooltipText}${tooltipSuffix}`}
           type={description ? undefined : 'label'}
           direction={tooltipDirection}
         >
@@ -65,6 +69,7 @@ const IconButton = forwardRef(
             data-component="IconButton"
             sx={sxStyles}
             type="button"
+            aria-keyshortcuts={keyshortcuts ?? undefined}
             // 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}

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

@@ -138,4 +138,49 @@ describe('Button', () => {
     expect(triggerEl).toHaveAttribute('aria-labelledby', tooltipEl.id)
     expect(triggerEl).not.toHaveAttribute('aria-label')
   })
+  it('should render aria-keyshorts on an icon button when keyshortcuts prop is passed', () => {
+    const {getByRole} = render(
+      <IconButton unsafeDisableTooltip={false} icon={HeartIcon} aria-label="Heart" keyshortcuts="Command+H" />,
+    )
+    const triggerEl = getByRole('button')
+    expect(triggerEl).toHaveAttribute('aria-keyshortcuts', 'Command+H')
+  })
+  it('should append the keyshortcuts to the tooltip text that labels the icon button when keyshortcuts prop is passed', () => {
+    const {getByRole, getByText} = render(
+      <IconButton unsafeDisableTooltip={false} icon={HeartIcon} aria-label="Heart" keyshortcuts="Command+H" />,
+    )
+    const triggerEl = getByRole('button')
+    const tooltipEl = getByText('Heart, Command+H')
+    expect(tooltipEl).toBeInTheDocument()
+    expect(triggerEl).toHaveAttribute('aria-labelledby', tooltipEl.id)
+  })
+  it('should render aria-keyshorts on an icon button when keyshortcuts prop is passed (Description Type)', () => {
+    const {getByRole, getByText} = render(
+      <IconButton
+        unsafeDisableTooltip={false}
+        icon={HeartIcon}
+        aria-label="Heart"
+        description="Love is all around"
+        keyshortcuts="Command+H"
+      />,
+    )
+    const triggerEl = getByRole('button')
+    const tooltipEl = getByText('Love is all around, Command+H')
+    expect(triggerEl).toHaveAttribute('aria-describedby', tooltipEl.id)
+  })
+  it('should append the keyshortcuts to the tooltip text that describes the icon button when keyshortcuts prop is passed (Description Type)', () => {
+    const {getByRole, getByText} = render(
+      <IconButton
+        unsafeDisableTooltip={false}
+        icon={HeartIcon}
+        aria-label="Heart"
+        description="Love is all around"
+        keyshortcuts="Command+H"
+      />,
+    )
+    const triggerEl = getByRole('button')
+    const tooltipEl = getByText('Love is all around, Command+H')
+    expect(tooltipEl).toBeInTheDocument()
+    expect(triggerEl).toHaveAttribute('aria-describedby', tooltipEl.id)
+  })
 })

packages/react/src/Button/types.ts

@@ -85,6 +85,7 @@ export type IconButtonProps = ButtonA11yProps & {
   unsafeDisableTooltip?: boolean
   description?: string
   tooltipDirection?: TooltipDirection
+  keyshortcuts?: string
 } & Omit<ButtonBaseProps, 'aria-label' | 'aria-labelledby'>
 
 // adopted from React.AnchorHTMLAttributes

script/generate-e2e-tests.js

@@ -624,6 +624,14 @@ const components = new Map([
           id: 'components-iconbutton-features--small',
           name: 'Small',
         },
+        {
+          id: 'components-iconbutton-features--keyshortcuts',
+          name: 'Keyshortcuts',
+        },
+        {
+          id: 'components-iconbutton-features--keyshortcuts-on-description',
+          name: 'Keyshortcuts on Description',
+        },
       ],
     },
   ],