Android: Modal announcements

Requires API Proposal

This issue may require a new API, or a change to an existing API. An API proposal should be added and discussed before proceeding with implementation. The API proposal can be added in the comments of this issue or linked as a separate issue.

Description

On Android, when new Windows appear, their title is announced. If no title is set, it will treat the first visible item as a title, and instead announce it, moving focus automatically to the second element. This is not always desired, so we should provide a way to set a specific title to be announced instead.

This issue specifically applies to the <Modal> component (https://reactnative.dev/docs/modal), which does not have a way to specify a title. Other Window types, such as Alert’s, work correctly as their only content is treated as the title.

React Native version:

v0.63

Expected Behavior

Upon appearance, <Modal>'s should announce a specified title, and focus should move into them, landing on the first visible element. If no title is specified, the existing behavior should apply, which treats the first visible element as the title, with focus moving to the second visible element.

Android Details

In Android Windows such as “Dialog” have the ability to set a title via a “setTitle()” method (https://developer.android.com/reference/android/app/Dialog#setTitle(java.lang.CharSequence)).

In React Native, when we create a new Dialog for the <Modal> component, we do not set this title (RN source here: https://github.com/facebook/react-native/blob/5348a98207dcff1686b2964d51572c3b226663ab/ReactAndroid/src/main/java/com/facebook/react/views/modal/ReactModalHostView.java#L265)

We need to set this title for the accessibility system to pick it up.

If you want the title to only be picked up by the accessibility system, but not visible displayed, you only need to set the title on the Window attributes, which you should be able to do by calling dialog.getWindow().getAttributes().setTitle("my title"). This is exactly what happens when you call setTitle() on the Dialog itself in the Android source. Android source here: https://cs.android.com/android/platform/superproject/+/master:frameworks/base/core/java/android/app/Dialog.java;l=611

[blavalla]

Just wanted to check - it sounds like “title” is different from “accessibilityLabel” (or contentDescription on Android)? It seems reasonable to me to add a new prop to Modal to allow people to pass in a title for accessibility purposes. This would require both Android and iOS work.

Yeah, on Android a Window (which a dialog is) doesn’t have the normal View properties like contentDescription, etc. A title is meant to be visibly displayed at the top of the Window and used to let the user know what the purpose of this window is. When one is set Talkback is also smart enough to know to announce this when the window first appears, and not to focus on it directly. It’s not a property meant specifically for accessibility though, but there are implications if one isn’t set, as Talkback will still read something when the Window appears, but since it’s not something we define, the behavior may not be what a developer expects.

As a fun aside, the same general rule applies to activities on Android, which can also have titles set, but if you don’t set them, it will just read your apps name instead of trying to find a title in the content. If you’ve used the an app and heard Talkback say the app name over and over whenever you open some new screen, it probably means you forgot to add an activity title.

[fabriziobertoglio1987]

@blavalla I included an API Proposal in the Draft PR https://github.com/facebook/react-native/pull/34969 Thanks

Video of the Functionality on Android https://www.icloud.com/iclouddrive/0fdBl7MCKgQ3d0vMeRR-DDVuA#modal_title_android