Update accessibility related APIs (facebook#1326)

* Update accessibility related APIs * Add accessibilityValue prop to Touchable * Modify the accessibilityValue prop description * Using 'clear' instead of obvious * Update touchablewithoutfeedback.md Using 'clear' instead of obvious * Moving more content into tables and reducing h-tag hierarchy * Retooling opening paragraph and meta-description * Tweaking intro copy
MLH-Fellowship · Nov 6, 2019 · 3b962a6 · 3b962a6
1 parent 0c99ba3
commit 3b962a6
Show file tree

Hide file tree

Showing 7 changed files with 681 additions and 502 deletions.
diff --git a/docs/accessibility.md b/docs/accessibility.md
@@ -1,19 +1,17 @@
 ---
 id: accessibility
 title: Accessibility
----
-
-## Native App Accessibility (iOS and Android)
+description: "Create mobile apps accessible to assistive technology with React Native's suite of APIs designed to work with iOS and Android."
 
-Both iOS and Android provide APIs for making apps accessible to people with disabilities. In addition, both platforms provide bundled assistive technologies, like the screen readers VoiceOver (iOS) and TalkBack (Android) for the visually impaired. Similarly, in React Native we have included APIs designed to provide developers with support for making apps more accessible. Take note, iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
+---
 
-In addition to this documentation, you might find [this blog post](https://engineering.fb.com/ios/making-react-native-apps-accessible/) about React Native accessibility to be useful.
+Both iOS and Android provide APIs for integrating apps with assitive technologies like the bundled screen readers VoiceOver (iOS) and Talkback (Android). React Native has complimentary APIs that let your app accommodate all users. 
 
-## Making Apps Accessible
+> iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
 
-### Accessibility properties
+## Accessibility properties
 
-#### accessible (iOS, Android)
+### accessible (iOS, Android)
 
 When `true`, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component. By default, all touchable elements are accessible.
 
@@ -28,7 +26,7 @@ On Android, `accessible={true}` property for a react-native View will be transla
 
 In the above example, we can't get accessibility focus separately on 'text one' and 'text two'. Instead we get focus on a parent view with 'accessible' property.
 
-#### accessibilityLabel (iOS, Android)
+### accessibilityLabel (iOS, Android)
 
 When a view is marked as accessible, it is a good practice to set an accessibilityLabel on the view, so that people who use VoiceOver know what element they have selected. VoiceOver will read this string when a user selects the associated element.
 
@@ -47,7 +45,7 @@ To use, set the `accessibilityLabel` property to a custom string on your View, T
 
 In the above example, the `accessibilityLabel` on the TouchableOpacity element would default to "Press me!". The label is constructed by concatenating all Text node children separated by spaces.
 
-#### accessibilityHint (iOS, Android)
+### accessibilityHint (iOS, Android)
 
 An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.
 
@@ -69,11 +67,11 @@ iOS In the above example, VoiceOver will read the hint after the label, if the u
 
 Android In the above example, Talkback will read the hint after the label. At this time, hints cannot be turned off on Android.
 
-#### accessibilityIgnoresInvertColors(iOS)
+### accessibilityIgnoresInvertColors(iOS)
 
 Inverting screen colors is an Accessibility feature that makes the iPhone and iPad easier on the eyes for some people with a sensitivity to brightness, easier to distinguish for some people with color blindness, and easier to make out for some people with low vision. However, sometimes you have views such as photos that you don't want to be inverted. In this case, you can set this property to be false so that these specific views won't have their colors inverted.
 
-#### accessibilityRole (iOS, Android)
+### accessibilityRole (iOS, Android)
 
 `accessibilityRole` communicates the purpose of a component to the user of an assistive technology.
 
@@ -107,47 +105,60 @@ Inverting screen colors is an Accessibility feature that makes the iPhone and iP
 - **timer** Used to represent a timer.
 - **toolbar** Used to represent a tool bar (a container of action buttons or components).
 
-#### accessibilityStates (iOS, Android)
+### accessibilityState (iOS, Android)
 
 Describes the current state of a component to the user of an assistive technology.
 
-`accessibilityStates` is an array of values, and may include any of the following:
+`accessibilityState` is an object. It contains the following fields:
+
+| Name     |  Description | Type               | Required |
+| -------- | ------------ | ------------------ | -------- |
+| disabled | Indicates whether the element is disabled or not. | boolean            | No       |
+| selected | Indicates whether a selectable element is currently selected or not. | boolean            | No       |
+| checked  | Indicates the state of a checkable element. This field can either take a boolean or the "mixed" string to represent mixed checkboxes. | boolean or 'mixed' | No       |
+| busy     | Indicates whether an element is currently busy or not. | boolean            | No       |
+| expanded | Indicates whether an expandable element is currently expanded or collapsed. | boolean            | No       |
+
+To use, set the `accessibilityState` to an object with a specific definition.
+
+### accessibilityValue (iOS, Android)
+
+Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).
 
-- **selected** Used when the element is in a selected state. For example, a button is selected.
-- **disabled** Used when the element is disabled and cannot be interacted with.
-- **checked** Used to indicate that a checkable element is currently checked.
-- **unchecked** Used to indicate that a checkable element is not currently checked.
-- **busy** Used to indicate that an element is currently busy.
-- **expanded** Used to indicate that an expandable element is currently expanded.
-- **collapsed** Used to indicate that an expandable element is currently collapsed.
+`accessibilityValue` is an object. It contains the following fields:
 
-To use, set the `accessibilityStates` to an array containing the list of current states.
+| Name | Description                                                                                    | Type    | Required                  |
+| ---- | ---------------------------------------------------------------------------------------------- | ------- | ------------------------- |
+| min  | The minimum value of this component's range.                                                   | integer | Required if `now` is set. |
+| max  | The maximum value of this component's range.                                                   | integer | Required if `now` is set. |
+| now  | The current value of this component's range.                                                   | integer | No                        |
+| text | A textual description of this component's value. Will override `min`, `now`, and `max` if set. | string  | No                        |
 
-#### accessibilityViewIsModal (iOS)
+### accessibilityViewIsModal (iOS)
 
 A Boolean value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver.
 
 For example, in a window that contains sibling views `A` and `B`, setting `accessibilityViewIsModal` to `true` on view `B` causes VoiceOver to ignore the elements in the view `A`. On the other hand, if view `B` contains a child view `C` and you set `accessibilityViewIsModal` to `true` on view `C`, VoiceOver does not ignore the elements in view `A`.
 
-#### accessibilityElementsHidden (iOS)
+### accessibilityElementsHidden (iOS)
 
 A Boolean value indicating whether the accessibility elements contained within this accessibility element are hidden.
 
 For example, in a window that contains sibling views `A` and `B`, setting `accessibilityElementsHidden` to `true` on view `B` causes VoiceOver to ignore the elements in the view `B`. This is similar to the Android property `importantForAccessibility="no-hide-descendants"`.
 
-#### onAccessibilityTap (iOS)
+### onAccessibilityTap (iOS, Android)
 
 Use this property to assign a custom function to be called when someone activates an accessible element by double tapping on it while it's selected.
 
-#### onMagicTap (iOS)
+### onMagicTap (iOS)
 
 Assign this property to a custom function which will be called when someone performs the "magic tap" gesture, which is a double-tap with two fingers. A magic tap function should perform the most relevant action a user could take on a component. In the Phone app on iPhone, a magic tap answers a phone call, or ends the current one. If the selected element does not have an `onMagicTap` function, the system will traverse up the view hierarchy until it finds a view that does.
 
-#### onAccessibilityEscape (iOS)
+### onAccessibilityEscape (iOS)
 
 Assign this property to a custom function which will be called when someone performs the "escape" gesture, which is a two finger Z shaped gesture. An escape function should move back hierarchically in the user interface. This can mean moving up or back in a navigation hierarchy or dismissing a modal user interface. If the selected element does not have an `onAccessibilityEscape` function, the system will attempt to traverse up the view hierarchy until it finds a view that does or bonk to indicate it was unable to find one.
 
-#### accessibilityLiveRegion (Android)
+### accessibilityLiveRegion (Android)
 
 When components dynamically change, we want TalkBack to alert the end user. This is made possible by the ‘accessibilityLiveRegion’ property. It can be set to ‘none’, ‘polite’ and ‘assertive’:
 
@@ -168,7 +179,7 @@ When components dynamically change, we want TalkBack to alert the end user. This
 
 In the above example method \_addOne changes the state.count variable. As soon as an end user clicks the TouchableWithoutFeedback, TalkBack reads text in the Text view because of its 'accessibilityLiveRegion=”polite”' property.
 
-#### importantForAccessibility (Android)
+### importantForAccessibility (Android)
 
 In the case of two overlapping UI components with the same parent, default accessibility focus can have unpredictable behavior. The ‘importantForAccessibility’ property will resolve this by controlling if a view fires accessibility events and if it is reported to accessibility services. It can be set to ‘auto’, ‘yes’, ‘no’ and ‘no-hide-descendants’ (the last value will force accessibility services to ignore the component and all of its children).
 
@@ -187,7 +198,7 @@ In the case of two overlapping UI components with the same parent, default acces
 
 In the above example, the yellow layout and its descendants are completely invisible to TalkBack and all other accessibility services. So we can use overlapping views with the same parent without confusing TalkBack.
 
-### Accessibility Actions
+## Accessibility Actions
 
 Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. In order to support accessibility actions, a component must do two things:
 
@@ -240,39 +251,25 @@ To handle action requests, a component must implement an `onAccessibilityAction`
 />
 ```
 
-### Checking if a Screen Reader is Enabled
+## Checking if a Screen Reader is Enabled
 
 The `AccessibilityInfo` API allows you to determine whether or not a screen reader is currently active. See the [AccessibilityInfo documentation](accessibilityinfo.md) for details.
 
-### Sending Accessibility Events (Android)
+## Sending Accessibility Events (Android)
 
-Sometimes it is useful to trigger an accessibility event on a UI component (i.e. when a custom view appears on a screen or a custom radio button has been selected). Native UIManager module exposes a method ‘sendAccessibilityEvent’ for this purpose. It takes two arguments: view tag and a type of an event.
+Sometimes it is useful to trigger an accessibility event on a UI component (i.e. when a custom view appears on a screen or set accessibility focus to a view). Native UIManager module exposes a method ‘sendAccessibilityEvent’ for this purpose. It takes two arguments: view tag and a type of an event. The supported event types are `typeWindowStateChanged`, `typeViewFocused` and `typeViewClicked`.
 
 ```jsx
-import { UIManager, findNodeHandle } from 'react-native';
+import { Platform, UIManager, findNodeHandle } from 'react-native';
 
-_onPress: function() {
-  const radioButton = this.state.radioButton === 'radiobutton_checked' ?
-    'radiobutton_unchecked' : 'radiobutton_checked'
-
-  this.setState({
-    radioButton: radioButton
-  });
-
-  if (radioButton === 'radiobutton_checked') {
+if (Platform.OS === 'android') {
     UIManager.sendAccessibilityEvent(
       findNodeHandle(this),
-      UIManager.AccessibilityEventTypes.typeViewClicked);
+      UIManager.AccessibilityEventTypes.typeViewFocused);
   }
 }
-
-<CustomRadioButton
-  accessibilityComponentType={this.state.radioButton}
-  onPress={this._onPress}/>
 ```
 
-In the above example we've created a custom radio button that now behaves like a native one. More specifically, TalkBack now correctly announces changes to the radio button selection.
-
 ## Testing VoiceOver Support (iOS)
 
 To enable VoiceOver, go to the Settings app on your iOS device (it's not available for simulator). Tap General, then Accessibility. There you will find many tools that people use to make their devices more usable, such as bolder text, increased contrast, and VoiceOver.
@@ -303,3 +300,7 @@ adb shell settings put secure enabled_accessibility_services com.android.talkbac
 # enable
 adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService
 ```
+
+## Additional Resources
+
+* [Making React Native Apps Accessible](https://engineering.fb.com/ios/making-react-native-apps-accessible/)
diff --git a/docs/touchablewithoutfeedback.md b/docs/touchablewithoutfeedback.md
@@ -37,6 +37,26 @@ function MyComponent(props) {
 
 ---
 
+### `accessible`
+
+When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.
+
+| Type | Required |
+| ---- | -------- |
+| bool | No       |
+
+---
+
+### `accessibilityLabel`
+
+Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space.
+
+| Type   | Required |
+| ------ | -------- |
+| string | No       |
+
+---
+
 ### `accessibilityHint`
 
 An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.
@@ -47,45 +67,91 @@ An accessibility hint helps users understand what will happen when they perform
 
 ---
 
-### `accessibilityLabel`
+### `accessibilityRole`
 
-Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space.
+`accessibilityRole` communicates the purpose of a component to the user of an assistive technology.
+
+`accessibilityRole` can be one of the following:
+
+- `'none'` - Used when the element has no role.
+- `'button'` - Used when the element should be treated as a button.
+- `'link'` - Used when the element should be treated as a link.
+- `'search'` - Used when the text field element should also be treated as a search field.
+- `'image'` - Used when the element should be treated as an image. Can be combined with button or link, for example.
+- `'keyboardkey'` - Used when the element acts as a keyboard key.
+- `'text'` - Used when the element should be treated as static text that cannot change.
+- `'adjustable'` - Used when an element can be "adjusted" (e.g. a slider).
+- `'imagebutton'` - Used when the element should be treated as a button and is also an image.
+- `'header'` - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
+- `'summary'` - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
+- `'alert'` - Used when an element contains important text to be presented to the user.
+- `'checkbox'` - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
+- `'combobox'` - Used when an element represents a combo box, which allows the user to select among several choices.
+- `'menu'` - Used when the component is a menu of choices.
+- `'menubar'` - Used when a component is a container of multiple menus.
+- `'menuitem'` - Used to represent an item within a menu.
+- `'progressbar'` - Used to represent a component which indicates progress of a task.
+- `'radio'` - Used to represent a radio button.
+- `'radiogroup'` - Used to represent a group of radio buttons.
+- `'scrollbar'` - Used to represent a scroll bar.
+- `'spinbutton'` - Used to represent a button which opens a list of choices.
+- `'switch'` - Used to represent a switch which can be turned on and off.
+- `'tab'` - Used to represent a tab.
+- `'tablist'` - Used to represent a list of tabs.
+- `'timer'` - Used to represent a timer.
+- `'toolbar'` - Used to represent a tool bar (a container of action buttons or components).
 
 | Type   | Required |
 | ------ | -------- |
 | string | No       |
 
 ---
 
-### `accessibilityRole`
+### `accessibilityState`
 
-| Type               | Required |
-| ------------------ | -------- |
-| AccessibilityRoles | No       |
+Describes the current state of a component to the user of an assistive technology.
+
+See the [Accessibility guide](accessibility.md#accessibilitystate-ios-android) for more information.
+
+| Type                                                                                           | Required |
+| ---------------------------------------------------------------------------------------------- | -------- |
+| object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool} | No       |
 
 ---
 
-### `accessibilityStates`
+### `accessibilityActions`
+
+Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The `accessibilityActions` property should contain a list of action objects. Each action object should contain the field name and label.
 
-| Type                         | Required |
-| ---------------------------- | -------- |
-| array of AccessibilityStates | No       |
+See the [Accessibility guide](accessibility.md#accessibility-actions) for more information.
+
+| Type  | Required |
+| ----- | -------- |
+| array | No       |
 
 ---
 
-### `accessibilityState`
+### `onAccessibilityAction`
 
-| Type   | Required |
-| ------ | -------- |
-| Object | No       |
+Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.
+
+See the [Accessibility guide](accessibility.md#accessibility-actions) for more information.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
 
 ---
 
-### `accessible`
+### `accessibilityValue`
 
-| Type | Required |
-| ---- | -------- |
-| bool | No       |
+Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).
+
+See the [Accessibility guide](accessibility.md#accessibilityvalue-ios-android) for more information.
+
+| Type                                                          | Required |
+| ------------------------------------------------------------- | -------- |
+| object: {min: number, max: number, now: number, text: string} | No       |
 
 ---