react-native-header-motion 0.4.0 → 1.0.0-beta.0

package/README.md

@@ -1,34 +1,67 @@
 # React Native Header Motion
 
-High-level APIs for **orchestrating header motion** driven by scroll — built on top of [**React Native Reanimated**](https://docs.swmansion.com/react-native-reanimated/).
+High-level APIs for orchestrating scroll-driven header motion in React Native.
 
-This library is **100% a wrapper around Reanimated**. All the credit for the underlying animation engine, worklets, and primitives goes to **Reanimated** (and `react-native-worklets`). This package focuses on a specific use case: **header motion + scroll orchestration** (including multi-scroll/tab scenarios).
+This library is a wrapper around:
+
+- [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/) & [React Native Worklets](https://docs.swmansion.com/react-native-worklets/docs/)
+- [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/)
+
+All credit for the underlying animation engine, worklets, gestures, and low-level primitives goes to those libraries. This package focuses on composing them into a specific higher-level use case: header motion and scroll orchestration.
+
+This library does not ship a predesigned "collapsible header" UI. It gives you the pieces to:
+
+- measure the parts of a header that matter
+- derive a shared `progress` value from scroll
+- keep multiple scrollables in sync when one header is shared across them
+- bridge that state into navigation-rendered headers
+
+You build the visuals yourself on top of that.
 
 <div align="center">
-<img src="https://github.com/user-attachments/assets/b673349a-f26a-4cc8-bfe1-60d77deb4390" width="70%" />
+  <img src="https://github.com/user-attachments/assets/b673349a-f26a-4cc8-bfe1-60d77deb4390" width="70%" />
 </div>
 
-## What this is (and isn’t)
+## Version notes
+
+- If you are upgrading from `v0.3.x`, read [MIGRATION-v1.md](./MIGRATION-v1.md).
+- If you are still on the pre-v1 API and need the old docs, use the `v0` README:
+  [README on branch `v0`](https://github.com/pawicao/react-native-header-motion/blob/v0/README.md)
+
+## What's new in v1
+
+The API change in v1 is quite substantial, but the migration is usually straightforward and the end result gives a much better developer experience.
 
-**✅ This is**
+- Header panning built on top of `react-native-gesture-handler`. Dragging on the header itself can initiate or continue the scroll interaction naturally instead of forcing the user to only use the scrollables.
+- Context-first header API built around `HeaderMotion.Header` and `HeaderMotion.Header.Dynamic`
+- Explicit navigation bridging with `HeaderMotion.Bridge` and `HeaderMotion.NavigationBridge`
+- Narrower `useMotionProgress()` that focuses on `progress` and `progressThreshold`
+- Reusable custom-scrollable factory via `createHeaderMotionScrollable()`
+  - It's now easier than ever to wire up LegendList and FlashList to Header Motion!
+- `react-native-gesture-handler` added to the peer dependency surface
 
-- A small set of components + hooks that expose a single `progress` shared value and a few measurement helpers.
-- A scroll orchestration layer that can keep multiple scrollables in sync (e.g. tabs + pager).
+## What this library is good at
 
-**❌ This is NOT**
+- Scroll-driven animated headers
+- Shared header state across tabs / pagers / multiple scrollables
+- Navigation headers rendered outside the provider subtree
+- Reusable wrappers around custom scrollables
 
-- An out-of-the-box “collapsible header” component with a baked-in look.
+## What this library is not trying to be
 
-You build any header motion you want by animating based on `progress`.
+- A fully styled header component
+- A page layout framework
+- A general-purpose animation abstraction on top of Reanimated
 
-## Requirements (peer dependencies)
+## Requirements
 
-You must have these installed in your app:
+Your app must provide:
 
-- `react-native-reanimated` **>= 4.0.0**
-- `react-native-worklets` **>= 0.4.0**
+- `react-native-gesture-handler >= 2.0.0`
+- `react-native-reanimated >= 4.0.0`
+- `react-native-worklets >= 0.4.0`
 
-This package declares them as peer dependencies, so your app owns those versions. Remember to install a version of Worklets compatible with your version of Reanimated.
+These are peer dependencies.
 
 ## Installation
 
@@ -42,483 +75,504 @@ or
 yarn add react-native-header-motion
 ```
 
-### Reanimated setup
+Then follow the normal setup instructions for:
 
-Follow the official Reanimated [installation instructions](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/#installation) for your environment (Expo / bare RN).
+- [Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/#installation)
+- [Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation)
+- [Worklets](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/#installation)
 
 ## Mental model
 
-There are three key concepts:
+There are four concepts to understand:
 
-### 1) `progress` (SharedValue)
+### 1. `progress`
 
-`progress` is a Reanimated `SharedValue<number>` that represents the normalized progress of your header animation.
+`progress` is a `SharedValue<number>`.
 
-- `0` → animation start (initial state)
-- `1` → animation end (final state)
+- `0` means "expanded"
+- `1` means "collapsed"
 
-### 2) `progressThreshold`
+Most header animations should be derived from this value.
 
-`progressThreshold` is the distance needed for `progress` to move from `0 → 1`.
+### 2. `progressThreshold`
 
-You can provide it as:
+`progressThreshold` is the collapse distance in pixels.
 
-- a number, or
-- a function `(measuredDynamic) => threshold`
+It can be:
 
-If you provide a function, it uses the value measured by `measureDynamic`.
+- a fixed number
+- a function derived from the measured dynamic part of the header
 
-### 3) Measurement functions
+At runtime, `useMotionProgress()` gives you `progressThreshold` as a `SharedValue<number>`.
 
-The library gives you two measurement callbacks that you pass to your header layout:
+In practice, `progress` is calculated by mapping scroll distance across that threshold:
 
-- `measureTotalHeight` – attach to the _outer_ header container to measure the total header height. Scrollables use this to add `paddingTop` so content starts below the header.
-- `measureDynamic` – attach to the part of the header that determines the threshold (often the animated/dynamic portion).
+- before the threshold, `progress` moves from `0` toward `1`
+- at the threshold, `progress` reaches `1`
+- past the threshold, behavior depends on `progressExtrapolation`
 
-## Why `HeaderMotion.Header` exists
+### 3. Total header height vs dynamic header height
 
-When you pass a `header` component to React Navigation / Expo Router, that header is rendered by the navigator in a different part of the React tree.
+The library measures two different things:
 
-Because of that, the navigation header **cannot read the `HeaderMotion` context**, so calling `useMotionProgress()` inside that header would throw.
+- the total header height
+- the dynamic part of the header that should define the collapse distance
 
-`HeaderMotion.Header` solves this by acting as a **bridge**: it runs inside the provider, reads context, and passes the values to your navigation header via a render function.
+`HeaderMotion.Header` wires the total-height measurement.
 
-## Why `HeaderBase` / `AnimatedHeaderBase` uses absolute positioning
+`HeaderMotion.Header.Dynamic` wires the dynamic measurement.
 
-Navigation headers are special:
+In many designs:
 
-- Even with `headerTransparent: true`, the navigator can still reserve layout space for the header container.
-- If you animate with translations without absolute positioning, you can end up with:
-  - content below becoming unclickable (an invisible parent header still sits on top), or
-  - content hidden under the header container.
+- the sticky/top part stays visible
+- the dynamic part slides away
+- the dynamic part is what should feed `progressThreshold`
 
-`HeaderBase` and `AnimatedHeaderBase` are **absolutely positioned** to avoid those layout traps, which is especially important when you use transforms/translations.
+### 4. Navigation headers are a separate tree
 
-## When to use components vs hooks
+When a navigation library renders a header outside your screen subtree, it cannot read the `HeaderMotion` context directly.
 
-You can use either style; pick based on your integration needs:
+That is why the library has:
 
-- Prefer **components** when you want a “batteries included” wiring:
+- `HeaderMotion.Bridge`
+- `HeaderMotion.NavigationBridge`
 
-  - `HeaderMotion.ScrollView` / `HeaderMotion.FlatList` for common scrollables
-  - `HeaderMotion.ScrollManager` for custom scrollables via render-props
+Use them only to move HeaderMotion context across that boundary.
 
-- Prefer **hooks** when you want to build your own wrappers:
-  - `useScrollManager()` (same engine as `HeaderMotion.ScrollManager`, but hook-based)
-  - `useMotionProgress()` when your header is inside the provider tree
+## Recommended integration order
 
-Also:
+The library allows (and requires) you to integrate your scrollables with headers to provide animation behavior.
 
-- Use `HeaderMotion.Header` when your header is rendered by navigation.
-- Use `useMotionProgress` when your header is rendered inside the same tree as `HeaderMotion`.
+Use the simplest integration that fits your case:
 
-## Examples
-
-### Example app
+1. `HeaderMotion.ScrollView` or `HeaderMotion.FlatList` - exported directly from the library
+2. `createHeaderMotionScrollable()` - to easily create custom integrated scrollables on top of other scrollables (e.g. LegendList or FlashList)
+3. `HeaderMotion.ScrollManager` / `useScrollManager()` - for even more custom scenarios
 
-Examples live in the example app: `example/`. They demonstrate a few cases, from simple animations, to scroll orchestration and persisted header animation state between different tabs (e.g. with `react-native-pager-view`).
+For custom scrollables, prefer `createHeaderMotionScrollable()` first.
 
-Those examples use Expo Router as the navigation library, but it should be fairly simple to do the same with plain React Navigation.
+Use the scroll managers only when the factory approach is not flexible enough.
 
-### Expo Router
+## Quick start: navigation header
 
-This is the core pattern used in the example app (`example/src/app/simple.tsx`).
+This is the core v1 pattern when your header is rendered by Expo Router / React Navigation.
 
 ```tsx
-import HeaderMotion, {
-  AnimatedHeaderBase,
-  type WithCollapsibleHeaderProps,
-} from 'react-native-header-motion';
+import HeaderMotion, { useMotionProgress } from 'react-native-header-motion';
 import { Stack } from 'expo-router';
+import { StyleSheet, View } from 'react-native';
 import Animated, {
   Extrapolation,
   interpolate,
   useAnimatedStyle,
 } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import { View } from 'react-native';
 
 export default function Screen() {
   return (
     <HeaderMotion>
-      <HeaderMotion.Header>
-        {(headerProps) => (
+      <HeaderMotion.Bridge>
+        {(ctx) => (
           <Stack.Screen
             options={{
-              header: () => <MyHeader {...headerProps} />,
+              header: () => (
+                <HeaderMotion.NavigationBridge value={ctx}>
+                  <AppHeader />
+                </HeaderMotion.NavigationBridge>
+              ),
             }}
           />
         )}
-      </HeaderMotion.Header>
+      </HeaderMotion.Bridge>
 
-      <HeaderMotion.ScrollView>
-        {/* your scrollable content */}
-      </HeaderMotion.ScrollView>
+      <HeaderMotion.ScrollView>{/* content */}</HeaderMotion.ScrollView>
     </HeaderMotion>
   );
 }
 
-function MyHeader({
-  progress,
-  measureTotalHeight,
-  measureDynamic,
-  progressThreshold,
-}: WithCollapsibleHeaderProps) {
+function AppHeader() {
+  const { progress, progressThreshold } = useMotionProgress();
   const insets = useSafeAreaInsets();
 
   const containerStyle = useAnimatedStyle(() => {
-    const translateY = interpolate(
-      progress.value,
-      [0, 1],
-      [0, -progressThreshold],
-      Extrapolation.CLAMP
-    );
-    return { transform: [{ translateY }] };
+    const threshold = progressThreshold.get();
+
+    return {
+      transform: [
+        {
+          translateY: interpolate(
+            progress.get(),
+            [0, 1],
+            [0, -threshold],
+            Extrapolation.CLAMP
+          ),
+        },
+      ],
+    };
   });
 
   return (
-    <AnimatedHeaderBase
-      onLayout={measureTotalHeight}
-      style={[{ paddingTop: insets.top }, containerStyle]}
+    <HeaderMotion.Header
+      style={[styles.header, { paddingTop: insets.top }, containerStyle]}
     >
-      <Animated.View onLayout={measureDynamic}>
-        {/* “dynamic” part of the header */}
-      </Animated.View>
+      <HeaderMotion.Header.Dynamic>
+        {/* collapsible part */}
+      </HeaderMotion.Header.Dynamic>
 
-      <View>{/* "regular" part of the header */}</View>
-    </AnimatedHeaderBase>
+      <View>{/* sticky part */}</View>
+    </HeaderMotion.Header>
   );
 }
-```
 
-### React Navigation
+const styles = StyleSheet.create({
+  header: {
+    backgroundColor: '#304077',
+  },
+});
+```
 
-In React Navigation you typically configure headers via `navigation.setOptions()`.
+## Quick start: inline header inside the screen
 
-Important: the header itself can’t call `useMotionProgress()`, so we still use `HeaderMotion.Header` as a bridge.
+If your animated header lives in the same subtree as `HeaderMotion`, you do not need bridging at all.
 
 ```tsx
-import React from 'react';
-import HeaderMotion, {
-  AnimatedHeaderBase,
-  type WithCollapsibleHeaderProps,
-} from 'react-native-header-motion';
-import { useNavigation } from '@react-navigation/native';
-import Animated, {
-  Extrapolation,
-  interpolate,
-  useAnimatedStyle,
-} from 'react-native-reanimated';
-import { View } from 'react-native';
-
-export function MyScreen() {
+function Screen() {
   return (
     <HeaderMotion>
-      <HeaderMotion.Header>
-        {(headerProps) => (
-          <NavigationHeaderInstaller headerProps={headerProps} />
-        )}
-      </HeaderMotion.Header>
+      <InlineHeader />
       <HeaderMotion.ScrollView>{/* content */}</HeaderMotion.ScrollView>
     </HeaderMotion>
   );
 }
 
-function NavigationHeaderInstaller({
-  headerProps,
-}: {
-  headerProps: WithCollapsibleHeaderProps;
-}) {
-  const navigation = useNavigation();
-
-  React.useLayoutEffect(() => {
-    navigation.setOptions({
-      header: () => <MyHeader {...headerProps} />,
-    });
-  }, [navigation, headerProps]);
+function InlineHeader() {
+  const { progress, progressThreshold } = useMotionProgress();
 
-  return null;
+  return (
+    <HeaderMotion.Header>
+      <HeaderMotion.Header.Dynamic>
+        {/* collapsible section */}
+      </HeaderMotion.Header.Dynamic>
+    </HeaderMotion.Header>
+  );
 }
+```
 
-function MyHeader({
-  progress,
-  measureTotalHeight,
-  measureDynamic,
-  progressThreshold,
-}: WithCollapsibleHeaderProps) {
-  const insets = useSafeAreaInsets();
+## Shared header across multiple scrollables
 
-  const containerStyle = useAnimatedStyle(() => {
-    const translateY = interpolate(
-      progress.value,
-      [0, 1],
-      [0, -progressThreshold],
-      Extrapolation.CLAMP
-    );
-    return { transform: [{ translateY }] };
-  });
+If one header is shared across tabs or pager pages:
+
+1. Create an active scroll id with `useActiveScrollId()`
+2. Pass `activeScrollId.sv` to `HeaderMotion`
+3. Give each scrollable a unique `scrollId`
+
+```tsx
+import { useRef } from 'react';
+import PagerView from 'react-native-pager-view';
+
+const indexToKey = new Map([
+  [0, 'A'],
+  [1, 'B'],
+]);
+
+function Screen() {
+  const [activeScrollId, setActiveScrollId] = useActiveScrollId<'A' | 'B'>('A');
+  const pagerRef = useRef<PagerView>(null);
 
   return (
-    <AnimatedHeaderBase
-      onLayout={measureTotalHeight}
-      style={[{ paddingTop: insets.top }, containerStyle]}
-    >
-      <Animated.View onLayout={measureDynamic}>
-        {/* “dynamic” part of the header */}
-      </Animated.View>
+    <HeaderMotion activeScrollId={activeScrollId.sv}>
+      <HeaderMotion.Bridge>
+        {(ctx) => (
+          <Stack.Screen
+            options={{
+              header: () => (
+                <HeaderMotion.NavigationBridge value={ctx}>
+                  <Header />
+                </HeaderMotion.NavigationBridge>
+              ),
+            }}
+          />
+        )}
+      </HeaderMotion.Bridge>
+
+      <PagerView
+        ref={pagerRef}
+        style={{ flex: 1 }}
+        initialPage={0}
+        onPageSelected={(e) => {
+          setActiveScrollId(indexToKey.get(e.nativeEvent.position)!);
+        }}
+      >
+        <View key="A">
+          <HeaderMotion.ScrollView scrollId="A">
+            {/* page A content */}
+          </HeaderMotion.ScrollView>
+        </View>
+
+        <View key="B">
+          <HeaderMotion.ScrollView scrollId="B">
+            {/* page B content */}
+          </HeaderMotion.ScrollView>
+        </View>
+      </PagerView>
+    </HeaderMotion>
+  );
+}
+```
 
-      <View>{/* "regular" part of the header */}</View>
-    </AnimatedHeaderBase>
+## Header panning
+
+Sometimes the header itself takes up a large part of the screen, so forcing the user to move their finger back down to the scrollable can feel awkward.
+
+In those cases, you can make the header surface itself drive the scroll interaction as well:
+
+```tsx
+function Header() {
+  return (
+    <HeaderMotion.Header pannable>
+      <HeaderMotion.Header.Dynamic>
+        {/* collapsible content */}
+      </HeaderMotion.Header.Dynamic>
+    </HeaderMotion.Header>
   );
 }
 ```
 
-### Tabs / pager: synchronizing multiple scrollables
+## Public API
 
-If you have multiple scrollables (e.g. pages in `react-native-pager-view`), you can keep a single header progress by:
+### Default export: `HeaderMotion`
 
-1. Creating a shared “active scroll id” using `useActiveScrollId()`
-2. Passing `activeScrollId.sv` to `<HeaderMotion activeScrollId={...} />`
-3. Rendering each page scrollable with a unique `scrollId`
+Compound component with:
 
-The example app shows this pattern in `example/src/app/collapsible-pager.tsx` using `HeaderMotion.ScrollManager`.
+- `HeaderMotion.Header`
+- `HeaderMotion.Bridge`
+- `HeaderMotion.NavigationBridge`
+- `HeaderMotion.ScrollView`
+- `HeaderMotion.FlatList`
+- `HeaderMotion.ScrollManager`
 
-### Keeping the native header (back button/title) + custom animated header below
+Provider props:
 
-Sometimes you want to keep the native navigation header for back buttons + title, but still animate a custom header section below it.
+- `progressThreshold?: number | ((measuredDynamic: number) => number)`: collapse distance in pixels; when passed as a function, it is derived from the value measured by `HeaderMotion.Header.Dynamic`
+- `measureDynamic?: (e) => number`: controls what value is read from the dynamic section's layout event; defaults to its height
+- `measureDynamicMode?: 'mount' | 'update'`: `'mount'` measures once; `'update'` re-measures when the dynamic section lays out again
+- `activeScrollId?: SharedValue<string>`: identifies which scrollable currently owns header progress in multi-scroll setups
+- `progressExtrapolation?: ExtrapolationType`: controls how `progress` behaves outside the normal collapse range
 
-In that case:
+### `HeaderMotion.Header`
 
-- set `headerTransparent: true`
-- do **not** provide a custom `header` component
-- render your animated header content _inside the screen_ under the native header
+Main header container.
 
-Sketch:
+Responsibilities:
 
-```tsx
-import HeaderMotion, {
-  AnimatedHeaderBase,
-  useMotionProgress,
-} from 'react-native-header-motion';
-import { Stack } from 'expo-router';
-import Animated, {
-  Extrapolation,
-  interpolate,
-  useAnimatedStyle,
-} from 'react-native-reanimated';
-import { View } from 'react-native';
+- measures total header height
+- applies overlay positioning by default
+- can make the header surface pannable
 
-export default function Screen() {
-  return (
-    <>
-      <Stack.Screen options={{ headerTransparent: true }} />
-      <HeaderMotion>
-        <InlineAnimatedHeader />
-        <HeaderMotion.ScrollView>
-          {/* rest of content */}
-        </HeaderMotion.ScrollView>
-      </HeaderMotion>
-    </>
-  );
-}
+Props:
 
-function InlineAnimatedHeader() {
-  const { progress, measureTotalHeight, measureDynamic, progressThreshold } =
-    useMotionProgress();
+- all normal `Animated.View` props in default mode: styles, accessibility props, pointer events, and other normal animated view props work as expected
+- `overlay?: boolean`: keeps the header absolutely positioned above content; disable only if you intentionally want it in normal layout flow
+- `pannable?: boolean`: allows dragging directly on the header surface to continue the scroll interaction
+- `panDecayConfig?: WithDecayConfig | ((event) => WithDecayConfig)`: customizes the momentum animation after a header pan ends
+- `withGestureHandlerRootView?: boolean`: wraps the gesture subtree in `GestureHandlerRootView` when that part of the tree is not already under one
+- `asChild?: boolean`: injects the total-height measurement into a single child instead of rendering the default `Animated.View`
 
-  const containerStyle = useAnimatedStyle(() => {
-    const translateY = interpolate(
-      progress.value,
-      [0, 1],
-      [0, -progressThreshold],
-      Extrapolation.CLAMP
-    );
-    return { transform: [{ translateY }] };
-  });
+Use `asChild` when you want to inject the total-height measurement into a single child instead of rendering the default `Animated.View`.
 
-  return (
-    <AnimatedHeaderBase onLayout={measureTotalHeight} style={containerStyle}>
-      <Animated.View onLayout={measureDynamic}>
-        {/* custom animated header content below the native header */}
-      </Animated.View>
-      <View>{/* sticky part */}</View>
-    </AnimatedHeaderBase>
-  );
-}
-```
+### `HeaderMotion.Header.Dynamic`
 
-## API
+Marks the part of the header whose layout should define the collapsible distance.
 
-The package exports a default compound component plus hooks, types, and a couple base components.
+Use this for the section that visually disappears during collapse.
 
-### `HeaderMotion` (default export)
+Props:
 
-`HeaderMotion` is a compound component:
+- all normal `Animated.View` props in default mode: use these as you would on any animated view
+- `asChild?: boolean`: injects the dynamic measurement into a single child instead of rendering the default `Animated.View`
 
-- `HeaderMotion` (provider)
-- `HeaderMotion.Header` (bridge for navigation headers)
-- `HeaderMotion.ScrollView` (pre-wired Animated.ScrollView)
-- `HeaderMotion.FlatList` (pre-wired Animated.FlatList)
-- `HeaderMotion.ScrollManager` (render-prop API for custom scrollables)
+### `HeaderMotion.Bridge`
 
-#### Props
+Reads the current HeaderMotion context and exposes it through a render function.
 
-- `progressThreshold?: number | (measuredDynamic: number) => number`
-  - Defines how many pixels correspond to `progress` going from `0` to `1`.
-  - If you pass a function, it uses the value measured from `measureDynamic`.
-- `measureDynamic?: (e) => number`
-  - What value to read from the `onLayout` event (defaults to `height`).
-- `measureDynamicMode?: 'mount' | 'update'`
-  - Whether `measureDynamic` updates only once or on every layout recalculation.
-- `activeScrollId?: SharedValue<string>`
-  - Enables multi-scroll orchestration (tabs/pager).
-- `progressExtrapolation?: ExtrapolationType`
-  - Controls how progress behaves outside the threshold range (useful for overscroll).
+Use it to move the context into a navigation-rendered header subtree.
 
-#### `HeaderMotion.Header`
+Props:
 
-Render-prop component that passes motion progress props to a header you render via navigation.
+- `children: (value) => ReactNode`: receives the bridged HeaderMotion context value that should usually be passed into `HeaderMotion.NavigationBridge`
 
-```tsx
-<HeaderMotion.Header>
-	{(headerProps) => /* pass headerProps into navigation header */}
-</HeaderMotion.Header>
-```
+### `HeaderMotion.NavigationBridge`
 
-Use this instead of `useMotionProgress()` when your header is rendered by React Navigation / Expo Router.
+Re-provides a previously captured HeaderMotion context value in another subtree.
 
-#### `HeaderMotion.ScrollView`
+Use it together with `HeaderMotion.Bridge`.
 
-Animated ScrollView wired with:
+Props:
 
-- `onScroll` handler
-- `ref`
-- automatic `paddingTop` based on measured header height
+- `value`: the bridged HeaderMotion context captured by `HeaderMotion.Bridge`
+- `children`: the subtree that should regain access to HeaderMotion context
 
-Supports `scrollId?: string` for multi-scroll scenarios.
+### `HeaderMotion.ScrollView`
 
-#### `HeaderMotion.FlatList`
+Pre-wired `Animated.ScrollView`.
 
-Animated FlatList wired similarly to the ScrollView.
+Supports:
 
-Supports `scrollId?: string` for multi-scroll scenarios.
+- `scrollId?: string`: unique id for this scrollable when one header is shared across multiple scrollables
+- `headerOffsetStrategy?: 'padding' | 'margin' | 'top' | 'translate' | 'none'`: controls how content is pushed below the measured header
+- `ensureScrollableContentMinHeight?: boolean`: experimental fallback for short content that otherwise could not scroll far enough to collapse the header fully
+- `animatedRef?: AnimatedRef`: lets you reuse your own animated ref instead of letting HeaderMotion create one
 
-#### `HeaderMotion.ScrollManager`
+### `HeaderMotion.FlatList`
 
-Render-prop API for custom scrollables (pager pages, 3rd party lists, etc.).
+Pre-wired `Animated.FlatList`.
 
-If you use `HeaderMotion.ScrollManager` directly for custom integrations, pass refresh-related props to `ScrollManager` (instead of your inner scrollable):
+Supports the same HeaderMotion-specific props as `HeaderMotion.ScrollView`.
 
-- `refreshControl`
-- `refreshing`
-- `onRefresh`
-- optional `progressViewOffset` if you want to force your offset.
+### `createHeaderMotionScrollable(Component, options?)`
+
+Factory for creating reusable HeaderMotion-aware wrappers around custom scrollables.
 
-This is required, as the positioning of scrollables is affecting Refresh Control and has to be coupled with the header heights.
+Prefer this over the scroll managers whenever it is enough.
+
+Useful options:
+
+- `displayName`: custom component name shown in React DevTools
+- `isComponentAnimated`: set this when the input component is already animated and should not be wrapped again
+- `contentContainerMode: 'children' | 'renderScrollComponent'`: tells HeaderMotion how to inject content offsetting for that scrollable shape
+
+Use:
+
+- `'children'` for ScrollView-like components
+- `'renderScrollComponent'` for FlatList-like components
+
+Examples:
+
+`FlashList`
 
 ```tsx
-<HeaderMotion.ScrollManager scrollId="A">
-  {(
-    scrollableProps,
-    { originalHeaderHeight, minHeightContentContainerStyle }
-  ) => (
-    <Animated.ScrollView
-      {...scrollableProps}
-      contentContainerStyle={[
-        minHeightContentContainerStyle,
-        { paddingTop: originalHeaderHeight },
-      ]}
-    />
-  )}
-</HeaderMotion.ScrollManager>
+import { FlashList } from '@shopify/flash-list';
+import { createHeaderMotionScrollable } from 'react-native-header-motion';
+
+const HeaderMotionFlashList = createHeaderMotionScrollable(FlashList, {
+  displayName: 'HeaderMotionFlashList',
+  contentContainerMode: 'renderScrollComponent',
+});
 ```
 
-Refresh example with explicit props on `ScrollManager`:
+`LegendList`
 
 ```tsx
-<HeaderMotion.ScrollManager
-  scrollId="A"
-  refreshing={refreshing}
-  onRefresh={onRefresh}
->
-  {(
-    { onScroll, refreshControl: managedRefreshControl, ...scrollableProps },
-    { originalHeaderHeight, minHeightContentContainerStyle }
-  ) => (
-    <Animated.ScrollView
-      {...scrollableProps}
-      onScroll={onScroll}
-      refreshControl={managedRefreshControl}
-      contentContainerStyle={[
-        minHeightContentContainerStyle,
-        { paddingTop: originalHeaderHeight },
-      ]}
-    />
-  )}
-</HeaderMotion.ScrollManager>
+import { LegendList } from '@legendapp/list';
+import { createHeaderMotionScrollable } from 'react-native-header-motion';
+
+const HeaderMotionLegendList = createHeaderMotionScrollable(LegendList, {
+  displayName: 'HeaderMotionLegendList',
+  isComponentAnimated: true,
+  contentContainerMode: 'renderScrollComponent',
+});
 ```
 
+### `HeaderMotion.ScrollManager`
+
+Render-prop fallback for complex custom integrations.
+
+Most code should prefer `createHeaderMotionScrollable()`.
+
+Use `ScrollManager` only when you need a custom composition that the factory API cannot express cleanly.
+
+Props:
+
+- `scrollId?: string`: unique id for this scrollable when one header is shared across multiple scrollables
+- `children`: render function that receives `scrollableProps` and `headerMotionContext`
+- plus the same refresh / ref options accepted by `useScrollManager()`
+
 ### Hooks
 
 #### `useMotionProgress()`
 
 Returns:
 
-- `progress` (`SharedValue<number>`)
-- `progressThreshold` (`number`)
-- `measureTotalHeight` (`onLayout` callback)
-- `measureDynamic` (`onLayout` callback)
+- `progress`: `SharedValue<number>` that typically moves from `0` at expanded state to `1` at collapsed state
+- `progressThreshold`: `SharedValue<number>` representing the collapse distance in pixels
 
-Only use inside the `HeaderMotion` provider tree.
+This is the primary animation hook for header UI.
 
-#### `useScrollManager(scrollId?)`
+#### `useHeaderMotionBridge()`
 
-Lower-level orchestration hook that powers the component APIs. Returns:
+Returns the full internal bridge value.
 
-- `scrollableProps`: `{ onScroll, scrollEventThrottle, ref }`
-- `headerMotionContext`:
-  - `originalHeaderHeight`
-  - `minHeightContentContainerStyle` (helps when content is shorter than the threshold)
+Most app code should not need this. Prefer `useMotionProgress()` unless you are explicitly bridging context across a tree boundary.
+
+Returns:
+
+- full HeaderMotion context value, including measurement callbacks and scroll synchronization internals
 
 #### `useActiveScrollId(initialId)`
 
-Helper for multi-scroll scenarios (tabs/pager). Returns:
+Returns:
+
+- `{ state, sv }`: `state` is the React value for UI logic, `sv` is the matching shared value for HeaderMotion
+- setter function: updates both in sync
+
+Use this for multi-scroll setups.
+
+#### `useScrollManager(scrollId?, options?)`
+
+Hook-level fallback for complex custom scrollables.
+
+Most code should prefer `createHeaderMotionScrollable()`.
+
+Parameters:
+
+- `scrollId`: unique id for this scrollable when one header is shared across multiple scrollables
+- `options`: optional ref, refresh, and event-handler configuration
+
+Returns:
+
+- `scrollableProps`: props to spread onto the scrollable itself, including the managed ref, scroll handlers, and resolved refresh control
+- `headerMotionContext`: layout values for offsetting content below the measured header, including `originalHeaderHeight` and optional `contentContainerMinHeight`
+
+## Notes
 
-- `[active, setActive]`
-- `active.state` (React state)
-- `active.sv` (SharedValue)
+### Why `HeaderMotion.Header` is absolute by default
 
-### Base components
+Headers rendered by navigation are often easier to animate and interact with when they are visually overlayed above content rather than participating in normal layout flow.
 
-#### `HeaderBase`
+That is why `overlay` defaults to `true`.
 
-Non-animated absolutely positioned header base.
+Disable it only when you intentionally want the header in normal layout flow.
 
-#### `AnimatedHeaderBase`
+### `ensureScrollableContentMinHeight` (experimental)
 
-Reanimated-powered, absolutely positioned header base.
+This is available on the pre-wired scrollables and the custom-scrollable APIs.
 
-### Types
+It is useful when content is too short to naturally scroll through the full collapse distance.
 
-- `WithCollapsibleHeaderProps` – convenience type for headers using motion progress props.
-- `WithCollapsiblePagedHeaderProps` – like above, plus `activeTab` and `onTabChange`.
+This feature is still experimental.
 
-## Additional notes
+### Scroll event frequency
 
-### Refresh Control (v.0.3.0+)
+`scrollEventThrottle` is intentionally not managed by this library.
 
-Refresh control support was improved in `v0.3.0+`.
+Pass it directly to your scrollable when you need it.
 
-- If you use `HeaderMotion.ScrollView` or `HeaderMotion.FlatList`, your refresh-control usage stays the same as in React Native.
-- If you use `HeaderMotion.ScrollManager` directly for custom integrations, pass refresh-related props to `ScrollManager`:
-  - `refreshControl`
-  - `refreshing`
-  - `onRefresh`
-  - optional `progressViewOffset`
+If you run into performance issues, try adjusting `scrollEventThrottle` to reduce how many scroll events this library processes.
 
-This is important because scrollable positioning affects refresh-control behavior and needs to stay coupled with measured header height.
+### Refresh control
 
-#### Platform support note:
+If you use `HeaderMotion.ScrollView` or `HeaderMotion.FlatList`, your refresh-control usage stays the same as in React Native.
+
+If you use `HeaderMotion.ScrollManager` directly for custom integrations, pass refresh-related props to `ScrollManager` itself:
+
+- `refreshControl`
+- `refreshing`
+- `onRefresh`
+- optional `progressViewOffset`
+
+This matters because scrollable positioning affects refresh-control behavior and needs to stay coupled with the measured header height.
+
+Platform support note:
 
 - Support for Refresh Control is currently partial.
 - Android works well with the current implementation.
@@ -527,15 +581,26 @@ This is important because scrollable positioning affects refresh-control behavio
 - Other iOS approaches tried so far introduced different issues.
 - Additional iOS support improvements are planned for future releases.
 
+## Examples
+
+See the example app in [`example/`](./example/).
+
+Useful files:
+
+- [`example/src/app/simple.tsx`](./example/src/app/simple.tsx)
+- [`example/src/app/flashlist.tsx`](./example/src/app/flashlist.tsx)
+- [`example/src/app/legend-list.tsx`](./example/src/app/legend-list.tsx)
+- [`example/src/app/pager-header-pan.tsx`](./example/src/app/pager-header-pan.tsx)
+- [`example/src/app/collapsible-pager.tsx`](./example/src/app/collapsible-pager.tsx)
+
 ## Contributing
 
-- Development workflow: see [CONTRIBUTING.md](CONTRIBUTING.md)
-- Code of conduct: see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+Development workflow: see [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+Code of conduct: see [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
 
 ## License
 
 MIT
 
----
-
-Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
+Made with [`create-react-native-library`](https://github.com/callstack/react-native-builder-bob)