microsoft / react-native-windows

A framework for building native Windows apps with React.
https://microsoft.github.io/react-native-windows/
Other
16.13k stars 1.13k forks source link

Add Support for accessibiliyActions #13316

Open chiaramooney opened 1 month ago

chiaramooney commented 1 month ago

Documentation

accessibilityActions Documentation: https://reactnative.dev/docs/accessibility#accessibility-actions

Behavior Explanation

From documentation: "To support accessibility actions, a component must do two things:

Define the list of actions it supports via the accessibilityActions property. Implement an onAccessibilityAction function to handle action requests."

For example a developer will define the following control:

<View
      accessible={true}
      accessibilityActions={[
          { name: 'toggle', label: 'toggle' },
          { name: 'invoke', label: 'invoke' },
          { name: 'expand', label: 'expand' },
          { name: 'collapse', label: 'collapseIt' },
      ]}
      onAccessibilityAction={(event: { nativeEvent: { actionName: any; }; }) => {
          switch (event.nativeEvent.actionName) {
              case 'toggle':
                  console.log('toggle action success');
                  break;
              case 'invoke':
                  console.log('invoke action success');
                  break;
              case 'expand':
                  console.log('expand action success');
                  break;
              case 'collapseIt':
                  console.log('collapseIt action success');
                  break;
          }
      }}
/>

They have defined a set of accessibilityActions they expect to occur for this control, and they have defined an onAccessibilityAction function which should be called after one of the defined accessibilityActions takes place.

On the native side, our platform must store the information that this View control wants to know when Toggle, Invoke, Expand, and Collapse UIA events occur. The native code should monitor when a Toggle, Invoke, Expand, or Collapse UIA event is fired and call the onAccessibilityAction event handler the developer defined with the event information.

Implementation Plan

In our native implementation of accessibilityActions we must:

  1. Store the registered accessibilityActions event names (most likely via CompositionDynamicAutomationProvider)
  2. Store a new AccessibilityActionsEventHandler property with a name parameter
  3. When a UIA action occurs, check the registered accessibilityActions names and if there's a match, then fire the AccessibilityActionsEventHandler

Note this prop will not need to be implemented per component. One implementation in the accessibility source will serve all component types. (i.e. per component issues linked below can all be closed at once after prop behavior is implemented)

Past Implementation

Implementation on Paper: #3475 Issue on Paper: #2765

Notes

Implementing accessibilityActions should not implement our native handling of UIA events. For example, toggling a Switch control when a UIA Toggle event is fired should not be handled by this feature work. That is a separate task. See https://github.com/microsoft/react-native-windows/issues/11903

To Be Clarified

It is unclear in the documentation if specification accessibilityActions and the onAccessibilityAction handler should override default accessibility event behavior. For example, our native code will handle Invoke events for the Button control by calling the controls onPress function. If a developer was to create a Button control and specify the accessibilityActions prop to be { name: 'invoke', label: 'invoke' } and the onAccessibilityAction handler to be

 onAccessibilityAction={(event: { nativeEvent: { actionName: any; }; }) => {
          switch (event.nativeEvent.actionName) {
              case 'invoke':
                  console.log('invoke action success');
                  break;
          }
      }}

should the onAccessibilityAction call replace the default handling of the Invoke event within our native code or be in addition to?

chrisglein commented 1 month ago

@chiaramooney Can you add the right interlinking with these issues: https://github.com/microsoft/react-native-windows/issues?q=is%3Aopen+accessibilityActions