Android: Modal announcements

[amarlette]

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 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, '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 component, we do not set this title (RN source here:

react-native/ReactAndroid/src/main/java/com/facebook/react/views/modal/ReactModalHostView.java

Line 265 in 5348a98

mDialog = new Dialog(context, theme);

)

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

[dulmandakh]

Modal is just a container so you can build your own UI. Or you can use third-party ready made modals.

[amarlette]

The intent of this issue is for React Native itself to perform these actions.

[blavalla]

@kacieb, @lunaleaps, @nadiia, do we want RN's dialog to have a way to visibly display a title as well as have one set for accessibility? Right now, it relies on a user passing content into it that will act as a title, but this content is not technically considered a "title" by Android at an OS level, which leads to this problem.

We can set a title only for accessibility, or we could have the option to set a title both visibly and for accessibility. Thoughts?

[kacieb]

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.

I think this component is generic enough that we don't want to render the title for them, though (since you can put anything you want in this modal) - the prop should only be for accessibility. We should be very descriptive about when to use it in our documentation about the prop. The only issue I see with adding a prop only for accessibility is it wouldn't move the focus correctly to the first "non-title" element.

This component could honestly also use a revamp in general, I noticed quite a few deprecated lifecycle methods when looking at it, (and there may be better solutions elsewhere in open source), so I don't think this issue is high priority.

[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.

[fabOnReact]

@blavalla I included an API Proposal in the Draft PR #34969 Thanks

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