Update IconButton and ActionBar.IconButton to support multiple keybinding hints

.changeset/iconbutton-keybinding-hint-array.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+`IconButton`: `keybindingHint` now accepts `string[]` in addition to `string`. Multiple hints are rendered joined with "or".

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

@@ -88,6 +88,10 @@ export const KeybindingHintOnDescription = () => (
 
 export const KeybindingHint = () => <IconButton icon={BoldIcon} aria-label="Bold" keybindingHint="Mod+B" />
 
+export const MultipleKeybindingHints = () => (
+  <IconButton icon={BoldIcon} aria-label="Bold" keybindingHint={['Mod+B', 'Control+B']} />
+)
+
 export const LongDelayedTooltip = () => (
   // Ideal for cases where we don't want to show the tooltip immediately — for example, when the user is just passing over the element.
   <Tooltip text="This is a tooltip with 1200ms delay" delay="long">

packages/react/src/Button/types.ts

@@ -91,7 +91,7 @@ export type IconButtonProps = ButtonA11yProps & {
   tooltipDirection?: TooltipDirection
   /** @deprecated Use `keybindingHint` instead. */
   keyshortcuts?: string
-  keybindingHint?: string
+  keybindingHint?: string | string[]
 } & Omit<ButtonBaseProps, 'aria-label' | 'aria-labelledby'>
 
 // adopted from React.AnchorHTMLAttributes

packages/react/src/TooltipV2/Tooltip.tsx

@@ -17,7 +17,7 @@ export type TooltipProps = React.PropsWithChildren<{
   direction?: TooltipDirection
   text: string
   type?: 'label' | 'description'
-  keybindingHint?: KeybindingHintProps['keys']
+  keybindingHint?: KeybindingHintProps['keys'] | Array<KeybindingHintProps['keys']>
   /**
    * Delay in milliseconds before showing the tooltip
    * @default short (50ms)
@@ -273,6 +273,15 @@ export const Tooltip: ForwardRefExoticComponent<
     const isMacOS = useIsMacOS()
     const hasAriaLabel = 'aria-label' in rest
 
+    // Normalize keybindingHint to an array for uniform rendering, treating empty arrays as undefined
+    const keybindingHints = keybindingHint
+      ? Array.isArray(keybindingHint)
+        ? keybindingHint.length > 0
+          ? keybindingHint
+          : undefined
+        : [keybindingHint]
+      : undefined
+
     return (
       <TooltipContext.Provider value={value}>
         <>
@@ -353,9 +362,9 @@ export const Tooltip: ForwardRefExoticComponent<
             onMouseEnter={openTooltip}
             onMouseLeave={closeTooltip}
             // If there is an aria-label prop, always assign the ID to the parent so the accessible label can be overridden
-            id={hasAriaLabel || !keybindingHint ? tooltipId : undefined}
+            id={hasAriaLabel || !keybindingHints ? tooltipId : undefined}
           >
-            {keybindingHint ? (
+            {keybindingHints ? (
               <>
                 <span id={hasAriaLabel ? undefined : tooltipId}>
                   {text}
@@ -364,10 +373,17 @@ export const Tooltip: ForwardRefExoticComponent<
                and renders full key names as `VisuallyHidden` text. Due to the browser bug this causes the label text
                to duplicate the symbols and key names. To work around this, we exclude the hint from being part of the
                label and instead render the plain keybinding description string. */}
-                  <VisuallyHidden>({getAccessibleKeybindingHintString(keybindingHint, isMacOS)})</VisuallyHidden>
+                  <VisuallyHidden>
+                    ({keybindingHints.map(hint => getAccessibleKeybindingHintString(hint, isMacOS)).join(' or ')})
+                  </VisuallyHidden>
                 </span>
                 <span className={clsx(classes.KeybindingHintContainer, text && classes.HasTextBefore)} aria-hidden>
-                  <KeybindingHint keys={keybindingHint} format="condensed" variant="onEmphasis" size="small" />
+                  {keybindingHints.map((hint, i) => (
+                    <React.Fragment key={`${i}-${hint}`}>
+                      {i > 0 && ' or '}
+                      <KeybindingHint keys={hint} format="condensed" variant="onEmphasis" size="small" />
+                    </React.Fragment>
+                  ))}
                 </span>
               </>
             ) : (

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

@@ -172,6 +172,23 @@ describe('Tooltip', () => {
     )
     expect(getByRole('button', {name: 'Overridden label'})).toBeInTheDocument()
   })
+  it('includes multiple keybinding hints joined with "or" in the label text', () => {
+    const {getByRole} = HTMLRender(<TooltipComponent type="label" keybindingHint={['Control+K', 'Control+Shift+K']} />)
+    expect(getByRole('button', {name: 'Tooltip text (control k or control shift k)'})).toBeInTheDocument()
+  })
+  it('renders multiple keybinding hints when an array is provided', () => {
+    const {getAllByTestId, container} = HTMLRender(
+      <TooltipComponent keybindingHint={['Control+K', 'Control+Shift+K']} />,
+    )
+    expect(getAllByTestId('keybinding-hint')).toHaveLength(2)
+    // Verify the "or" separator is rendered between keybinding hints
+    const hintContainer = container.querySelector('[aria-hidden="true"] [aria-hidden="true"]')
+    expect(hintContainer?.textContent).toContain(' or ')
+  })
+  it('treats an empty array keybindingHint as if no hint was provided', () => {
+    const {queryByTestId} = HTMLRender(<TooltipComponent keybindingHint={[]} />)
+    expect(queryByTestId('keybinding-hint')).not.toBeInTheDocument()
+  })
 
   it('should append tooltip id to existing aria-describedby value on the trigger element', () => {
     const {getByRole, getByText} = HTMLRender(<TooltipComponentWithExistingDescription />)