Add list documentation to AMA package (#226)

* Add StaticFlatList doc * Add ListWrapper doc to AMA * Add FlatList doc to AMA * Add DynamicFlatList doc to AMA
FormidableLabs · Aug 6, 2024 · db5d6f1 · db5d6f1
1 parent 54b8151
commit db5d6f1
Show file tree

Hide file tree

Showing 4 changed files with 255 additions and 0 deletions.
diff --git a/packages/lists/docs/DynamicFlatList.mdx 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';
+
+<DynamicFlatList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={item => 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
+
+<TalkBackList />
+
+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
+
+### <Required /> `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 |
+
+### <Required /> `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';
+
+<DynamicFlatList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={item => 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
diff --git a/packages/lists/docs/FlatList.mdx 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';
+
+<FlatList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={item => 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
+
+<TalkBackList />
+
+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
+
+### <Required /> `listType`
+
+| Value   | Description                    |
+| ------- | ------------------------------ |
+| dynamic | Renders a [DynamicFlatList](/) |
+| static  | Renders a [StaticFlatList](/)  |
+
+## Related guidelines
+
+- [Lists & Grids](../../../website/guidelines/lists-grids.md)
diff --git a/packages/lists/docs/ListWrapper.mdx 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.
+
+<TalkBackList />
+
+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";
+
+
+<ListWrapper rowsCount={10} columnsCount={1}>
+    <MyCustomFlatList />
+</ListWrapper>
+```
+
+:::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)
diff --git a/packages/lists/docs/StaticFlatList.mdx 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';
+
+<StaticFlatList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={item => item.id}
+/>
+```
+
+## Accessibility Improvements
+
+- On `Android` allows TalkBack to announce **in list**/**out list** or **in grid**/**out of grid**
+
+### TalkBack
+
+<TalkBackList />
+
+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)