Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal to add accessibility APIs for lists #146

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
75 changes: 75 additions & 0 deletions proposals/0000-accessibilityapis-lists.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
title: Accessibility States and Roles for lists
author:
- Harini Kannan
date: 06/12/2019
---

# RFC0000: Accessibility States and Roles for lists

## Summary

This proposal adds new accessibility roles for supporting lists as well as new APIs for describing size of lists,nth item in the list etc.,

This addresses Issues [2578](https://github.com/microsoft/react-native-windows/issues/2578) and [2579](https://github.com/microsoft/react-native-windows/issues/2579) from react-native-windows. An implementation of the same can be tracked through [this PR](https://github.com/microsoft/react-native-windows/pull/2743).

## Basic example

React Native developers can use these new APIs to describe lists, listitems, size of lists, nth item in the list etc., to assistive technologies using simple code as shown below:

```
<FlatList
data={this.state.listdata}
accessibilityRole="list"
renderItem={({item}) =>
<View accessibilityRole="listItem"
accessibilitySetSize ={this.state.listdata.count}
accessibilityPostInSet={item.id} >
<Text>{item.name}</Text>
</View>
}
</FlatList>
```


## Motivation

It is currently not possible for react-native developers to describe size of lists, nth item in the list etc., With these new APIs, react-native developers can provide more information on lists to assistive technologies which can then be more descriptive of list experiences.

## Detailed design

### P1 APIs:
The following roles will be added to [accessibilityRole](https://facebook.github.io/react-native/docs/accessibility#accessibilityrole-ios-android) APIs:
- **list** Used when element should be treated as a list
- **listitem** Used when element should be treated as a list item

FlatList, SectionList, VirtualizedList components will have `accessibilityRole = list` set by default.

### P2 APIs:
The following new properties will be introduced to customize and describe details of the list/list items:
- **accessibilitysetsize**
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As props these would still be camelcase: accessibilitySetSize

- **accessibilityposinset**

In keeping with the ARIA equivalents like [aria-setSize](https://accessibilityresources.org/aria-setsize) and [aria-posInSet](https://accessibilityresources.org/aria-posinset), these properties are marked on the members of a set, not the container element that collects the members of the set. When set, assistive technologies will call out "item X out of Y," when a member of a set with this property has accessibility focus. The assistive technologies would use X equal to the `acessibilityPosInSet` attribute and Y equal to the `accessibilitySetSize` attribute.

These properties should be used in conjunction with each other.

## Drawbacks

FlatList tries to be a simple building block component and hence adding a lot of functionality to it can make it more complex. However, the APIs we are adding are ARIA based and have equivalents in all platforms. However, Lists are also some of the most common experiences in any app and hence the small amount of complexity this adds feels warranted.

Given the nature of FlatList, SectionList in React Native where there are no actual collections/items that the list itself maybe aware of, it is not possible to provide good default behaviors for the item specific APIs in this proposal and it is up to each developer to set these values for the right behaviors.

## Adoption strategy

These APIs all have existing equivalents in ARIA, UIA and other native accessibility APIs. The naming of these has been matched to existing ARIA equivalents and hence will be familiar to React/Web developers.

For Windows developers, these should be familiar as well - the UIA properties that describe these for accessibility tools are [PositionInSet](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.Automation.AutomationProperties.PositionInSetProperty) and [SizeOfSet](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.Automation.AutomationProperties.SizeOfSetProperty)

## How we teach this

We should add these to the existing [Accessibility documentation](https://facebook.github.io/react-native/docs/accessibility) in react-native.

## Unresolved questions

Can these values be set on any component?