-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
116 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |