iOS/Android: Text input error for screenreaders

[amarlette]

Requires API Proposal

This issue requires a new 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

Cannot specify error text on TextInputs. Errors for form fields, while they can be displayed visually in many unique ways, need to have a strong association with the problematic field itself for accessibility. Otherwise, any users who can't visually see the relation of the error to the field won't necessarily know which field is the problem.

React Native version:

v0.63

Expected Results

Upon focus of a text input in an error state, the error message specified should announced after the main focus announcement, prefixed with "Error: ". Upon changing the contents of a text input which puts the input into an error state, an error message should be announced prefixed with "Error: ".

Snack

https://snack.expo.io/X4NIqnJ2K

Android Details

To implement error states on Android, you should call the setError method of the TextView. This will automatically set the correct properties on the AccessibilityNodeInfo that will inform screen readers to this state. If you need to do this manually, what this does behind the scenes is call setContentInvalid(true) and setError(youErrorString) on the AccessibilityNodeInfo.

iOS Details

iOS has no standard pattern for the presentation of error states on text inputs, so I'd recommend we follow Android's pattern here. To do this, you'll need to implement a key press listener, and on change, detect if the field is now in an error state. If it is, you'll need to make a manual screen reader announcement of the error message, and append this message to the accessibilityValue for the field.

[kacieb]

API Proposal:

This will require adding a new prop to JS, and Android and iOS changes to use that prop.

JS

Add a new prop to TextInput:

  /**
   * String to be read by screenreaders to indicate an error state. If this value is
   * not null, an error will be announced. You can use onChangeText or onBlur to 
   * detect an error and set this prop. Once the error is gone, set this to null
   * to clear the error
   */
  errorMessage?: ?Stringish,

Example usage:
In this example, the TextInput goes into an error state if the user types "error" into the TextInput.

export default function Playground(): React.Node {
  const [text, setText] = React.useState('');
  const [error, setError] = React.useState(null);
  return (
    <TextInput
      error={error}
      onChangeText={newText => {
        setText(newText);
        setError(newText === 'error' ? 'this input is invalid' : null);
      }}
      value={text}
    />
  );
}

Note: onChangeText may not be the right place to announce the error. This API gives flexibility to set the error when needed. Another place might be onBlur, which is when the TextInput loses focus.

Implementation Thoughts

On Android, implementation will follow the suggestions in the issue. To avoid visual styling, we will call setContentInvalid(true) and setError(youErrorString) on the AccessibilityNodeInfo manually.

On iOS, since there is no way to do this sanctioned by Apple, we'll follow the recommended approach listed in the issue. The behavior will be as similar to Android as possible.