Add keyboard-accessible tooltip for truncated ActionList.Description

.changeset/chatty-paws-attend.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Add keyboard-accessible tooltip for truncated ActionList.Description

packages/react/src/ActionList/ActionList.module.css

@@ -541,12 +541,12 @@
       transform: scaleY(1);
     }
 
-    & + .SubGroup {
+    & ~ .SubGroup {
       display: none;
     }
 
     /* show active indicator on parent collapse if child is active */
-    &:has(+ .SubGroup [data-active='true']) {
+    &:has(~ .SubGroup [data-active='true']) {
       background: var(--control-transparent-bgColor-selected);
 
       & .ItemLabel {

packages/react/src/ActionList/ActionList.test.tsx

@@ -145,7 +145,7 @@ describe('ActionList', () => {
     expect(container.querySelector('li[aria-disabled="true"]')?.nextElementSibling).toHaveAttribute('tabindex', '0')
   })
 
-  it('sets title correctly for Description component', () => {
+  it('sets Description title for button-semantics items (tooltip path)', () => {
     const {container} = HTMLRender(
       <ActionList>
         <ActionList.Item>
@@ -168,6 +168,36 @@ describe('ActionList', () => {
 
     const descriptions = container.querySelectorAll('[data-component="ActionList.Description"]')
 
+    // For button-semantic items, the native title is suppressed in favor of
+    // a keyboard-accessible Tooltip rendered by the parent Item.
+    expect(descriptions[0]).toHaveAttribute('title', '')
+    expect(descriptions[1]).toHaveAttribute('title', '')
+    expect(descriptions[2]).not.toHaveAttribute('title')
+  })
+
+  it('sets Description title for list-semantics items (no truncation tooltip path)', () => {
+    const {container} = HTMLRender(
+      <ActionList role="listbox" selectionVariant="single">
+        <ActionList.Item>
+          Option 1<ActionList.Description truncate>Simple string description</ActionList.Description>
+        </ActionList.Item>
+        <ActionList.Item>
+          Option 2
+          <ActionList.Description truncate>
+            <span>Complex</span> content
+          </ActionList.Description>
+        </ActionList.Item>
+        <ActionList.Item>
+          Option 3
+          <ActionList.Description>
+            <span>Non-truncated</span> content
+          </ActionList.Description>
+        </ActionList.Item>
+      </ActionList>,
+    )
+
+    const descriptions = container.querySelectorAll('[data-component="ActionList.Description"]')
+
     expect(descriptions[0]).toHaveAttribute('title', 'Simple string description')
     expect(descriptions[1]).toHaveAttribute('title', 'Complex content')
     expect(descriptions[2]).not.toHaveAttribute('title')

packages/react/src/ActionList/Description.test.tsx

@@ -32,7 +32,9 @@ describe('ActionList.Description', () => {
 
     const description = getByText('Item 1 description')
     expect(description.tagName).toBe('DIV')
-    expect(description).toHaveAttribute('title', 'Item 1 description')
+    // For button-semantic items, the native title is suppressed in favor of
+    // a keyboard-accessible Tooltip rendered by the parent Item.
+    expect(description).toHaveAttribute('title', '')
     expect(description).toHaveStyle('flex-basis: auto')
     expect(description).toHaveStyle('text-overflow: ellipsis')
     expect(description).toHaveStyle('overflow: hidden')

packages/react/src/ActionList/Description.tsx

@@ -29,17 +29,27 @@ export const Description: FCWithSlotMarker<React.PropsWithChildren<ActionListDes
   style,
   ...props
 }) => {
-  const {blockDescriptionId, inlineDescriptionId} = React.useContext(ItemContext)
+  const {blockDescriptionId, inlineDescriptionId, setTruncatedText} = React.useContext(ItemContext)
   const containerRef = React.useRef<HTMLDivElement>(null)
   const [computedTitle, setComputedTitle] = React.useState<string>('')
 
   // Extract text content from rendered DOM for tooltip
   React.useEffect(() => {
     if (truncate && containerRef.current) {
-      const textContent = containerRef.current.textContent || ''
+      const el = containerRef.current
+      const textContent = el.textContent || ''
       setComputedTitle(textContent)
+      if (setTruncatedText) {
+        setTruncatedText(
+          el.scrollWidth > el.clientWidth
+            ? typeof props.children === 'string'
+              ? props.children
+              : textContent
+            : undefined,
+        )
+      }
     }
-  }, [truncate, props.children])
+  }, [truncate, props.children, setTruncatedText])
 
   const effectiveTitle = typeof props.children === 'string' ? props.children : computedTitle
 
@@ -61,7 +71,7 @@ export const Description: FCWithSlotMarker<React.PropsWithChildren<ActionListDes
         id={inlineDescriptionId}
         className={clsx(className, classes.Description)}
         style={style}
-        title={effectiveTitle}
+        title={setTruncatedText ? '' : effectiveTitle}
         inline={true}
         maxWidth="100%"
         data-component="ActionList.Description"

packages/react/src/ActionList/Item.test.tsx

@@ -3,6 +3,7 @@ import {render as HTMLRender, waitFor, fireEvent} from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import React, {type JSX} from 'react'
 import {ActionList} from '.'
+import {AnchoredOverlay} from '../AnchoredOverlay'
 import {BookIcon} from '@primer/octicons-react'
 import {implementsClassName} from '../utils/testing'
 import classes from './ActionList.module.css'
@@ -385,4 +386,49 @@ describe('ActionList.Item', () => {
     expect(tabs[0].nodeType).toBe(Node.ELEMENT_NODE)
     expect(tabs).toHaveLength(3)
   })
+
+  it('should preserve consumer ref when tooltip wraps trigger', async () => {
+    const user = userEvent.setup()
+
+    function TestComponent() {
+      const anchorRef = React.useRef<HTMLLIElement>(null)
+      const [open, setOpen] = React.useState(false)
+      return (
+        <>
+          <ActionList aria-label="Actions">
+            <ActionList.Item
+              ref={anchorRef}
+              onSelect={() => {
+                setOpen(!open)
+              }}
+            >
+              Convert to issue
+              <ActionList.Description truncate>
+                This description gets truncated because it is inline with truncation
+              </ActionList.Description>
+            </ActionList.Item>
+          </ActionList>
+          <AnchoredOverlay open={open} renderAnchor={null} anchorRef={anchorRef} onClose={() => setOpen(false)}>
+            <ActionList role="menu" aria-label="Convert to issue menu">
+              <ActionList.Item role="menuitem">Choose repository</ActionList.Item>
+              <ActionList.Item role="menuitem">Create issue</ActionList.Item>
+            </ActionList>
+          </AnchoredOverlay>
+        </>
+      )
+    }
+
+    const {getByText, queryByRole} = HTMLRender(<TestComponent />)
+
+    // Overlay should not be visible initially
+    expect(queryByRole('menu')).not.toBeInTheDocument()
+
+    // Click the item to open the anchored overlay
+    await user.click(getByText('Convert to issue'))
+
+    // The overlay should open — this fails if Tooltip overwrites the consumer ref
+    await waitFor(() => {
+      expect(queryByRole('menu')).toBeInTheDocument()
+    })
+  })
 })

packages/react/src/ActionList/Item.tsx

@@ -1,5 +1,4 @@
 import React, {type JSX} from 'react'
-
 import {useId} from '../hooks/useId'
 import {useSlots} from '../hooks/useSlots'
 import {ActionListContainerContext} from './ActionListContainerContext'
@@ -16,11 +15,35 @@ import VisuallyHidden from '../_VisuallyHidden'
 import classes from './ActionList.module.css'
 import {clsx} from 'clsx'
 import {fixedForwardRef} from '../utils/modern-polymorphic'
+import {Tooltip} from '../TooltipV2'
+import {TooltipContext} from '../TooltipV2/Tooltip'
 
 type ActionListSubItemProps = {
   children?: React.ReactNode
 }
 
+/**
+ * Wraps button-semantic items with Tooltip, disabled when not truncated
+ * For non-button-semantic items, renders children directly.
+ */
+const ConditionalTooltip = React.forwardRef<
+  HTMLElement,
+  {
+    text: string | undefined
+    enabled: boolean
+    children: React.ReactElement
+  }
+>(function ConditionalTooltip({text, enabled, children}, forwardedRef) {
+  if (!enabled || !text) {
+    return children
+  }
+  return (
+    <Tooltip ref={forwardedRef} text={text || ''} direction="e" delay="medium">
+      {children}
+    </Tooltip>
+  )
+})
+
 export const SubItem: React.FC<ActionListSubItemProps> = ({children}) => {
   return <>{children}</>
 }
@@ -185,6 +208,8 @@ const UnwrappedItem = <As extends React.ElementType = 'li'>(
   const trailingVisualId = `${itemId}--trailing-visual`
   const inactiveWarningId = inactive && !showInactiveIndicator ? `${itemId}--warning-message` : undefined
 
+  const [truncatedText, setTruncatedText] = React.useState<string | undefined>(undefined)
+
   const DefaultItemWrapper = listSemantics ? DivItemContainerNoBox : ButtonItemContainerNoBox
 
   const ItemWrapper = _PrivateItemWrapper || DefaultItemWrapper
@@ -209,12 +234,11 @@ const UnwrappedItem = <As extends React.ElementType = 'li'>(
     'data-inactive': inactive ? true : undefined,
     'data-loading': loading && !inactive ? true : undefined,
     tabIndex: focusable ? undefined : 0,
-    'aria-labelledby': `${labelId} ${slots.trailingVisual ? trailingVisualId : ''} ${
-      slots.description && descriptionVariant === 'inline' ? inlineDescriptionId : ''
-    }`,
+    'aria-labelledby': `${labelId} ${slots.trailingVisual ? trailingVisualId : ''}`,
     'aria-describedby':
       [
         slots.description && descriptionVariant === 'block' ? blockDescriptionId : undefined,
+        slots.description && descriptionVariant === 'inline' ? inlineDescriptionId : undefined,
         inactiveWarningId ?? undefined,
       ]
         .filter(String)
@@ -248,6 +272,7 @@ const UnwrappedItem = <As extends React.ElementType = 'li'>(
         inlineDescriptionId,
         blockDescriptionId,
         trailingVisualId,
+        setTruncatedText: buttonSemantics ? setTruncatedText : undefined,
       }}
     >
       <li
@@ -261,59 +286,65 @@ const UnwrappedItem = <As extends React.ElementType = 'li'>(
         data-has-description={slots.description ? true : false}
         className={clsx(classes.ActionListItem, className)}
       >
-        <ItemWrapper
-          {...wrapperProps}
-          className={classes.ActionListContent}
-          data-size={size}
-          // @ts-ignore: ItemWrapper is polymorphic and the ref type depends on the rendered element ('button' or 'li')
-          ref={forwardedRef}
-        >
-          <span className={classes.Spacer} />
-          <Selection selected={selected} className={classes.LeadingAction} />
-          <VisualOrIndicator
-            inactiveText={showInactiveIndicator ? inactiveText : undefined}
-            itemHasLeadingVisual={Boolean(slots.leadingVisual)}
-            labelId={labelId}
-            loading={loading}
-            position="leading"
+        <ConditionalTooltip ref={forwardedRef} text={truncatedText} enabled={buttonSemantics}>
+          <ItemWrapper
+            {...wrapperProps}
+            className={classes.ActionListContent}
+            data-size={size}
+            // @ts-ignore: ItemWrapper is polymorphic and the ref type depends on the rendered element ('button' or 'li')
+            ref={forwardedRef}
           >
-            {slots.leadingVisual}
-          </VisualOrIndicator>
-          <span className={classes.ActionListSubContent} data-component="ActionList.Item--DividerContainer">
-            <ConditionalWrapper
-              if={!!slots.description}
-              className={classes.ItemDescriptionWrap}
-              data-description-variant={descriptionVariant}
-            >
-              <span id={labelId} className={classes.ItemLabel}>
-                {childrenWithoutSlots}
-                {/* Loading message needs to be in here so it is read with the label */}
-                {/* If the item is inactive, we do not simultaneously announce that it is loading */}
-                {loading === true && !inactive && <VisuallyHidden>Loading</VisuallyHidden>}
+            {/* Reset TooltipContext so that child components don't detect
+                the ConditionalTooltip and suppress their own internal tooltips. */}
+            <TooltipContext.Provider value={{}}>
+              <span className={classes.Spacer} />
+              <Selection selected={selected} className={classes.LeadingAction} />
+              <VisualOrIndicator
+                inactiveText={showInactiveIndicator ? inactiveText : undefined}
+                itemHasLeadingVisual={Boolean(slots.leadingVisual)}
+                labelId={labelId}
+                loading={loading}
+                position="leading"
+              >
+                {slots.leadingVisual}
+              </VisualOrIndicator>
+              <span className={classes.ActionListSubContent} data-component="ActionList.Item--DividerContainer">
+                <ConditionalWrapper
+                  if={!!slots.description}
+                  className={classes.ItemDescriptionWrap}
+                  data-description-variant={descriptionVariant}
+                >
+                  <span id={labelId} className={classes.ItemLabel}>
+                    {childrenWithoutSlots}
+                    {/* Loading message needs to be in here so it is read with the label */}
+                    {/* If the item is inactive, we do not simultaneously announce that it is loading */}
+                    {loading === true && !inactive && <VisuallyHidden>Loading</VisuallyHidden>}
+                  </span>
+                  {slots.description}
+                </ConditionalWrapper>
+                <VisualOrIndicator
+                  inactiveText={showInactiveIndicator ? inactiveText : undefined}
+                  itemHasLeadingVisual={Boolean(slots.leadingVisual)}
+                  labelId={labelId}
+                  loading={loading}
+                  position="trailing"
+                >
+                  {trailingVisual}
+                </VisualOrIndicator>
+
+                {
+                  // If the item is inactive, but it's not in an overlay (e.g. ActionMenu, SelectPanel),
+                  // render the inactive warning message directly in the item.
+                  !showInactiveIndicator && inactiveText ? (
+                    <span className={classes.InactiveWarning} id={inactiveWarningId}>
+                      {inactiveText}
+                    </span>
+                  ) : null
+                }
               </span>
-              {slots.description}
-            </ConditionalWrapper>
-            <VisualOrIndicator
-              inactiveText={showInactiveIndicator ? inactiveText : undefined}
-              itemHasLeadingVisual={Boolean(slots.leadingVisual)}
-              labelId={labelId}
-              loading={loading}
-              position="trailing"
-            >
-              {trailingVisual}
-            </VisualOrIndicator>
-
-            {
-              // If the item is inactive, but it's not in an overlay (e.g. ActionMenu, SelectPanel),
-              // render the inactive warning message directly in the item.
-              !showInactiveIndicator && inactiveText ? (
-                <span className={classes.InactiveWarning} id={inactiveWarningId}>
-                  {inactiveText}
-                </span>
-              ) : null
-            }
-          </span>
-        </ItemWrapper>
+            </TooltipContext.Provider>
+          </ItemWrapper>
+        </ConditionalTooltip>
         {!inactive && !loading && !menuContext && Boolean(slots.trailingAction) && slots.trailingAction}
         {slots.subItem}
       </li>

packages/react/src/ActionList/shared.ts

@@ -85,6 +85,7 @@ export type ItemContext = Pick<ActionListItemProps<React.ElementType>, 'variant'
   blockDescriptionId?: string
   trailingVisualId?: string
   inactive?: boolean
+  setTruncatedText?: (text: string | undefined) => void
 }
 
 export const ItemContext = React.createContext<ItemContext>({})

packages/react/src/TooltipV2/Tooltip.tsx

@@ -360,10 +360,10 @@ export const Tooltip: ForwardRefExoticComponent<
                 <span id={hasAriaLabel ? undefined : tooltipId}>
                   {text}
                   {/* There is a bug in Chrome browsers where `aria-hidden` text inside the target of an `aria-labelledby`
-               still gets included in the accessible label. `KeybindingHint` renders the symbols as `aria-hidden` text
-               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. */}
+                   still gets included in the accessible label. `KeybindingHint` renders the symbols as `aria-hidden` text
+                   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>
                 </span>
                 <span className={clsx(classes.KeybindingHintContainer, text && classes.HasTextBefore)} aria-hidden>