[docs] Document implementing accessible Popovers

[ArmandRedgate]

Duplicates

• [X] I have searched the existing issues

Latest version

• [X] I have tested the latest version

Steps to reproduce 🕹

Link to live example:

https://codesandbox.io/s/youthful-artem-ycvxvf?file=/src/App.tsx

Steps:

1. Enable screen reader (I used NVDA)
2. Tab over to button
3. Press Enter to open the Popover
4. Popover contents not read

Current behavior 😯

Currently, when you open a Popover, its contents are not read by screen readers.

Expected behavior 🤔

The contents of a Popover should be read by screen readers on open

Context 🔦

I was building a pop-over help modal, but I didn't want a full-screen modal.

Popover seems like it should be the right choice, and it behaves broadly as it should including:

• Opening it focuses its contents
• Pressing Escape from withing closes it
• Pressing tab cycles through only elements within the Popover

However, screen readers do not correctly read its contents. When the dialog is opened, there is no screen reader feedback so you have no idea a dialog was opened or that your focus was moved into it.

I faffed around for over 2 hours trying to figure out why, and in the end I found out that its because the popover has a role of generic rather than dialog. By setting the role to dialog, opening the popover was announced as a dialog and the contents were read.

Your environment 🌎

npx @mui/envinfo

System: OS: Windows 10 10.0.22621 Binaries: Node: 19.4.0 - C:\Program Files\nodejs\node.EXE Yarn: 3.6.0 - C:\Program Files\nodejs\yarn.CMD npm: 9.2.0 - C:\Program Files\nodejs\npm.CMD Browsers: Chrome: Not Found Edge: Spartan (44.22621.1848.0), Chromium (114.0.1823.41) npmPackages: @emotion/react: 11.11.0 @emotion/styled: 11.11.0 @mui/base: 5.0.0-beta.4 @mui/core-downloads-tracker: 5.13.4 @mui/icons-material: 5.11.16 @mui/material: 5.13.4 @mui/private-theming: 5.13.1 @mui/styled-engine: 5.13.2 @mui/system: 5.13.2 @mui/types: 7.2.4 @mui/utils: 5.13.1 @types/react: 18.2.8 react: 18.2.0 react-dom: 18.2.0 typescript: 5.0.4 ``` Don't forget to mention which browser you used. Output from `npx @mui/envinfo` goes here. ```

[ArmandRedgate]

You may or may not want to set role=dialog by default as this may break some existing implementations, but I would strongly advise to at least give some accessibility guidance around using the Popover component.

[michaldudak]

Popover is a lower-level building block, and it may be used for many types of interactions. In this case, it's up to the user to provide the a11y attributes relevant to the implemented use case. Having said that, I agree the docs are lacking in the area and should be updated.

[ArmandRedgate]

Many thanks for responding to this quickly! I figured it might have been intended as a building block.

I agree that users should have some knowledge of accessibility issues.

What concerned me the most is that the following common testing methodologies did not highlight there was an issue:

• Reading the docs
• Looking for warnings or errors
• Testing keyboard navigation
• Using a browser tool such as AXE or WAVE

This was an issue you could only spot if you tried using a screen reader, which only a tiny minority of designers and developers do.

Shocking!

Thanks again for having a look. Updating the docs will definitely help.