Skip to content

Commit

Permalink
fix(overlay): hide from screen readers while animating (#29951)
Browse files Browse the repository at this point in the history
Issue number: resolves #29857 

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

Screen readers like Android Talkback would not have the focus ring on
the correct element. For example, Talkback would announce the buttons
correctly within action sheet but the focus ring was no where to be
seen.

After digging around, the focus rings are located out of screen because
the action sheet is mounted to the DOM out of the screen first then
transitions into the screen. There are some screen readers that do not
behave as expected when an element uses `transform` styles like action
sheet.


https://github.com/user-attachments/assets/5a700bcc-3149-47a9-96ff-0aef99dd2bb3

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- When an overlay is being animated (presenting or dismissing), the
overlay will hide from screen readers. This allows the element to
navigate to its correct destination for screen readers to interact with.
Plus, we shouldn't allow screen readers to interact with content in the
middle of an animation. It could lead to some confusion.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

Dev build: 8.3.3-dev.11729276019.194c165c

**A physical Android device will be needed, the issue does not appear in
simulators**

Components that need to be tested because they use overlays:
- Action sheet
- Alert
- Loading
- Modal
- Popover
- Select w/ action sheet interface
- Select w/ alert interface
- Select w/ popover interface
- Toast

How to test:
1. Create a starter app (any framework will do)
2. Add an action sheet
3. Build app for mobile devices
```
ionic build

ionic cap add ios
ionic cap add android

ionic cap copy && ionic cap sync
```
4. Open the app in Android Studio: `ionic cap open android`
5. Connect the Android device to Android Studio
6. Open app in Android device
7. Launch Talkback
8. Navigate back to the app
9. Open action sheet 
10. Swipe over to the action sheet's buttons
11. Notice that the buttons don't have a focus ring
12. Go back to the starter
4. Install the dev build
5. Add the components to the app
6. Sync app: `ionic cap copy && ionic cap sync`
13. Relaunch the app on the Android device
14. Verify that the focus ring appears on the action sheet's buttons
15. Verify that the other overlays are working as intended
  • Loading branch information
thetaPC authored Oct 24, 2024
1 parent e32fbe0 commit cb60073
Showing 1 changed file with 38 additions and 2 deletions.
40 changes: 38 additions & 2 deletions core/src/utils/overlays.ts
Original file line number Diff line number Diff line change
Expand Up @@ -514,7 +514,8 @@ export const present = async <OverlayPresentOptions>(

document.body.classList.add(BACKDROP_NO_SCROLL);

hideOverlaysFromScreenReaders(overlay.el);
hideUnderlyingOverlaysFromScreenReaders(overlay.el);
hideAnimatingOverlayFromScreenReaders(overlay.el);

overlay.presented = true;
overlay.willPresent.emit();
Expand Down Expand Up @@ -560,6 +561,11 @@ export const present = async <OverlayPresentOptions>(
* it would still have aria-hidden on being presented again.
* Removing it here ensures the overlay is visible to screen
* readers.
*
* If this overlay was being presented, then it was hidden
* from screen readers during the animation. Now that the
* animation is complete, we can reveal the overlay to
* screen readers.
*/
overlay.el.removeAttribute('aria-hidden');
};
Expand Down Expand Up @@ -644,6 +650,13 @@ export const dismiss = async <OverlayDismissOptions>(
overlay.presented = false;

try {
/**
* There is no need to show the overlay to screen readers during
* the dismiss animation. This is because the overlay will be removed
* from the DOM after the animation is complete.
*/
hideAnimatingOverlayFromScreenReaders(overlay.el);

// Overlay contents should not be clickable during dismiss
overlay.el.style.setProperty('pointer-events', 'none');
overlay.willDismiss.emit({ data, role });
Expand Down Expand Up @@ -929,6 +942,29 @@ export const createTriggerController = () => {
};
};

/**
* The overlay that is being animated also needs to hide from screen
* readers during its animation. This ensures that assistive technologies
* like TalkBack do not announce or interact with the content until the
* animation is complete, avoiding confusion for users.
*
* If the overlay is being presented, it prevents focus rings from appearing
* in incorrect positions due to the transition (specifically `transform`
* styles), ensuring that when aria-hidden is removed, the focus rings are
* correctly displayed in the final location of the elements.
*
* @param overlay - The overlay that is being animated.
*/
const hideAnimatingOverlayFromScreenReaders = (overlay: HTMLIonOverlayElement) => {
if (doc === undefined) return;

/**
* Once the animation is complete, this attribute will be removed.
* This is done at the end of the `present` method.
*/
overlay.setAttribute('aria-hidden', 'true');
};

/**
* Ensure that underlying overlays have aria-hidden if necessary so that screen readers
* cannot move focus to these elements. Note that we cannot rely on focus/focusin/focusout
Expand All @@ -939,7 +975,7 @@ export const createTriggerController = () => {
* @param newTopMostOverlay - The overlay that is being presented. Since the overlay has not been
* fully presented yet at the time this function is called it will not be included in the getPresentedOverlays result.
*/
const hideOverlaysFromScreenReaders = (newTopMostOverlay: HTMLIonOverlayElement) => {
const hideUnderlyingOverlaysFromScreenReaders = (newTopMostOverlay: HTMLIonOverlayElement) => {
if (doc === undefined) return;

const overlays = getPresentedOverlays(doc);
Expand Down

0 comments on commit cb60073

Please sign in to comment.