Investigate focus management issues with modal

[dougmacknz]

This was definitely working in the past, but looks like it was regressed in #1301. See #1593 also for a fix for a regression caused by the same work.

Audit info

Type:WCAG 2
Principle: Operable
Guideline:2.4 Navigable
Success Criteria: 2.4.3 Focus Order (A)
Level: A
Platform: Web
Severity:High

What's the issue?

Focus is not set in the modal when the Add Comment modals open.

Why it matters

If focus is not set inside the modal when it opens:

• keyboard users will not be able to interact with the modal content.
• screen reader users are unable to access the modal content and will not know that it is there.

Our recommendation
When the modal opens, set focus on the modal container.

• At the start of the modal, add screen reader only text that says "Start of dialog". Give the text a unique ID and add tabindex="-1" to it.
• Give the modal an informative heading marked up as an <h1>. Give the <h1> a unique ID.
• Add aria-labelledby to the modal container and reference the ID of the screen reader text and the <h1>.
• Add tabindex="-1" to the modal container. When the modal opens set focus on the modal container.
• A screen reader user will hear the "Start of dialog" followed by the heading when the modal opens, and can then go on to navigate its contents in sequence.

Trap focus inside of the modal while the modal is open.

• Structure the code so that the modal is separate to the page content. Wrap the page content in a generic container element such as a div.
• Apply aria-hidden="true" to the page content container to hide it (and all of its children) from screen readers.
• Apply tabindex="-1" to each interactive element within the page content container to remove them from the tab order so that only modal content remains focusable.

When the modal is closed return focus to the control that opened the modal.

Note: We don't recommend using role="dialog" as some screen readers will read the entire modal contents when the role is present.

See the Intopia Codepen for Accessible Dialog for working example.