New Accessibility states API. #24608

marcmulcahy · 2019-04-25T15:05:47Z

Summary

As currently defined, accessibilityStates is an array of strings, which represents the state of an object. The array of strings notion doesn't well encapsulate how various states are related, nor enforce any level of correctness.

This PR converts accessibilityStates to an object with a specific definition. So, rather than:

We have:

And specifically define the checked state to either take a boolean or the "mixed" string (to represent mixed checkboxes).

We feel this API is easier to understand an implement, and provides better semantic definition of the states themselves, and how states are related to one another.

Changelog

[general] [change] - Convert accessibilityStates to an object instead of an array of strings.

Test Plan

Converted code in RNTester to use the new accessibilityStates API, and modified the checkbox example to support the "mixed" state, which was one of the limitations of the current API which prompted this work.

analysis-bot

Code analysis results:

eslint found some issues. Run yarn lint --fix to automatically fix problems.

analysis-bot · 2019-04-25T15:07:07Z

Libraries/Components/Button.js

    if (disabled) {
      buttonStyles.push(styles.buttonDisabled);
      textStyles.push(styles.textDisabled);
-      accessibilityStates.push('disabled');
+      accessibilityStates['enabled'] = false;


dot-notation: ["enabled"] is better written in dot notation.

pull-bot · 2019-04-25T15:07:14Z

	Messages
📖	📋 Verify Changelog Format - A changelog entry has the following format: `[CATEGORY] [TYPE] - Message`. CATEGORY may be: General iOS Android JavaScript Internal (for changes that do not need to be called out in the release notes) TYPE may be: Added, for new features. Changed, for changes in existing functionality. Deprecated, for soon-to-be removed features. Removed, for now removed features. Fixed, for any bug fixes. Security, in case of vulnerabilities. MESSAGE may answer "what and why" on a feature level. Use this to briefly tell React Native users about notable changes.

Generated by 🚫 dangerJS against 780d6f5

necolas · 2019-04-25T17:49:00Z

For context, this is a change I proposed here to provide an API that works for platforms where attributes must be present on host nodes to communicate their purpose to the native accessibility system

necolas

This might need to support but deprecate the old API to give people time to migrate

RNTester/js/AccessibilityExample.js

ReactAndroid/src/main/java/com/facebook/react/uimanager/AccessibilityDelegateUtil.java

marcmulcahy · 2019-04-25T18:17:21Z

@necolas Any thoughts about how to deprecate the older API, while strongly encouraging developers to move to the new one?

necolas · 2019-04-25T18:41:31Z

Any thoughts about how to deprecate the older API, while strongly encouraging developers to move to the new one?

Hopefully someone from RN Core will be able to advise

cpojer · 2019-04-25T20:24:28Z

Ideally we make this a non-breaking change for now by supporting both arrays or objects for a while, then we’ll add a warning in the release after, and then release a codemod (I can help with that) and then remove it.

marcmulcahy · 2019-05-03T22:22:01Z

@cpojer Not sure how to allow the native code to accept both an array of strings as well as an object. Any ideas?

cpojer · 2019-05-07T10:52:09Z

Unfortunately we can't make a breaking change like that in a single pull request. We could wrap <View /> in JS, which would be slow and which we can't do. It seems like the only option here is to introduce a new prop and deprecate the existing one (in a separate PR later) which I don't think we want to do. I'll ask at FB if there are other possibilities but unless we want to introduce a new prop name this may not easily be possible atm.

cpojer · 2019-05-09T10:22:08Z

@marcmulcahy do you have any idea for a new prop that we could introduce so that we could deprecate the existing one? I know this is unfortunate but it seems like the only way. If not, please close this PR.

marcmulcahy · 2019-05-09T16:51:14Z

@cpojer I suppose we could simply add a new prop called something like accessibilityStates2 that's an object instead of an array of strings. Switch all the RNTester samples and components to use accessibilityStates2, and then eventually deprecate accessibilityStates, or rename accessibilityStates2 to accessibilityStates.

I do think this object-based API is much clearer, in that the component author must enumerate the states that "matter", and it makes much clearer how states are related to each other (expanded/collapsed, checked/unchecked, etc.).

I'm also happy to close the PR if this isn't something we want to tackle ATM. Let me know what FB prefers to do.

cpojer · 2019-05-09T17:44:02Z

Alright, yeah I think we can do this. Can you change this PR to do the following:

Add deprecatedAccessibilityStates and make the native code work with that
Make it so accessibilityStates still keeps working exactly the same after your PR lands.

In a month from now (sorry, this is some fb internal issue we have to deal with) we can then change how accessibilityStates works as long as we don't have internal users for it any longer. A month after that we can bring back the accessibilityStates prop with the new API and kill the deprecatedAccessibilityStates API.

I'm sorry for this slow multi process step but I think it's worth doing it if you are up for it :)

cpojer · 2019-05-09T17:46:11Z

Alternatively, if we can think of a better name than accessibilityStates, we can also just add the new prop with a new name and then remove the old one in a month from now. That is way less involved and faster. The process is:

Add a new prop with the new API
I will migrate all internal callsites at FB
Send a PR with the removal for the old accessibilityStates that can be merged in a month from now.

What would be a reasonable name for a new prop?

necolas · 2019-05-09T18:11:20Z

What would be a reasonable name for a new prop?

accessibilityState? Since the value is an object and the name is close enough. And thinking ahead to Marc's other proposal around relationships, that prop could be accessibilityRelationship (no s either).

cpojer · 2019-05-09T18:28:48Z

I think that’s a great idea. Let’s do it!

marcmulcahy · 2019-05-22T02:32:14Z

As we discussed, this version moves the new API to a new property called "accessibilityState" and leaves "accessibilityStates" in tact.

To verify that the existing prop was still working, I applied all the patches which add the new property, and left RNTester unchanged, and verified that RNTester behaves as before on both Android and iOS. I then modified RNTester to use "accessibilityState" instead of "accessibilityStates" and re-tested.

necolas · 2019-05-23T03:02:01Z

Looks good to me

cpojer

That's fantastic. Thank you so much @marcmulcahy and I'm sorry for putting you through so much pain with this one but I really appreciate you were sticking with us :)

I made a few small inline reverts to ensure the current props keep working at FB during the migration phase. Once this PR is landed, do you mind sending a PR that removes accessibilityStates altogether? I can merge that one (in about a month from now) and then we'll be in a good state again :)

…t of strings contained in accessibilityStates with a more semantically rich object.

facebook-github-bot

@cpojer is landing this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

pull-bot · 2019-05-23T08:00:01Z

	Messages
📖	📋 Verify Changelog Format - A changelog entry has the following format: `[CATEGORY] [TYPE] - Message`. CATEGORY may be: General iOS Android JavaScript Internal (for changes that do not need to be called out in the release notes) TYPE may be: Added, for new features. Changed, for changes in existing functionality. Deprecated, for soon-to-be removed features. Removed, for now removed features. Fixed, for any bug fixes. Security, in case of vulnerabilities. MESSAGE may answer "what and why" on a feature level. Use this to briefly tell React Native users about notable changes.

Generated by 🚫 dangerJS against 998faa4

facebook-github-bot

@cpojer has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

react-native-bot · 2019-05-23T12:40:08Z

This pull request was successfully merged by Marc Mulcahy in 099be9b.

^{When will my fix make it into a release? | Upcoming Releases}

Summary: As currently defined, accessibilityStates is an array of strings, which represents the state of an object. The array of strings notion doesn't well encapsulate how various states are related, nor enforce any level of correctness. This PR converts accessibilityStates to an object with a specific definition. So, rather than: <View ... accessibilityStates={['unchecked']}> We have: <View accessibilityStates={{'checked': false}}> And specifically define the checked state to either take a boolean or the "mixed" string (to represent mixed checkboxes). We feel this API is easier to understand an implement, and provides better semantic definition of the states themselves, and how states are related to one another. ## Changelog [general] [change] - Convert accessibilityStates to an object instead of an array of strings. Pull Request resolved: facebook#24608 Differential Revision: D15467980 Pulled By: cpojer fbshipit-source-id: f0414c0ef6add3f10f7f551d323d82d978754278

…4608)

…1144) Summary: This issue fixes #30955 and is a follow up to pr #24608 which added the basic Accessibility functionalities to React Native. TextInput should announce "selected" to the user when screenreader focused. The focus is moved to the TextInput by navigating with the screenreader to the TextInput. This PR adds call to View#setSelected in BaseViewManager https://developer.android.com/reference/android/view/View#setSelected(boolean) The View#setSelected method definition https://github.com/aosp-mirror/platform_frameworks_base/blob/master/core/java/android/view/View.java ```java /** * Changes the selection state of this view. A view can be selected or not. * Note that selection is not the same as focus. Views are typically * selected in the context of an AdapterView like ListView or GridView; * the selected view is the view that is highlighted. * * param selected true if the view must be selected, false otherwise */ public void setSelected(boolean selected) { if (((mPrivateFlags & PFLAG_SELECTED) != 0) != selected) { // ... hidden logic if (selected) { sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_SELECTED); } // ... hidden logic } } ``` VoiceOver and TalkBack was tested with video samples included below. ## Changelog  [Android] [Fixed] - Fix Selected State does not announce when TextInput Component selected on Android Pull Request resolved: #31144 Test Plan: **<details><summary>CLICK TO OPEN TESTS RESULTS</summary>** <p> **ENABLE THE AUDIO** to hear the TalkBack announcing **SELECTED** when the user taps on the TextInput ```javascript <TextInput accessibilityLabel="element 20" accessibilityState={{ selected: true, }} /> ``` | selected is true | |:-------------------------:| | <video src="https://user-images.githubusercontent.com/24992535/111652826-afc4f000-8807-11eb-9c79-8c51d7bf455b.mp4" width="700" height="" /> | ```javascript <TextInput accessibilityLabel="element 20" accessibilityState={{ selected: false, }} /> ``` | selected is false | |:-------------------------:| | <video src="https://user-images.githubusercontent.com/24992535/111652919-c10dfc80-8807-11eb-8244-83db6c327bcd.mp4" width="700" height="" /> | The functionality does not present issues on iOS | iOS testing | |:-------------------------:| | <video src="https://user-images.githubusercontent.com/24992535/111647656-f401c180-8802-11eb-9fa9-a4c211cf1665.mp4" width="400" height="" /> | </p> </details> </p> </details> Reviewed By: blavalla Differential Revision: D27306166 Pulled By: kacieb fbshipit-source-id: 1b3cb37b2d0875cf53f6f1bff4bf095a877b2f0e

marcmulcahy requested a review from shergin as a code owner April 25, 2019 15:05

facebook-github-bot added CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. p: Amazon Partner: Amazon labels Apr 25, 2019

analysis-bot suggested changes Apr 25, 2019

View reviewed changes

marcmulcahy changed the title ~~A11y states api~~ New Accessibility states API. Apr 25, 2019

marcmulcahy mentioned this pull request Apr 25, 2019

Additional Accessibility Roles and States #24095

Closed

necolas reviewed Apr 25, 2019

View reviewed changes

RNTester/js/AccessibilityExample.js Outdated Show resolved Hide resolved

ReactAndroid/src/main/java/com/facebook/react/uimanager/AccessibilityDelegateUtil.java Outdated Show resolved Hide resolved

marcmulcahy force-pushed the a11y-states-api branch from 600eb59 to 44bec03 Compare May 3, 2019 21:34

marcmulcahy force-pushed the a11y-states-api branch from 44bec03 to 3e8420c Compare May 22, 2019 02:27

cpojer approved these changes May 23, 2019

View reviewed changes

Marc Mulcahy added 5 commits May 23, 2019 09:57

Add accessibilityState property which will eventually replace the lis…

032831e

…t of strings contained in accessibilityStates with a more semantically rich object.

Add iOS support for accessibilityState property.

686086c

Add Android support for accessibilityState property.

d3abb5b

Update components to use accessibilityState API.

45758ca

Modify RNTester to use accessibilityState.

97e6e84

cpojer added 5 commits May 23, 2019 09:57

Update Button.js

b263b35

Update TextInput.js

2514052

Update TextInput.js

238298e

Update TouchableWithoutFeedback.js

0a1edd2

Update TouchableWithoutFeedback.js

998faa4

cpojer force-pushed the a11y-states-api branch from 780d6f5 to 998faa4 Compare May 23, 2019 07:57

facebook-github-bot approved these changes May 23, 2019

View reviewed changes

facebook-github-bot reviewed May 23, 2019

View reviewed changes

facebook-github-bot closed this in 099be9b May 23, 2019

react-native-bot added the Merged This PR has been merged. label May 23, 2019

marcmulcahy deleted the a11y-states-api branch May 31, 2019 15:30

ahimberg mentioned this pull request Jul 4, 2019

[react-native] update/add new accessibility properties DefinitelyTyped/DefinitelyTyped#36636

Merged

9 tasks

xuelgong mentioned this pull request Oct 4, 2019

Update accessibility related APIs facebook/react-native-website#1326

Merged

kmelmon mentioned this pull request Feb 6, 2020

Upgrade to 61: View.accessibilityState API change microsoft/react-native-windows#4042

Closed

AKB48 pushed a commit to UnPourTous/react-native that referenced this pull request Apr 21, 2020

099be9b|Facebook Github Bot|New Accessibility states API. (facebook#2…

2863792

…4608)

fabOnReact mentioned this pull request Mar 16, 2021

[Android] Selected State does not annonce when TextInput Component selected #31144

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New Accessibility states API. #24608

New Accessibility states API. #24608

marcmulcahy commented Apr 25, 2019

analysis-bot left a comment

analysis-bot Apr 25, 2019

pull-bot commented Apr 25, 2019 •

edited

necolas commented Apr 25, 2019

necolas left a comment

marcmulcahy commented Apr 25, 2019

necolas commented Apr 25, 2019

cpojer commented Apr 25, 2019

marcmulcahy commented May 3, 2019

cpojer commented May 7, 2019

cpojer commented May 9, 2019

marcmulcahy commented May 9, 2019

cpojer commented May 9, 2019

cpojer commented May 9, 2019

necolas commented May 9, 2019 •

edited

cpojer commented May 9, 2019

marcmulcahy commented May 22, 2019

necolas commented May 23, 2019

cpojer left a comment

facebook-github-bot left a comment

pull-bot commented May 23, 2019

facebook-github-bot left a comment

react-native-bot commented May 23, 2019

New Accessibility states API. #24608

New Accessibility states API. #24608

Conversation

marcmulcahy commented Apr 25, 2019

Summary

Changelog

Test Plan

analysis-bot left a comment

Choose a reason for hiding this comment

analysis-bot Apr 25, 2019

Choose a reason for hiding this comment

pull-bot commented Apr 25, 2019 • edited

necolas commented Apr 25, 2019

necolas left a comment

Choose a reason for hiding this comment

marcmulcahy commented Apr 25, 2019

necolas commented Apr 25, 2019

cpojer commented Apr 25, 2019

marcmulcahy commented May 3, 2019

cpojer commented May 7, 2019

cpojer commented May 9, 2019

marcmulcahy commented May 9, 2019

cpojer commented May 9, 2019

cpojer commented May 9, 2019

necolas commented May 9, 2019 • edited

cpojer commented May 9, 2019

marcmulcahy commented May 22, 2019

necolas commented May 23, 2019

cpojer left a comment

Choose a reason for hiding this comment

facebook-github-bot left a comment

Choose a reason for hiding this comment

pull-bot commented May 23, 2019

facebook-github-bot left a comment

Choose a reason for hiding this comment

react-native-bot commented May 23, 2019

pull-bot commented Apr 25, 2019 •

edited

necolas commented May 9, 2019 •

edited