Skip to content

Commit bab65ef

Browse files
vishalnarkhedevishalnarkhede
committed
docs: added docs on docusaurus
1 parent f2c0429 commit bab65ef

22 files changed

+11010
-40
lines changed

‎README.md‎

Lines changed: 2 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,6 @@
1010

1111
![Vishal - Article 01](https://user-images.githubusercontent.com/11586388/109156507-38082600-7771-11eb-82c4-2ca0dec97545.png)
1212

13-
## Tutorial on how to implement Chat UI with bidirectional infinite scroll
14-
15-
https://dev.to/vishalnarkhede/react-native-how-to-build-bidirectional-infinite-scroll-32ph
16-
1713
## Introduction
1814

1915
[FlatList](https://reactnative.dev/docs/flatlist) by react-native only allows infinite scroll in one direction (using `onEndReached`). This package adds capability on top of FlatList to allow infinite scroll from both directions, and also maintains **smooth scroll** UX.
@@ -40,43 +36,9 @@ https://dev.to/vishalnarkhede/react-native-how-to-build-bidirectional-infinite-s
4036
</tr>
4137
</table>
4238

43-
## 🛠 Installation
44-
45-
```sh
46-
yarn add react-native-bidirectional-infinite-scroll @stream-io/flat-list-mvcp
47-
```
48-
49-
## 🔮 Usage
50-
51-
Please check the [example app](https://github.com/GetStream/react-native-bidirectional-infinite-scroll/tree/main/example) for working demo.
52-
53-
```jsx
54-
import { FlatList } from "react-native-bidirectional-infinite-scroll";
55-
56-
<FlatList
57-
data={numbers}
58-
renderItem={ListItem}
59-
keyExtractor={(item) => item.toString()}
60-
onStartReached={onStartReached} // required, should return a promise
61-
onEndReached={onEndReached} // required, should return a promise
62-
showDefaultLoadingIndicators={true} // optional
63-
onStartReachedThreshold={10} // optional
64-
onEndReachedThreshold={10} // optional
65-
activityIndicatorColor={'black'} // optional
66-
HeaderLoadingIndicator={() => { /** Your loading indicator */ }} // optional
67-
FooterLoadingIndicator={() => { /** Your loading indicator */ }} // optional
68-
enableAutoscrollToTop={false} // optional | default - false
69-
// You can use any other prop on react-native's FlatList
70-
/>
71-
72-
```
73-
74-
**Note**:
75-
- `onEndReached` and `onStartReached` only get called once, per content length.
76-
- `onEndReached` and `onStartReached` must return a promise.
77-
- `maintainVisibleContentPosition` is fixed, and can't be modified through props.
78-
- doesn't accept `ListFooterComponent` via prop, since it is occupied by `FooterLoadingIndicator`
39+
## 🛠 Installation and Usage
7940

41+
Please check the complete docs at https://getstream.github.io/react-native-bidirectional-infinite-scroll/
8042

8143
## ✍ Contributing
8244

‎website/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎website/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Website
2+
3+
This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
4+
5+
## Installation
6+
7+
```console
8+
yarn install
9+
```
10+
11+
## Local Development
12+
13+
```console
14+
yarn start
15+
```
16+
17+
This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
## Build
20+
21+
```console
22+
yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
## Deployment
28+
29+
```console
30+
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
31+
```
32+
33+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎website/babel.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎website/docs/example.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Example
3+
slug: /example
4+
sidebar_label: Example
5+
---
6+
7+
You can refer following resources for examples:
8+
9+
- [https://dev.to/vishalnarkhede/react-native-how-to-build-bidirectional-infinite-scroll](https://dev.to/vishalnarkhede/react-native-how-to-build-bidirectional-infinite-scroll-32ph#%F0%9F%96%A5-tutorial-chat-ui-with-bidirectional-infinite-scroll)
10+
- [https://github.com/GetStream/react-native-bidirectional-infinite-scroll/tree/main/example](https://github.com/GetStream/react-native-bidirectional-infinite-scroll/tree/main/example)

‎website/docs/getting-started.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: Installation and Usage
3+
slug: /installation
4+
---
5+
6+
## Setup
7+
8+
#### NPM
9+
10+
```sh
11+
$ npm i react-native-bidirectional-infinite-scroll @stream-io/flat-list-mvcp
12+
```
13+
14+
#### Yarn
15+
16+
```sh
17+
$ yarn add react-native-bidirectional-infinite-scroll @stream-io/flat-list-mvcp
18+
```
19+
20+
## Usage
21+
22+
Please check the [example app](https://github.com/GetStream/react-native-bidirectional-infinite-scroll/tree/main/example) for working demo.
23+
24+
```js
25+
import { FlatList } from "react-native-bidirectional-infinite-scroll";
26+
27+
export const App = () => {
28+
// All your business logic here
29+
30+
return (
31+
<FlatList
32+
data={numbers}
33+
renderItem={ListItem}
34+
keyExtractor={(item) => item.toString()}
35+
onStartReached={onStartReached} // required, should return a promise
36+
onEndReached={onEndReached} // required, should return a promise
37+
showDefaultLoadingIndicators={true} // optional
38+
onStartReachedThreshold={10} // optional
39+
onEndReachedThreshold={10} // optional
40+
activityIndicatorColor={'black'} // optional
41+
HeaderLoadingIndicator={() => { /** Your loading indicator */ }} // optional
42+
FooterLoadingIndicator={() => { /** Your loading indicator */ }} // optional
43+
enableAutoscrollToTop={false} // optional | default - false
44+
// You can use any other prop on react-native's FlatList
45+
/>
46+
)
47+
}
48+
```

‎website/docs/how-it-works.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: How it works
3+
slug: /how-it-works
4+
---
5+
6+
This section will walk you through the hurdles of implementing bidirectional infinite scroll and how its solved by this package.
7+
​
8+
### Support for `onStartReached`
9+
[FlatList](https://reactnative.dev/docs/flatlist) from React Native has built-in support for infinite scroll in a single direction (from the end of the list). You can add a prop `onEndReached`on `FlatList`. This function gets called when your scroll is near the end of the list, and thus you can append more items to the list from this function. You can Google for **React Native infinite scrolling**, and you will find plenty of examples for this. Unfortunately, the `FlatList` doesn't provide any similar prop for `onStartReached` for infinite scrolling in other directions.
10+
​
11+
We have added support for this prop as part of this package by simply adding the `onScroll` handler on `FlatList`, and executing the callback function (`onStartReached`) when the scroll is near the start of the list. If you take a look at the implementation of [VirtualizedList](https://github.com/facebook/react-native/blob/master/Libraries/Lists/VirtualizedList.js), you will notice that `onEndReached`function gets called only once per content length. That's there for a good purpose - to avoid redundant function calls on every scroll position change. Similar optimizations have been done for `onStartReached` within this package.
12+
​
13+
### Race condition between `onStartReached` and `onEndReached`
14+
15+
To maintain a smooth scrolling experience, we need to manage the execution order of `onStartReached` and `onEndReached`. Because if both the callbacks happen at (almost) the same time, which means items will be added to the list from both directions. This may result in scroll jump, and that's not a good user experience. Thus it's essential to make sure one callback waits for the other callback to finish.
16+
​
17+
### `onStartReachedThreshold` and `onEndReachedThreshold`
18+
19+
`FlatList` from React Native has a support for the prop `onEndReachedThreshold`, which is [documented here](https://reactnative.dev/docs/flatlist#onendreachedthreshold)
20+
​
21+
> How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the `onEndReached` callback.
22+
23+
24+
Instead, it's easier to have a fixed value offset (distance from the end of the list) to trigger one of these callbacks. Thus we can maintain these two values within our implementation. So `onStartReachedThreshold` and `onEndReachedThreshold` props accept the number - distance from the end of the list to trigger one of these callbacks.
25+
​
26+
### Smooth scrolling experience
27+
`FlatList` from React Native accepts a prop - [maintainVisibleContentPosition](https://reactnative.dev/docs/scrollview#maintainvisiblecontentposition), which makes sure your scroll doesn't jump to the end of the list when more items are added to the list. But this prop is only supported on iOS for now. So taking some inspiration from this [PR](https://github.com/facebook/react-native/pull/29466), we published our separate package to add support for this prop on Android - [flat-list-mvcp](https://github.com/GetStream/flat-list-mvcp#maintainvisiblecontentposition-prop-support-for-android-react-native). And thus `@stream-io/flat-list-mvcp` is a dependency of the `react-native-bidirectional-scroll` package.
28+
​

‎website/docs/introduction.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Introduction
3+
slug: /
4+
---
5+
6+
[FlatList](https://reactnative.dev/docs/flatlist) by react-native only allows infinite scroll in one direction (using `onEndReached`). This package adds capability on top of FlatList to allow infinite scroll from both directions, and also maintains **smooth scroll** UX.
7+
8+
- Accepts prop `onStartReached` & `onEndReached`, which you can use to load more results.
9+
- Calls to onEndReached and onStartReached have been optimized.
10+
- Inline loading Indicators, which can be customized as well.
11+
- Uses [flat-list-mvcp](https://github.com/GetStream/flat-list-mvcp#maintainvisiblecontentposition-prop-support-for-android-react-native) to maintain scroll position or smooth scroll UX.
12+
13+
14+
<table>
15+
<tr>
16+
<td align='center' width="33%"><img src='https://user-images.githubusercontent.com/11586388/109138261-77774800-775a-11eb-806b-2add75755af7.gif' height="600" /></td>
17+
<td align='center' width="33%"><img src='https://user-images.githubusercontent.com/11586388/109139686-16507400-775c-11eb-893f-8cccfb47f9d7.gif' height="600"/></td>
18+
</tr>
19+
<tr></tr>
20+
<tr>
21+
<td align='center'>
22+
<strong>iOS</strong>
23+
</td>
24+
<td align='center'>
25+
<strong>Android</strong>
26+
</td>
27+
</tr>
28+
</table>

‎website/docs/props.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: Props
3+
slug: /props
4+
---
5+
6+
This package is a wrapper around react-native's FlatList. So it accepts all the props from `FlatList`, except for [`maintainVisibleContentPosition`](https://reactnative.dev/docs/0.63/scrollview#maintainvisiblecontentposition). It has support for following additional props, to fine tune your infinite scroll.
7+
8+
9+
### `onEndReached`
10+
11+
Called once when the scroll position gets close to end of list. This must return a promise.
12+
You can `onEndReachedThreshold` as distance from end of list, when this function should be called.
13+
14+
15+
| type | default | required |
16+
| -------- | ------- | -------- |
17+
| function | null | YES |
18+
19+
20+
### `onStartReached`
21+
22+
Called once when the scroll position gets close to begining of list. This must return a promise.
23+
You can `onStartReachedThreshold` as distance from beginning of list, when this function should be called.
24+
25+
| type | default | required |
26+
| -------- | ------- | -------- |
27+
| function | null | YES |
28+
29+
### `activityIndicatorColor`
30+
31+
Color for inline loading indicator
32+
33+
| type | default | required |
34+
| ------ | ------- | -------- |
35+
| string | #000000 | NO |
36+
37+
### `enableAutoscrollToTop`
38+
39+
Enable autoScrollToTop.
40+
In chat type applications, you want to auto scroll to bottom, when new message comes it.
41+
42+
| type | default | required |
43+
| ------ | ------- | -------- |
44+
| string | false | NO |
45+
46+
### `autoscrollToTopThreshold`
47+
48+
The scroll offset threshold, below which auto scrolling should occur.
49+
50+
:::info
51+
52+
This prop only works, when `enableAutoscrollToTop` is set to true.
53+
54+
:::
55+
56+
| type | default | required |
57+
| -------- | ------- | -------- |
58+
| number | 100 | NO |
59+
60+
61+
### `onStartReachedThreshold`
62+
63+
Scroll offset from beginning of list, when onStartReached should be called.
64+
65+
| type | default | required |
66+
| -------- | ------- | -------- |
67+
| number | 10 | NO |
68+
69+
### `onEndReachedThreshold`
70+
71+
Scroll distance from end of list, when onStartReached should be called.
72+
Please note that this is different from onEndReachedThreshold of FlatList from react-native.
73+
74+
| type | default | required |
75+
| -------- | ------- | -------- |
76+
| number | 10 | NO |
77+
78+
### `showDefaultLoadingIndicators`
79+
80+
If true, inline loading indicators will be shown
81+
82+
| type | default | required |
83+
| -------- | ------- | -------- |
84+
| boolean | true | NO |
85+
86+
### `HeaderLoadingIndicator`
87+
88+
Custom UI component for header inline loading indicator
89+
90+
| type | default | required |
91+
| -------- | ------- | -------- |
92+
| Component | [ActivityIndicator](https://reactnative.dev/docs/0.63/activityindicator) | NO |
93+
94+
95+
### `FooterLoadingIndicator`
96+
97+
Custom UI component for footer inline loading indicator
98+
99+
| type | default | required |
100+
| -------- | ------- | -------- |
101+
| Component | [ActivityIndicator](https://reactnative.dev/docs/0.63/activityindicator) | NO |
102+
103+
104+
### `ListHeaderComponent`
105+
106+
Custom UI component for header indicator of FlatList, which overrides the HeaderLoadingIndicator. Only used when `showDefaultLoadingIndicators` is false
107+
108+
| type | default | required |
109+
| -------- | ------- | -------- |
110+
| Component | null | NO |
111+
112+
113+
### `ListFooterComponent`
114+
115+
Custom UI component for footer indicator of FlatList, which overrides the FooterLoadingIndicator. Only used when `showDefaultLoadingIndicators` is false
116+
117+
| type | default | required |
118+
| -------- | ------- | -------- |
119+
| Component | null | NO |
120+
121+

‎website/docs/troubleshooting.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Troubleshooting
3+
---
4+
5+
### Exception in native call from JS
6+
7+
Please upgrade to `@stream-io/[email protected]`
8+
9+
### Scroll is jumping, when new items are loaded in list
10+
11+
Please try adjusting (increasing) the [windowSize](https://reactnative.dev/docs/0.63/virtualizedlist#windowsize) on FlatList.

0 commit comments

Comments
 (0)