From 4f7e184c4774c366599d71ca62ea55b836886b61 Mon Sep 17 00:00:00 2001 From: JDMathew Date: Mon, 5 Aug 2024 13:36:17 -0700 Subject: [PATCH 1/4] Add StaticFlatList doc --- packages/lists/docs/StaticFlatList.mdx | 49 ++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 packages/lists/docs/StaticFlatList.mdx diff --git a/packages/lists/docs/StaticFlatList.mdx b/packages/lists/docs/StaticFlatList.mdx new file mode 100644 index 00000000..59824a3d --- /dev/null +++ b/packages/lists/docs/StaticFlatList.mdx @@ -0,0 +1,49 @@ +import { TalkBackList } from '@site/src/components'; + +# StaticFlatList + +StaticFlatList extends the React Native FlatList component [focused on accessibility]. + +## Usage + +```jsx +import { StaticFlatList } from '@react-native-ama/lists'; + + item.id} +/> +``` + +## Accessibility Improvements + +- On `Android` allows TalkBack to announce **in list**/**out list** or **in grid**/**out of grid** + +### TalkBack + + + +To provide this accessibility feature, AMA wraps the list in the custom native +component: [ListWrapper](./ListWrapper.mdx). + + +## Additional props + +### `rowsCount` + +The number of rows of the list/grid. If empty, the length of the data is used to calculate it and divided by `numColumns`. + +:::note + +When passing `rowsCount`, it is used as it is and is assumed that the number of columns has been taken into account. + +::: + +### `numColumns` + +The number of columns of the list/grid. + +## Related guidelines + +- [Lists & Grids](../../../website/guidelines/lists-grids.md) From 0d630e176b2d0921b6cdb2fd4c2abe410ca166ca Mon Sep 17 00:00:00 2001 From: JDMathew Date: Mon, 5 Aug 2024 14:21:59 -0700 Subject: [PATCH 2/4] Add ListWrapper doc to AMA --- packages/lists/docs/ListWrapper.mdx | 42 +++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 packages/lists/docs/ListWrapper.mdx diff --git a/packages/lists/docs/ListWrapper.mdx b/packages/lists/docs/ListWrapper.mdx new file mode 100644 index 00000000..23dc4e63 --- /dev/null +++ b/packages/lists/docs/ListWrapper.mdx @@ -0,0 +1,42 @@ +import { TalkBackList } from '@site/src/components'; + +# ListWrapper + +ListWrapper is a custom native component for Android that allows TalkBack to recognise that its children are part of a list/grid and behave accordingly. + + + +This component can be used to wrap custom a FlatList whenever they do not provide the same accessibility experienced with native Android apps. [^1] + +## Usage + +```jsx +import { ListWrapper } from "@react-native-ama/lists"; + + + + + +``` + +:::note + +On iOS, the component is rendered as Fragment as this behaviour is native to Android only. +::: + +## Props + +### `rowsCount` + +The number of rows to be announced by TalkBack. + +### `columnsCount` + +This optional parameter is used by TalkBack to know if the user landed on a List or a Grid. +The default value of **1** makes TalkBack read: **in list** / **out of list**, while a bigger number: in grid / out of grid + +## Related guidelines + +- [Lists & Grids](../../../website/guidelines/lists-grids.md) + +[^1]: The component is internally used by [FlatList](./FlatList.mdx), [DynamicFlatList](./DynamicFlatList.mdx) and [StaticFlatList](./StaticFlatList.mdx) From c8b9a397c05537dfe55c7f89473c852e1b7ac8e2 Mon Sep 17 00:00:00 2001 From: JDMathew Date: Mon, 5 Aug 2024 15:18:26 -0700 Subject: [PATCH 3/4] Add FlatList doc to AMA --- packages/lists/docs/FlatList.mdx | 48 ++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 packages/lists/docs/FlatList.mdx diff --git a/packages/lists/docs/FlatList.mdx b/packages/lists/docs/FlatList.mdx new file mode 100644 index 00000000..33f6e358 --- /dev/null +++ b/packages/lists/docs/FlatList.mdx @@ -0,0 +1,48 @@ +import { TalkBackList, Required } from '@site/src/components'; + +# FlatList + +FlatList is an extension of the [React Native FlatList](https://reactnative.dev/docs/flatlist) component, [focused on accessibility](#accessibility-improvements). + +## Usage + +```jsx +import { FlatList } from '@react-native-ama/lists'; + + item.id} + listType="dynamic" + singularMessage="%count% item found" + pluralMessage="%count% items found" +/> +``` + +## Accessibility Improvements + +- On `Android` allows TalkBack to announce **in list**/**out list** or **in grid**/**out of grid** +- A [dynamic list](./DynamicFlatList.mdx) automatically announces the number of items found when it gets filtered + +### TalkBack + + + +To provide this accessibility feature AMA wraps the list in the custom native component: [ListWrapper](./ListWrapper.mdx). + +### Dynamic list + +A dynamic list must announce the number of items displayed if they change due to filtering. Check [here](../../../website/guidelines/lists-grids.md#number-of-results) for more info. + +## Props + +### `listType` + +| Value | Description | +| ------- | ------------------------------ | +| dynamic | Renders a [DynamicFlatList](/) | +| static | Renders a [StaticFlatList](/) | + +## Related guidelines + +- [Lists & Grids](../../../website/guidelines/lists-grids.md) From 82bbcc77002e63124b33a842c297902a0a29d72d Mon Sep 17 00:00:00 2001 From: JDMathew Date: Tue, 6 Aug 2024 13:57:59 -0700 Subject: [PATCH 4/4] Add DynamicFlatList doc to AMA --- packages/lists/docs/DynamicFlatList.mdx | 116 ++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 packages/lists/docs/DynamicFlatList.mdx diff --git a/packages/lists/docs/DynamicFlatList.mdx b/packages/lists/docs/DynamicFlatList.mdx new file mode 100644 index 00000000..1d223e4e --- /dev/null +++ b/packages/lists/docs/DynamicFlatList.mdx @@ -0,0 +1,116 @@ +import { TalkBackList, Required } from '@site/src/components'; + +# DynamicFlatList + +DynamicFlatList extends the React Native FlatList component [focused on accessibility]. + +## Usage + +```jsx +import { DynamicFlatList } from '@react-native-ama/lists'; + + item.id} + listType="dynamic" + singularMessage="%count% item found" + pluralMessage="%count% items found" +/> +``` + +## Accessibility Improvements + +- On `Android` allows TalkBack to announce **in list**/**out list** or **in grid**/**out of grid** +- A [dynamic list](./DynamicFlatList.mdx) automatically announces the number of items found when +it gets filtered + +### TalkBack + + + +To provide this accessibility feature AMA wraps the list in the custom native +component: [ListWrapper](./ListWrapper.mdx). + +### Dynamic list + +A dynamic list must announce the number of items displayed if they change due to filtering. +Check [here](../../../website/guidelines/lists-grids.md#number-of-results) for more info. + +## Additional props + +### `singularMessage` + +Is the message to announce when the list renders one[^1] item [^2]. +The string %count%\* will be replaced with the actual number of items rendered at the moment. + +| Type | Default | +|--------|-----------| +| string | undefined | + +### `pluralMessage` + +Is the message to announce when the list renders zero or multiple[^1] items [^2] +The string %count%\* will be replaced with the actual number of items rendered at the moment. + +| Type | Default | +|--------|-----------| +| string | undefined | + +### `isPlural` + +By default, the component considers the number **1** as singular and any other as plural. Although this works fine with English, it might not be the case for other languages. +For this reason, allows specifying a custom function that should return **true** if the _accessibilityPluralMessage_ should be used; otherwise, false. + +| Type | Default | +|---------------|-----------| +| () => boolean | undefined | + +#### Example: + +```js +import { DynamicFlatList } from 'react-native-ama'; + + item.id} + listType="dynamic" + singularMessage="%count% item found" + pluralMessage="%count% items found" + isPlural={customIsPlural} +/>; + +const customIsPlural = () => { + return Math.random() > 0.5; +}; +``` + +### `rowsCount` + +The number of rows of the list/grid. If empty, the length of the data is used to calculate it and divided by `numColumns`. + +| Type | Default | +| ------ | --------- | +| number | undefined | + +:::note + +When passing `rowsCount`, it is used as it is and is assumed that the number of columns has been taken into account. + +::: + +### `numColumns` + +The number of columns of the list. + +| Type | Default | +| ------ | --------- | +| number | undefined | + +## Related guidelines + +- [Lists & Grids](../../../website/guidelines/lists-grids.md) + +[^1]: The announcement is made only when the list is filtered, and the number of items displayed is different from the original one +[^2]: This is with the default behaviour that can be customised via the [isPlural](#isplural) prop