Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 14 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,19 @@ grouped by category, with both components layered over it:
default). `scrollToOffsetPercentage` maps 0..1 to FlashList `scrollToOffset`
over the scrollable height (content height minus viewport height).
- **Handle calls.** Every `onScroll` frame calls `onScrollToOffsetPercentage` on
both components, so that path has to stay cheap. `onViewableIndexChanged` is
called with the first viewable index, debounced 500 ms by the app.
both components, so that path has to stay cheap. The value is not clamped:
the app divides the offset by the scrollable height, floored at 1 px, so an
iOS bounce reports values below 0 and above 1, and far outside that range on
a list shorter than its viewport. `onViewableIndexChanged` is called with the
first viewable index, debounced 500 ms by the app.
- Both use `hideFastScrollIndicatorTimeout` 2000. Sections can be collapsed,
which keeps header indices stable but hides the rows between them.

**Generic list wrapper** - a shared FlashList wrapper renders a right-side
`FastScrollIndicator` over every list in the app, wired the same way.
`FastScrollIndicator` over every list in the app but never calls its handle,
so the thumb never shows there. The wrapper keeps the scroll offset in state
and passes an inline `scrollToOffsetPercentage`, so the indicator re-renders
on every scroll frame of every list: its render has to stay cheap.

**Sectioned list with a tab bar** - one screen of the app puts a
`FastScrollSectionTab` above a FlashList of rows grouped by category, with a
Expand Down Expand Up @@ -114,7 +120,11 @@ only fits one side's typings fails there.
full-list item taps scroll to `startIndex`.
- **Imperative handles are the integration point.** Apps call
`onViewableIndexChanged` / `onScrollToOffsetPercentage` on a ref from their
list's callbacks. Treat handle names and signatures as public API.
list's callbacks. Treat handle names and signatures as public API. A handle
runs on the JS thread, as often as every scroll frame, and on Reanimated 3 a
shared value read from JS blocks until the UI thread answers. So a handle
reads JS copies kept in refs (`FastScrollIndicator`) or sends the work to the
UI thread with `runOnUI` (`FastScrollSectionDotsBar`).
- **Two version targets.** Code must run on the minimum peers this repo
develops against (`react-native-reanimated` 2.12, `react-native-gesture-handler`
2.8, the dev dependencies) and on the versions production runs
Expand Down
15 changes: 7 additions & 8 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ We want this community to be friendly and respectful to each other. Please follo

## Development workflow

To get started with the project, run `yarn` in the root directory to install the required dependencies for each package:
To get started with the project, use the Node version in `.nvmrc` and run `yarn bootstrap` in the root directory. It installs the dependencies of the example app, then those of the library. `yarn typecheck` needs both.

```sh
yarn
yarn bootstrap
```

> While it's possible to use [`npm`](https://github.com/npm/cli), the tooling is built around [`yarn`](https://classic.yarnpkg.com/), so you'll have an easier time if you use `yarn` for development.

While developing, you can run the [example app](/example/) to test your changes. Any changes you make in your library's JavaScript code will be reflected in the example app without a rebuild. If you change any native code, then you'll need to rebuild the example app.
While developing, you can run the [example app](/example/) to test your changes. It runs in Expo Go (SDK 52) and uses the library's source directly, so any change you make in the library shows up without a rebuild. The library has no native code.

To start the packager:

Expand Down Expand Up @@ -71,15 +71,15 @@ We follow the [conventional commits specification](https://www.conventionalcommi
- `test`: adding or updating tests, e.g. add integration tests using detox.
- `chore`: tooling changes, e.g. change CI config.

Our pre-commit hooks verify that your commit message matches this format when committing.
No git hook checks the format: the hooks in `lefthook.yml` are disabled.

### Linting and tests

[ESLint](https://eslint.org/), [Prettier](https://prettier.io/), [TypeScript](https://www.typescriptlang.org/)

We use [TypeScript](https://www.typescriptlang.org/) for type checking, [ESLint](https://eslint.org/) with [Prettier](https://prettier.io/) for linting and formatting the code, and [Jest](https://jestjs.io/) for testing.
We use [TypeScript](https://www.typescriptlang.org/) for type checking, [ESLint](https://eslint.org/) with [Prettier](https://prettier.io/) for linting and formatting the code, and [Jest](https://jestjs.io/) for testing. [docs/unit-testing.md](docs/unit-testing.md) has the rules for writing tests.

Our pre-commit hooks verify that the linter and tests pass when committing.
CI runs the linter, the type check, the tests and the build on every pull request. No git hook runs them when committing, so run them before you push.

### Publishing to npm

Expand All @@ -95,7 +95,7 @@ yarn release

The `package.json` file contains various scripts for common tasks:

- `yarn bootstrap`: setup project by installing all dependencies and pods.
- `yarn bootstrap`: setup project by installing the dependencies of the example app and of the library.
- `yarn typecheck`: type-check files with TypeScript.
- `yarn lint`: lint files with ESLint.
- `yarn test`: run unit tests with Jest.
Expand All @@ -112,5 +112,4 @@ When you're sending a pull request:
- Prefer small pull requests focused on one change.
- Verify that linters and tests are passing.
- Review the documentation to make sure it looks good.
- Follow the pull request template when opening a pull request.
- For pull requests that change the API or implementation, discuss with maintainers first by opening an issue.
62 changes: 39 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,53 +7,69 @@ Fast Scroll implementation over Flashlist for react native
## Installation

```sh
yarn install react-native-fast-scroll
yarn add react-native-fast-scroll
```

## Requirements

1. React Native Gesture Handler
2. React Native Reanimated >= 2
The package's peer dependencies:

1. `react-native-gesture-handler` >= 2.8
2. `react-native-reanimated` >= 2.12
3. `react-native-redash`
4. `@shopify/flash-list`

## Usage of the FastScroll Indicator

The indicator works with offsets from 0 (the top of the list) to 1 (its end),
over the height the list can scroll: its content minus its own height.

```js
import { FastScrollIndicator } from 'react-native-fast-scroll';

// ...

const contentHeight = useRef(0);
const listHeight = useRef(0);
const scrollableHeight = () =>
Math.max(0, contentHeight.current - listHeight.current);

// The thumb was dragged: scroll the list.
const scrollToOffsetPercentage = (offsetPercentage: number) => {
const flashListHeight =
flashListRef.current?.recyclerlistview_unsafe?.getContentDimension()
.height ?? 1;
const offset = offsetPercentage * flashListHeight;
flashListRef.current?.scrollToOffset({
offset,
});
}
flashListRef.current?.scrollToOffset({
offset: offsetPercentage * scrollableHeight(),
animated: false,
});
};

// The list scrolled: move the thumb.
const onScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
const flashListHeight =
flashListRef.current?.recyclerlistview_unsafe?.getContentDimension()
.height ?? 1;
const scrollable = scrollableHeight();
const offsetPercentage =
event.nativeEvent.contentOffset.y / flashListHeight;
scrollable > 0 ? event.nativeEvent.contentOffset.y / scrollable : 0;
fastScrollIndicatorRef.current?.onScrollToOffsetPercentage(
offsetPercentage
);
fastScrollSectionDotsRef.current?.onScrollToOffsetPercentage(
offsetPercentage
);
}

};

<FlashList
ref={flashListRef}
onScroll={onScroll}
onContentSizeChange={(_width, height) => (contentHeight.current = height)}
onLayout={(event) => (listHeight.current = event.nativeEvent.layout.height)}
// ...
/>

<FastScrollIndicator
scrollToOffsetPercentage={scrollToOffsetPercentage}
hideFastScrollIndicatorTimeout={2000}
side={'right'}
ref={fastScrollIndicatorRef}
thumbColor={'rgba(65, 64, 66, 0.6)'}
scrollBarColor={'transparent'}
scrollToOffsetPercentage={scrollToOffsetPercentage}
hideFastScrollIndicatorTimeout={2000}
side={'right'}
ref={fastScrollIndicatorRef}
thumbColor={'rgba(65, 64, 66, 0.6)'}
scrollBarColor={'transparent'}
/>
```

Expand Down
Loading
Loading