fix: Tooltip describe variant using aria-description string instead of aria-describedby reference

cypress/integration/Tooltip.spec.ts

@@ -136,9 +136,10 @@ describe('Tooltip', () => {
         cy.checkA11y();
       });
 
-      it('the "Delete" button should have an aria-describedby linking to the role="tooltip" element', () => {
+      it('the "Delete" button should have an accessible description equal to the tooltip text', () => {
         cy.findByRole('button', {name: 'Delete'}).should(
-          'have.ariaDescription',
+          'have.attr',
+          'aria-description',
           'The service will restart after this action'
         );
       });
@@ -354,9 +355,7 @@ describe('Tooltip', () => {
           context(`when the preferred placement is set to ${io.placement}`, () => {
             beforeEach(() => {
               if (io.isMovedToSide) {
-                cy.findByTestId(`slide-${io.placement}`)
-                  .type('500')
-                  .trigger('change');
+                cy.findByTestId(`slide-${io.placement}`).type('500').trigger('change');
               }
               cy.findByRole('button', {name: io.placement}).click();
               cy.scrollTo(io.x, io.y);

modules/react/_examples/stories/Tooltips.stories.mdx

@@ -0,0 +1,16 @@
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {ListOfUploadedFiles} from './examples/Tooltips/ListOfUploadedFiles';
+
+<Meta title="Examples/Tooltips" component={Tooltip} />
+
+# Accessible Tooltip Examples
+
+## Using descriptive tooltips for repeated text buttons
+
+In this example, the "Delete" buttons are used repeatedly to reference the multiple files that have
+been uploaded to the web app. The text buttons already have an accessible name (a.k.a. label)
+derived from the button's inner text. The `describe` tooltip can be useful for providing more
+in-context description for both low vision sighted users and screen reader users without overriding
+the button name "Delete".
+
+<ExampleCodeBlock code={ListOfUploadedFiles} />

modules/react/_examples/stories/examples/Tooltips/ListOfUploadedFiles.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+
+import {DeleteButton} from '@workday/canvas-kit-react/button';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {Heading, Text} from '@workday/canvas-kit-react/text';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {trashIcon} from '@workday/canvas-system-icons-web';
+
+const files = ['Cover Letter.docx', 'Resume.docx', 'Portfolio.pptx', 'Portrait.png'];
+
+const listStyles = {
+  alignItems: 'center',
+  width: '35rem',
+};
+
+const deleteBtnStyle = {
+  marginLeft: 'auto',
+};
+
+export const ListOfUploadedFiles = () => {
+  return (
+    <>
+      <Heading size="medium">Uploaded Files:</Heading>
+      <Flex as="ul" gap="1rem" flexDirection="column">
+        {files.map(i => (
+          <Flex as="li" style={listStyles}>
+            <Text>{i}</Text>
+            <Tooltip type="describe" title={i}>
+              <DeleteButton icon={trashIcon} style={deleteBtnStyle}>
+                Delete
+              </DeleteButton>
+            </Tooltip>
+          </Flex>
+        ))}
+      </Flex>
+    </>
+  );
+};

modules/react/tooltip/lib/useTooltip.tsx

@@ -65,7 +65,7 @@ export function useTooltip<T extends Element = Element>({
    * - `label`: Sets the accessible name for the wrapped element. Use for icons or if tooltip
    *   `title` prop is the same as the text content of the wrapped element. E.g. TertiaryButton that renders an icon or
    *   Ellipsis tooltips.
-   * - `describe`: Sets `aria-describedby` of the wrapped element. Use if the tooltip has additional
+   * - `describe`: Sets `aria-description` strings for the wrapped element. Use if the tooltip has additional
    *   information about the target.
    * - `muted`: No effort is made to make the tooltip accessible to screen readers. Use if the
    *   tooltip contents are not useful to a screen reader or if you have handled accessibility of
@@ -135,7 +135,7 @@ export function useTooltip<T extends Element = Element>({
 
   const targetProps = {
     // extra description of the target element for assistive technology
-    'aria-describedby': type === 'describe' && visible ? id : undefined,
+    'aria-description': type === 'describe' ? titleText : undefined,
     // This will replace the accessible name of the target element
     'aria-label': type === 'label' ? titleText : undefined,
     onMouseEnter: onOpenFromTarget,
@@ -145,11 +145,6 @@ export function useTooltip<T extends Element = Element>({
     onBlur: onHide,
   };
 
-  // remove `aria-describedby` if undefined to not override what's provided
-  if (targetProps['aria-describedby'] === undefined) {
-    delete targetProps['aria-describedby'];
-  }
-
   return {
     /** Mix these properties into the target element. **Must be an Element** */
     targetProps,

modules/react/tooltip/spec/Tooltip.spec.tsx

@@ -28,10 +28,9 @@ describe('Tooltip', () => {
       fireEvent.mouseEnter(screen.getByText('Test Text')); // triggers the tooltip
 
       jest.advanceTimersByTime(300); // advance the timer by the amount of delay time
-      expect(screen.getByText('Test Text')).toHaveAttribute('aria-describedby');
+      expect(screen.getByText('Test Text')).toHaveAttribute('aria-description');
 
-      const id = screen.getByText('Test Text').getAttribute('aria-describedby');
-      expect(screen.getByRole('tooltip')).toHaveAttribute('id', id);
+      expect(screen.getByRole('tooltip')).toHaveAttribute('id');
     });
     jest.clearAllTimers();
   });

modules/react/tooltip/spec/useTooltip.spec.tsx

@@ -46,8 +46,7 @@ describe('useTooltip with type="describe"', () => {
     jest.advanceTimersByTime(300); // advance the timer by the amount of delay time
 
     expect(tooltip).toHaveAttribute('id');
-    const id = tooltip.getAttribute('id');
-    expect(target).toHaveAttribute('aria-describedby', id);
+    expect(target).toHaveAttribute('aria-description');
   });
   jest.clearAllTimers();
 });

modules/react/tooltip/stories/Tooltip.stories.mdx

@@ -67,10 +67,10 @@ and focus events.
 
 ### Describing an Element
 
-The default mode for a tooltip is to label content via `aria-label`. If a tooltip is meant to
-provide ancillary information, the `type` can be set to `describe`. This will add `aria-describedby`
-to the target element. This will allow screen reader users to hear the name of the control that is
-being focused and the ancillary tooltip information.
+The default mode for a tooltip is to assign a name to the target element with an `aria-label`
+string. If a tooltip is meant to provide ancillary information, the `type` can be set to `describe`.
+This will add `aria-description` strings to the target element instead. This variant is useful on
+text buttons and other components that already have a label or name.
 
 <ExampleCodeBlock code={DescribeType} />
 

modules/react/tooltip/stories/examples/DescribeType.tsx

@@ -1,12 +1,22 @@
 import React from 'react';
 
-import {DeleteButton} from '@workday/canvas-kit-react/button';
+import {DeleteButton, SecondaryButton, TertiaryButton} from '@workday/canvas-kit-react/button';
 import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {chartConfigIcon} from '@workday/canvas-system-icons-web';
 
 export const DescribeType = () => {
   return (
-    <Tooltip type="describe" title="The service will restart after this action">
-      <DeleteButton>Delete</DeleteButton>
-    </Tooltip>
+    <Flex gap="s">
+      <Tooltip type="describe" title="Search using additional criteria">
+        <TertiaryButton icon={chartConfigIcon}>Advanced Search</TertiaryButton>
+      </Tooltip>
+      <Tooltip type="describe" title="Create saved search">
+        <SecondaryButton>Save</SecondaryButton>
+      </Tooltip>
+      <Tooltip type="describe" title="The service will restart after this action">
+        <DeleteButton>Delete</DeleteButton>
+      </Tooltip>
+    </Flex>
   );
 };