Skip to content

Commit

Permalink
Add DynamicFlatList doc to AMA
Browse files Browse the repository at this point in the history
  • Loading branch information
JDMathew committed Aug 6, 2024
1 parent c8b9a39 commit 82bbcc7
Showing 1 changed file with 116 additions and 0 deletions.
116 changes: 116 additions & 0 deletions packages/lists/docs/DynamicFlatList.mdx
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

0 comments on commit 82bbcc7

Please sign in to comment.