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

[williamjstanton]

Summary

Fixes: #2797

The describe variant of the tool tip relies on aria-describedby attribute to assign the tool tip text to the accessible description of the target element. This only works when the tool tip is visible and present in the DOM, which only occurs when the element has focus. Screen readers can access web page elements without necessarily using keyboard focus, therefore, this variant didn't appear to always work reliably for screen reader users.

Release Category

Components

Release Note

Replaces aria-describedby reference on the target element with an aria-description string

Checklist

• MDX documentation adheres to Canvas Kit's Documentation Guidelines
• Label ready for review has been added to PR

For the Reviewer

For the describe variant of Tooltip, I replaced the aria-describedby attribute with aria-description and set the title prop value string. Also, remove the check for if visible, so we can always assign this string to the description.

• PR title is short and descriptive
• PR summary describes the change (Fixes/Resolves linked correctly)
• PR Release Notes describes additional information useful to call out in a release message or removed if not applicable
• Breaking Changes provides useful information to upgrade to this code or removed if not applicable

Where Should the Reviewer Start?

• in the useTooltip custom hook
• check out the updates to the Describe examples in storybook
• check out the new "Tooltip" section under "Examples" in Storybook

Areas for Feedback? (optional)

• Code
• Documentation
• Testing
• Codemods

Testing Manually

In the following scenarios, validate the issues cannot be reproduced and the tool tip text is always described without focusing the button elements.

Steps to reproduce the behavior:
With VoiceOver / MacOS:

1. Launch VoiceOver, open Safari
2. Canvas Design Site: Tooltip popups > Describing an element
3. Reading commands: Ctrl + Opt + Right
4. Issue: observe tool tip text on Delete button is not described
5. Press Tab to focus “Show Code”
6. Read backward: Ctrl + Opt + Left Arrow
7. Issue: observe tool tip text on Delete button is not described
8. Set Rotor to “Form Fields”: Ctrl + Opt + Cmd + Right Arrow
9. Jump buttons on the page: Ctrl + Opt + Cmd + UP / DOWN arrow
10. Issue: observe tool tip text on Delete button is not described

With NVDA on Windows 11:

1. Launch NVDA, open Chrome
2. Canvas site => Tooltips => Describing an element
3. In virtual mode, use quick key ‘b’ to jump to the Delete Button
4. Issue: observe the tool tip text is not described

Screenshots or GIFs (if applicable)

No visual changes. Just aria attribute change.

Thank You Gif (optional)

[cypress]

Passing run #7439 ↗︎

0

974

3

0

0

Details:

Merge acd19b6 into 244b93b...
Project: Workday/canvas-kit	Commit: 276986cdb0 ℹ️
Status: Passed	Duration: 05:12 💡
Started: Jul 16, 2024 2:19 PM	Ended: Jul 16, 2024 2:24 PM

Review all test suite changes for PR #2814 ↗︎

[RayRedGoose]

I think this is potentially breaking change, because now tooltip will require to have titleText passed, but it's optional now.

[josh-bagwell]

Agree with Raisa. This would be breaking.

Also, shouldn't both be present since aria-describedby points to the target of the element with the id and aria-description is just describing what the element is with nothing pointing to it?

[williamjstanton]

I think this is potentially breaking change, because now tooltip will require to have titleText passed, but it's optional now.

Does this mean title prop was optional? Why?

[williamjstanton]

Also, shouldn't both be present since aria-describedby points to the target of the element with the id and aria-description is just describing what the element is with nothing pointing to it?

No, for similar reasons why we discourage using both aria-labelledby references and aria-label strings on the same element. Browsers follow an algorithm to define a 1) accessible name and 2) accessible description for an element.

If aria-describedby is used on an element, then an aria-description string will be ignored and discarded by the browser.

[NicholasBoll]

titleText is optional in the useTooltip hook, but not the title in the Tooltip component. titleText was optional in useTooltip because type="describe" did not use the config. This change makes it so type="describe" also uses the config. There is still the type="muted" that doesn't use the titleText config.

Now, title is required by Tooltip because it is the contents of the tooltip. OverflowTooltip does not use title because the contents of the target are the contents of the tooltip. An OverflowTooltip uses the type="muted" because a screen reader doesn't understand the concept of the ellipsis - to the screen reader, the full contents are exposed already. A screen dictation user will be able to target based on what content is already visible and not cut off - from there it is part of the design to make sure the most significant part of the target text is visible when overflowing.

[NicholasBoll]

I think it makes sense to assert the contents of the attribute and not just the presence of it. The second parameter is the text that is expected.

[NicholasBoll]

I don't think it is important for the tooltip to have an id at this point. This line should be removed. The id was only used for the aria-describedby.