Fix ContextualMenuItemButton's secondary text never read by screen-reader

[KevinTCoughlin]

Pull request checklist

• Addresses an existing issue: Fixes #0000
• Include a change request file using $ npm run change

Description of changes

Overview

We received an accessibility report in #6360:

Bug 5 : [Accessibility][Screen reader]: Secondary text is not announced when user navigates in context menu under ContextualMenu with icons and secondary text.

After debugging, I found that this is because we set an aria-label on ContextualMenuButton equal to either props.ariaLabel or item.text || item.name || ''. The item's secondary text is never included in that aria-label as item.secondaryText and therefore never read.

The Change

Initially, I thought the fix was to either conditionally concatenate primary and secondary text to produce aria-label or replace aria-label with aria-labelledby referencing both primary and secondary text nodes via unique IDs. The spec recommends aria-labelledby for multiple nodes with text visible.

Characteristic	Value
Related Concepts:	A related concept is label in XForms [XForms] and HTML [HTML].
Used in Roles:	All elements of the base markup
Value:	ID reference list

However, I found that I could remove the usage of aria-label completely (unless specified by the user via props) and the bug was fixed. Both primary and secondary text were then announced by Narrator because they are present in the DOM as child text nodes. See Narrator Buddy Output.

Conclusion

I'm recommending this change, because it seems to be backwards compatible for devs that are already supplying their own ariaLabel or relying on text contents item.text or item.name be read by assistive technology.

I believe that the most likely usage of ariaLabel in a ContextualMenuItemButton is when the item's text is unclear such as "X". In this case, the existing code's default value will be "X" for aria-label and not any more useful. This would require a developer to supply their own ariaLabel value anyway.

Narrator Buddy Output

Before

Default ContextualMenu Example

Office UI Fabric React Examples - Microsoft Edge window, Office UI Fabric React Examples, menu, 
New, menu item,
Rename, menu item,
Edit, menu item,
Properties, menu item,
Link same window, menu item,
Tooltip, http://bing.com/.
Link new window, menu item,
Link click, menu item,

ContextualMenu w/ Secondary Text Example

Office UI Fabric React Examples - Microsoft Edge window, Office UI Fabric React Examples, menu, 
Later Today, menu item,
Tomorrow, menu item,
This Weekend, menu item,
Next Week, menu item,

After

Default ContextualMenu Example

Office UI Fabric React Examples - Microsoft Edge window, Office UI Fabric React Examples, menu, 
New, menu item,
Rename, menu item,
Edit, menu item,
Properties, menu item,
Link same window, menu item,
Tooltip, http://bing.com/.
Link new window, menu item,
Link click, menu item,

ContextualMenu w/ Secondary Text Example

Office UI Fabric React Examples - Microsoft Edge window, Office UI Fabric React Examples, menu, 
Later Today 7:00 PM, menu item,
Tomorrow Thu. 8:00 AM, menu item,
This Weekend Sat. 10:00 AM, menu item,
Next Week Mon. 8:00 AM, menu item,

Focus areas to test

1. Navigate to the ContextualMenu examples page
2. Enable Narrator
3. Open the various ContextualMenus on the page, each item should have its text read aloud.
4. Open the ContextualMenu example with secondary text.
5. Narrator should read the primary and secondary text of each button that is focused within the menu.

References

• https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-labelledby

Microsoft Reviewers: Open in CodeFlow

[KevinTCoughlin]

Note to self to look at screenshot / unit test coverage here. It may already exist, but I want to make sure we don't regress this.

[KevinTCoughlin]

Might also be worth mentioning that a workaround exists in master. A dev could provide ariaLabel: item.text + ' ' + item.secondaryText per item.

[KevinTCoughlin]

Added some unit tests in an attempt to give us some coverage with a link to this PR for context.

Unit tests added:

• ContextualMenuItem renders secondary text if provided
• ContextualMenuItem's aria-label is undefined by default
• ContextualMenuItem's aria-label can be overridden via props

I couldn't find existing tests for the above scenarios. Let me know if I missed them, happy to not have dupes.

[msft-github-bot]

🎉office-ui-fabric-react@v6.84.1 has been released which incorporates this pull request.:tada:

Handy Links:

• Release Notes
• Official NPM Release
• Test the release with Developer Demo Site