[docs] Document implementing accessible Popovers

Duplicates

• I have searched the existing issues

Latest version

• 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 🌎

Start with the linked CodeSandbox at src/App.tsx and review the Popover accessibility behavior described in the issue. Document how to implement an accessible Popover, including the screen-reader announcement and dialog role behavior. Done means the guidance addresses the reported screen-reader problem and is added to the appropriate documentation location.