feat: createHeaderMotionScrollable (#14)

* feat: createHeaderMotionScrollable (WIP - codex's work for now)

* chore: simplify createHeaderMotionScrollable

* chore: codex-powered TS magic for createHeaderMotionScrollable

* chore: reorganize types

* chore: fix lint warnings and extend tests

* chore: do not infer FlatList and ScrollView exported types

Author: pawicao

.gitignore

@@ -84,3 +84,6 @@ android/generated
 
 # React Native Nitro Modules
 nitrogen/
+
+example/ios
+example/android

README.md

@@ -118,7 +118,8 @@ You can use either style; pick based on your integration needs:
 - Prefer **components** when you want a “batteries included” wiring:
 
   - `HeaderMotion.ScrollView` / `HeaderMotion.FlatList` for common scrollables
-  - `HeaderMotion.ScrollManager` for custom scrollables via render-props
+  - `createHeaderMotionScrollable()` for reusable wrappers around custom scrollables
+  - `HeaderMotion.ScrollManager` for one-off custom scrollables via render-props
 
 - Prefer **hooks** when you want to build your own wrappers:
   - `useScrollManager()` (same engine as `HeaderMotion.ScrollManager`, but hook-based)
@@ -393,6 +394,7 @@ The package exports a default compound component plus hooks, types, and a couple
 - `HeaderMotion.Header` (bridge for navigation headers)
 - `HeaderMotion.ScrollView` (pre-wired Animated.ScrollView)
 - `HeaderMotion.FlatList` (pre-wired Animated.FlatList)
+- `createHeaderMotionScrollable` (factory for reusable custom scrollables)
 - `HeaderMotion.ScrollManager` (render-prop API for custom scrollables)
 
 #### Props
@@ -449,6 +451,41 @@ Supports:
 - `headerOffsetStrategy?: 'padding' | 'margin' | 'top' | 'translate' | 'none'`
 - `ensureScrollableContentMinHeight?: boolean`
 
+#### `createHeaderMotionScrollable(Component, options?)`
+
+Named export for building reusable scrollable wrappers on top of `useScrollManager()`.
+This is the same abstraction used internally by `HeaderMotion.ScrollView` and `HeaderMotion.FlatList`.
+
+Returned components support:
+
+- `scrollId?: string`
+- `headerOffsetStrategy?: 'padding' | 'margin' | 'top' | 'translate' | 'none'`
+- `ensureScrollableContentMinHeight?: boolean`
+
+Use:
+
+- `contentContainerMode: 'children'` for ScrollView-like components
+- `contentContainerMode: 'renderScrollComponent'` for FlatList-like components
+- `isComponentAnimated: true` when you pass an already animated component
+
+The returned component keeps the wrapped component's prop shape, and list-like
+generic components preserve item inference at usage time. Users do not need to
+pass generics to `createHeaderMotionScrollable()` itself.
+
+By default, the factory wraps the provided component with
+`Animated.createAnimatedComponent()`.
+
+Example:
+
+```tsx
+import { FlashList } from '@shopify/flash-list';
+import { createHeaderMotionScrollable } from 'react-native-header-motion';
+
+const HeaderMotionFlashList = createHeaderMotionScrollable(FlashList, {
+  displayName: 'HeaderMotionFlashList',
+});
+```
+
 #### `HeaderMotion.ScrollManager`
 
 Render-prop API for custom scrollables (pager pages, 3rd party lists, etc.).

example/app.json

@@ -27,6 +27,6 @@
       "favicon": "./assets/favicon.png",
       "bundler": "metro"
     },
-    "plugins": ["expo-router"]
+    "plugins": ["expo-dev-client", "expo-router"]
   }
 }

example/package.json

@@ -4,14 +4,17 @@
   "main": "expo-router/entry",
   "scripts": {
     "start": "expo start",
-    "android": "expo start --android",
-    "ios": "expo start --ios",
+    "android": "expo run:android",
+    "ios": "expo run:ios",
     "web": "expo start --web"
   },
   "dependencies": {
     "@expo/metro-runtime": "~55.0.6",
+    "@legendapp/list": "2.0.19",
+    "@shopify/flash-list": "2.3.0",
     "expo": "~55.0.7",
     "expo-constants": "~55.0.8",
+    "expo-dev-client": "~55.0.8",
     "expo-linking": "~55.0.7",
     "expo-router": "~55.0.6",
     "expo-status-bar": "~55.0.4",

example/src/app/flashlist.tsx

@@ -0,0 +1,55 @@
+import { ContentCard, ShowcaseCollapsibleHeader } from '@/components';
+import { FlashList } from '@shopify/flash-list';
+import HeaderMotion, {
+  createHeaderMotionScrollable,
+} from 'react-native-header-motion';
+import { Stack } from 'expo-router';
+
+type ListRow = {
+  index: number;
+  label: string;
+};
+
+const HeaderMotionFlashList = createHeaderMotionScrollable(FlashList, {
+  displayName: 'HeaderMotionFlashList',
+});
+
+export default function Screen() {
+  return (
+    <HeaderMotion>
+      <HeaderMotion.Header>
+        {(headerProps) => (
+          <Stack.Screen
+            options={{
+              header: () => (
+                <ShowcaseCollapsibleHeader
+                  {...headerProps}
+                  title="FlashList"
+                  subtitle="Shared factory wrapper"
+                  backgroundColor="#14532d"
+                />
+              ),
+            }}
+          />
+        )}
+      </HeaderMotion.Header>
+      <HeaderMotionFlashList
+        data={content}
+        keyExtractor={(item) => `${item.index}`}
+        renderItem={({ item }) => (
+          <ContentCard
+            index={item.index}
+            label={item.label}
+            backgroundColor="#dcfce7"
+            textColor="#14532d"
+          />
+        )}
+      />
+    </HeaderMotion>
+  );
+}
+
+const content: ListRow[] = Array.from({ length: 500 }, (_, k) => ({
+  index: k + 1,
+  label: 'FlashList Item',
+}));

example/src/app/flatlist-handlers.tsx

@@ -6,7 +6,7 @@ import HeaderMotion, {
 import { Stack } from 'expo-router';
 import type { ComponentProps } from 'react';
 import { useCallback, useRef } from 'react';
-import { FlatList, StyleSheet, View } from 'react-native';
+import { StyleSheet, View } from 'react-native';
 import Animated, {
   Extrapolation,
   interpolate,
@@ -16,7 +16,11 @@ import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
 type ListRow = { key: string; index: number };
 
-type FL = ComponentProps<typeof FlatList<ListRow>>;
+type FL = ComponentProps<typeof HeaderMotion.FlatList<ListRow>>;
+type FLFn<TKey extends keyof FL> = Extract<
+  Exclude<FL[TKey], undefined>,
+  (...args: any[]) => any
+>;
 
 const LIST_DATA: ListRow[] = Array.from({ length: 120 }, (_, k) => ({
   key: `row-${k}`,
@@ -37,7 +41,7 @@ export default function Screen() {
           />
         )}
       </HeaderMotion.Header>
-      <HeaderMotion.FlatList<ListRow>
+      <HeaderMotion.FlatList
         data={LIST_DATA}
         keyExtractor={(item) => item.key}
         renderItem={({ item }) => (
@@ -61,71 +65,62 @@ function useFlatListHandlerLoggers() {
     itemVisiblePercentThreshold: 35,
   }).current;
 
-  const onViewableItemsChanged = useCallback<
-    NonNullable<FL['onViewableItemsChanged']>
-  >((info) => {
-    console.log(prefix, 'onViewableItemsChanged', {
-      viewableCount: info.viewableItems.length,
-      changedCount: info.changed.length,
-      firstVisibleIndex: info.viewableItems[0]?.index,
-    });
-  }, []);
+  const onViewableItemsChanged = useCallback<FLFn<'onViewableItemsChanged'>>(
+    (info) => {
+      console.log(prefix, 'onViewableItemsChanged', {
+        viewableCount: info.viewableItems.length,
+        changedCount: info.changed.length,
+        firstVisibleIndex: info.viewableItems[0]?.index,
+      });
+    },
+    []
+  );
 
   return {
-    onScrollBeginDrag: useCallback<NonNullable<FL['onScrollBeginDrag']>>(
-      (e) => {
-        console.log(prefix, 'onScrollBeginDrag', {
-          y: e.nativeEvent.contentOffset.y,
-        });
-      },
-      []
-    ),
-    onScrollEndDrag: useCallback<NonNullable<FL['onScrollEndDrag']>>((e) => {
+    onScrollBeginDrag: useCallback<FLFn<'onScrollBeginDrag'>>((e) => {
+      console.log(prefix, 'onScrollBeginDrag', {
+        y: e.nativeEvent.contentOffset.y,
+      });
+    }, []),
+    onScrollEndDrag: useCallback<FLFn<'onScrollEndDrag'>>((e) => {
       console.log(prefix, 'onScrollEndDrag', {
         y: e.nativeEvent.contentOffset.y,
       });
     }, []),
-    onMomentumScrollBegin: useCallback<
-      NonNullable<FL['onMomentumScrollBegin']>
-    >((e) => {
+    onMomentumScrollBegin: useCallback<FLFn<'onMomentumScrollBegin'>>((e) => {
       console.log(prefix, 'onMomentumScrollBegin', {
         y: e.nativeEvent.contentOffset.y,
       });
     }, []),
-    onMomentumScrollEnd: useCallback<NonNullable<FL['onMomentumScrollEnd']>>(
-      (e) => {
-        console.log(prefix, 'onMomentumScrollEnd', {
-          y: e.nativeEvent.contentOffset.y,
-        });
-      },
-      []
-    ),
-    onContentSizeChange: useCallback<NonNullable<FL['onContentSizeChange']>>(
-      (w, h) => {
-        console.log(prefix, 'onContentSizeChange', { width: w, height: h });
-      },
-      []
-    ),
-    onScroll: useCallback<NonNullable<FL['onScroll']>>((e) => {
+    onMomentumScrollEnd: useCallback<FLFn<'onMomentumScrollEnd'>>((e) => {
+      console.log(prefix, 'onMomentumScrollEnd', {
+        y: e.nativeEvent.contentOffset.y,
+      });
+    }, []),
+    onContentSizeChange: useCallback<FLFn<'onContentSizeChange'>>((w, h) => {
+      console.log(prefix, 'onContentSizeChange', { width: w, height: h });
+    }, []),
+    onScroll: useCallback<FLFn<'onScroll'>>((e) => {
       console.log(prefix, 'onScroll', {
         y: e.nativeEvent.contentOffset.y,
       });
     }, []),
     viewabilityConfig,
     onViewableItemsChanged,
-    onEndReached: useCallback<NonNullable<FL['onEndReached']>>((info) => {
+    onEndReached: useCallback<FLFn<'onEndReached'>>((info) => {
       console.log(prefix, 'onEndReached', info);
     }, []),
     onEndReachedThreshold: 0.25,
-    onStartReached: useCallback<NonNullable<FL['onStartReached']>>((info) => {
+    onStartReached: useCallback<FLFn<'onStartReached'>>((info) => {
       console.log(prefix, 'onStartReached', info);
     }, []),
     onStartReachedThreshold: 0.25,
-    onScrollToIndexFailed: useCallback<
-      NonNullable<FL['onScrollToIndexFailed']>
-    >((info) => {
-      console.log(prefix, 'onScrollToIndexFailed', info);
-    }, []),
+    onScrollToIndexFailed: useCallback<FLFn<'onScrollToIndexFailed'>>(
+      (info) => {
+        console.log(prefix, 'onScrollToIndexFailed', info);
+      },
+      []
+    ),
   };
 }
 

example/src/app/flatlist.tsx

@@ -12,6 +12,11 @@ import Animated, {
 } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
+type ListRow = {
+  index: number;
+  label: string;
+};
+
 export default function Screen() {
   return (
     <HeaderMotion>
@@ -136,7 +141,7 @@ const styles = StyleSheet.create({
   },
 });
 
-const content = Array.from({ length: 500 }, (_, k) => ({
+const content: ListRow[] = Array.from({ length: 500 }, (_, k) => ({
   index: k + 1,
   label: 'FlatList Item',
 }));

example/src/app/index.tsx

@@ -25,6 +25,8 @@ const SECTIONS: ShowcaseSection[] = [
       { title: 'Color Interpolation', href: '/colors', icon: '🎨' },
       { title: 'Overscroll', href: '/overscroll', icon: '🔄' },
       { title: 'FlatList', href: '/flatlist', icon: '📋' },
+      { title: 'FlashList', href: '/flashlist', icon: '⚡️' },
+      { title: 'LegendList', href: '/legendlist', icon: '🧾' },
     ],
   },
   {
@@ -136,12 +138,7 @@ export default function Screen() {
         <Link href={item.href} asChild>
           <Pressable>
             {({ pressed }) => (
-              <View
-                style={[
-                  styles.itemRow,
-                  pressed && { backgroundColor: '#E5E7EB' },
-                ]}
-              >
+              <View style={[styles.itemRow, pressed && styles.itemRowPressed]}>
                 <Text style={styles.itemIcon}>{item.icon}</Text>
                 <Text style={styles.itemTitle}>{item.title}</Text>
                 <Text style={styles.chevron}>›</Text>
@@ -187,6 +184,9 @@ const styles = StyleSheet.create({
     paddingHorizontal: 20,
     backgroundColor: '#FFF',
   },
+  itemRowPressed: {
+    backgroundColor: '#E5E7EB',
+  },
   itemIcon: {
     fontSize: 20,
     marginRight: 14,