fix: tooltip and icon-button respect child aria attributes (#19308)

* fix: tooltip and icon-button respect child aria attributes

* test: add aria accessibility tests for Tooltip

* refactor: apply review suggestion to simplify aria logic

* fix(tooltip): ignore empty or whitespace aria-labels for a11y support

Author: heloiselui

packages/react/src/components/IconButton/index.tsx

@@ -220,7 +220,7 @@ const IconButton = React.forwardRef(function IconButton(
         isSelected={isSelected}
         hasIconOnly
         className={className}
-        aria-describedby={badgeCount && badgeId}>
+        aria-describedby={rest['aria-describedby'] || (badgeCount && badgeId)}>
         {children}
         {!disabled && badgeCount !== undefined && (
           <BadgeIndicator
@@ -350,8 +350,13 @@ IconButton.propTypes = {
   /**
    * Provide the label to be rendered inside of the Tooltip. The label will use
    * `aria-labelledby` and will fully describe the child node that is provided.
+   * If the child node already has an `aria-label`, the tooltip will not apply
+   * `aria-labelledby`. If the child node has `aria-labelledby`, that value will
+   * be used instead. Otherwise, the tooltip will use its own ID as the label.
    * This means that if you have text in the child node it will not be
    * announced to the screen reader.
+   * If using `badgeCount={0}`, make sure the label explains that there is a
+   * new notification.
    */
   label: PropTypes.node.isRequired,
 

packages/react/src/components/Tooltip/Tooltip.tsx

@@ -81,6 +81,9 @@ interface TooltipBaseProps {
   /**
    * Provide the label to be rendered inside of the Tooltip. The label will use
    * `aria-labelledby` and will fully describe the child node that is provided.
+   * If the child already has an `aria-label`, the tooltip will not apply
+   * `aria-labelledby`. If the child has its own `aria-labelledby`, that value
+   * will be kept. Otherwise, the tooltip will use its own ID to label the child.
    * This means that if you have text in the child node, that it will not be
    * announced to the screen reader.
    *
@@ -130,6 +133,30 @@ const Tooltip: TooltipComponent = React.forwardRef(
     const prefix = usePrefix();
     const child = React.Children.only(children);
 
+    const {
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      'aria-describedby': ariaDescribedBy,
+    } = child?.props ?? {};
+
+    const hasLabel = !!label;
+    const hasAriaLabel =
+      typeof ariaLabel === 'string' ? ariaLabel.trim() !== '' : false;
+
+    // An `aria-label` takes precedence over `aria-describedby`, but when it's
+    // needed and the user doesn't specify one, the fallback `id` is used.
+    const labelledBy = hasAriaLabel
+      ? null
+      : hasLabel
+        ? (ariaLabelledBy ?? id)
+        : undefined;
+
+    // If `aria-label` is present, use any provided `aria-describedby`.
+    // If not, fallback to child's `aria-describedby` or the tooltip `id` if needed.
+    const describedBy = hasAriaLabel
+      ? ariaDescribedBy
+      : (ariaDescribedBy ?? (!hasLabel && !ariaLabelledBy ? id : undefined));
+
     const triggerProps = {
       onFocus: () => !focusByMouse && setOpen(true),
       onBlur: () => {
@@ -143,6 +170,8 @@ const Tooltip: TooltipComponent = React.forwardRef(
       onMouseDown,
       onMouseMove: onMouseMove,
       onTouchStart: onDragStart,
+      'aria-labelledby': labelledBy,
+      'aria-describedby': describedBy,
     };
 
     function getChildEventHandlers(childProps: any) {
@@ -161,12 +190,6 @@ const Tooltip: TooltipComponent = React.forwardRef(
       return eventHandlers;
     }
 
-    if (label) {
-      triggerProps['aria-labelledby'] = id;
-    } else {
-      triggerProps['aria-describedby'] = id;
-    }
-
     const onKeyDown = useCallback(
       (event: KeyboardEvent) => {
         if (open && match(event, keys.Escape)) {

packages/react/src/components/Tooltip/__tests__/Tooltip-test.js

@@ -110,3 +110,60 @@ describe('Tooltip', () => {
     expect(popoverContainer).not.toHaveClass('cds--popover--open');
   });
 });
+
+describe('Tooltip ARIA logic', () => {
+  it('should not use aria-labelledby when the button already has aria-label', () => {
+    render(
+      <Tooltip defaultOpen label="Label text">
+        <button aria-label="Aria Label">X</button>
+      </Tooltip>
+    );
+    const button = screen.getByRole('button');
+    expect(button).not.toHaveAttribute('aria-labelledby');
+    expect(button).toHaveAttribute('aria-label', 'Aria Label');
+  });
+
+  it('should keep the button’s aria-labelledby if it already has one', () => {
+    render(
+      <Tooltip defaultOpen label="Label text">
+        <button aria-labelledby="custom-id">X</button>
+      </Tooltip>
+    );
+    const button = screen.getByRole('button');
+    expect(button).toHaveAttribute('aria-labelledby', 'custom-id');
+  });
+
+  it('should apply tooltip ID to aria-labelledby if label is given and the button doesn’t have its own', () => {
+    render(
+      <Tooltip defaultOpen label="Label text">
+        <button>X</button>
+      </Tooltip>
+    );
+    const button = screen.getByRole('button');
+    const tooltip = screen.getByRole('tooltip');
+    expect(button).toHaveAttribute('aria-labelledby', tooltip.id);
+  });
+
+  it('should keep aria-describedby from the button if aria-label is also set', () => {
+    render(
+      <Tooltip defaultOpen description="Some description">
+        <button aria-label="Label" aria-describedby="desc-id">
+          X
+        </button>
+      </Tooltip>
+    );
+    const button = screen.getByRole('button');
+    expect(button).toHaveAttribute('aria-describedby', 'desc-id');
+  });
+
+  it('should use its own ID for aria-describedby if only description is given', () => {
+    render(
+      <Tooltip defaultOpen description="Some description">
+        <button>X</button>
+      </Tooltip>
+    );
+    const button = screen.getByRole('button');
+    const tooltip = screen.getByRole('tooltip');
+    expect(button).toHaveAttribute('aria-describedby', tooltip.id);
+  });
+});