react-native-header-motion 0.1.0

package/package.json

@@ -0,0 +1,164 @@
+{
+  "name": "react-native-header-motion",
+  "version": "0.1.0",
+  "description": "Smooth, animated collapsible headers with scroll-based motion control in React Native",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-header-motion-example",
+    "clean": "del-cli lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "test": "jest",
+    "release": "release-it --only-version",
+    "lint": "eslint \"**/*.{js,ts,tsx}\""
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pawicao/react-native-header-motion.git"
+  },
+  "author": "Oskar Pawica <pawicao@gmail.com> (https://github.com/pawicao)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/pawicao/react-native-header-motion/issues"
+  },
+  "homepage": "https://github.com/pawicao/react-native-header-motion#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.8.1",
+    "@eslint/compat": "^1.3.2",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.35.0",
+    "@react-native/babel-preset": "0.83.0",
+    "@react-native/eslint-config": "0.83.0",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.1.12",
+    "commitlint": "^19.8.1",
+    "del-cli": "^6.0.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^29.7.0",
+    "lefthook": "^2.0.3",
+    "prettier": "^2.8.8",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-builder-bob": "^0.40.17",
+    "react-native-reanimated": "4.1.1",
+    "react-native-worklets": "0.5.1",
+    "release-it": "^19.0.4",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-reanimated": ">=4.0.0",
+    "react-native-worklets": ">=0.4.0"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "jest": {
+    "preset": "react-native",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "create-react-native-library": {
+    "type": "library",
+    "languages": "js",
+    "tools": [
+      "jest",
+      "lefthook",
+      "release-it",
+      "eslint"
+    ],
+    "version": "0.56.0"
+  }
+}

package/src/components/FlatList.tsx

@@ -0,0 +1,72 @@
+import { forwardRef, type ComponentProps, type ComponentRef } from 'react';
+import { ScrollView, type ScrollViewProps } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { HeaderMotionScrollManager } from './ScrollManager';
+
+type AnimatedFlatListProps<T = any> = ComponentProps<
+  typeof Animated.FlatList<T>
+>;
+
+export type HeaderMotionFlatListProps<T = any> = AnimatedFlatListProps<T> & {
+  /**
+   * Optional unique identifier for this scroll view.
+   * Use this when you have multiple scroll views (e.g. in tabs) to track them separately.
+   */
+  scrollId?: string;
+};
+
+/**
+ * Animated FlatList component that integrates with HeaderMotion.
+ * Automatically handles scroll tracking and header animation synchronization.
+ * Must be used within a HeaderMotion component.
+ *
+ * @template T - The type of items in the FlatList
+ *
+ * @example
+ * ```tsx
+ * <HeaderMotion>
+ *   <HeaderMotion.FlatList
+ *     data={items}
+ *     renderItem={({ item }) => <Text>{item}</Text>}
+ *   />
+ * </HeaderMotion>
+ * ```
+ */
+export function HeaderMotionFlatList<T = any>({
+  scrollId,
+  ...props
+}: HeaderMotionFlatListProps<T>) {
+  return (
+    <HeaderMotionScrollManager scrollId={scrollId}>
+      {(
+        { onScroll, ...scrollViewProps },
+        { originalHeaderHeight, minHeightContentContainerStyle }
+      ) => (
+        <Animated.FlatList
+          {...scrollViewProps}
+          {...props}
+          onScroll={onScroll}
+          renderScrollComponent={(propsz) => (
+            <AnimatedScrollContainer {...propsz} />
+          )}
+          contentContainerStyle={[
+            minHeightContentContainerStyle,
+            { paddingTop: originalHeaderHeight },
+            props.contentContainerStyle,
+          ]}
+        />
+      )}
+    </HeaderMotionScrollManager>
+  );
+}
+
+const AnimatedScrollContainer = forwardRef<
+  ComponentRef<typeof ScrollView>,
+  ScrollViewProps
+>(({ children, contentContainerStyle, ...rest }, ref) => {
+  return (
+    <ScrollView {...rest} ref={ref}>
+      <Animated.View style={contentContainerStyle}>{children}</Animated.View>
+    </ScrollView>
+  );
+});

package/src/components/Header.tsx

@@ -0,0 +1,30 @@
+import { useMotionProgress } from '../hooks/useMotionProgress';
+import type { MotionProgress } from '../types';
+import type { ReactNode } from 'react';
+
+type HeaderRenderChildren = (props: MotionProgress) => ReactNode;
+
+export interface HeaderMotionHeaderProps {
+  /**
+   * Render function that receives motion progress props.
+   * Use this to animate your header based on scroll progress and to provide measurement functions to the elements of the header.
+   */
+  children: HeaderRenderChildren;
+}
+
+/**
+ * Header component for providing motion progress properties to animated headers.
+ * Must be used within a HeaderMotion component.
+ *
+ * Use to pass props to the header components in React Navigation / Expo Router, which cannot access HeaderMotion's context and `useMotionProgress` otherwise.`
+ */
+export function HeaderMotionHeader({ children }: HeaderMotionHeaderProps) {
+  if (typeof children !== 'function') {
+    throw new Error(
+      'HeaderMotion.Header only accepts render function as the only child.'
+    );
+  }
+
+  const motionProgressProps = useMotionProgress();
+  return children(motionProgressProps);
+}

package/src/components/HeaderBase.tsx

@@ -0,0 +1,51 @@
+import { StyleSheet, View, type ViewProps } from 'react-native';
+import Animated, { type AnimatedProps } from 'react-native-reanimated';
+
+export type HeaderBaseProps = ViewProps;
+export type AnimatedHeaderBaseProps = AnimatedProps<ViewProps>;
+
+/**
+ * Base header component with absolute positioning.
+ * Provides a foundation for building headers that need to be positioned absolutely.
+ *
+ * @example
+ * ```tsx
+ * <HeaderBase
+ *   onLayout={measureTotalHeight}
+ * >
+ *   ...
+ * </HeaderBase>
+ * ```
+ */
+export function HeaderBase({ style, ...rest }: HeaderBaseProps) {
+  return <View style={[style, styles.container]} {...rest} />;
+}
+
+/**
+ * Animated version of HeaderBase using Reanimated's Animated.View.
+ * Use this when you need to animate the header based on scroll progress.
+ *
+ * @example
+ * ```tsx
+ * <AnimatedHeaderBase
+ *   onLayout={measureTotalHeight}
+ *   style={[{ paddingTop: insets.top }, animatedStyle]}
+ * >
+ *   ...
+ * </AnimatedHeaderBase>
+ * ```
+ */
+export function AnimatedHeaderBase({
+  style,
+  ...rest
+}: AnimatedHeaderBaseProps) {
+  return <Animated.View style={[style, styles.container]} {...rest} />;
+}
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+  },
+});

package/src/components/HeaderMotion.tsx

@@ -0,0 +1,183 @@
+import { useCallback, useMemo, useState } from 'react';
+import {
+  Extrapolation,
+  interpolate,
+  useAnimatedReaction,
+  useDerivedValue,
+  useSharedValue,
+  type ExtrapolationType,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { HeaderMotionContext } from '../context';
+import type { ReactNode } from 'react';
+import type {
+  MeasureAnimatedHeader,
+  MeasureAnimatedHeaderAndSet,
+  ProgressThreshold,
+  ScrollValues,
+} from '../types';
+import {
+  DEFAULT_MEASURE_DYNAMIC,
+  DEFAULT_PROGRESS_THRESHOLD,
+  DEFAULT_SCROLL_ID,
+  getInitialScrollValue,
+} from '../utils';
+
+export interface HeaderMotionProps<T extends string> {
+  /**
+   * The threshold at which the header animation completes (reaches progress = 1).
+   * Can be a fixed number or a function that calculates based on the result of {@link measureDynamic}.
+   *
+   * Defaults to a function that returns the return value of `measureDynamic` unchanged.
+   */
+  progressThreshold?: ProgressThreshold;
+  /**
+   * Function to measure a dimension of choice of the animated element of the header.
+   *
+   * Receives the layout change event from React Native.
+   *
+   * This function can be further accessed when rendering headers from `HeaderMotion.Header` or `useMotionProgress`  - should be passed to the `onLayout` prop of such. If used, can be used for dynamic calculation of the {@link progressThreshold}.
+   *
+   * Defaults to measuring the height from the event.
+   */
+  measureDynamic?: MeasureAnimatedHeader;
+  /**
+   * Mode for measuring dynamic header height.
+   * - 'mount': Only measure once on mount
+   * - 'update': Update measurement on every layout recalculation of the component that {@link measureDynamic} was provided to as the `onLayout` property
+   * @default 'mount'
+   */
+  measureDynamicMode?: 'update' | 'mount';
+  /**
+   * Shared value for tracking the active scroll ID in multi-scroll scenarios (e.g. tabs).
+   * When provided, the header animation will sync across multiple scroll views.
+   */
+  activeScrollId?: SharedValue<T>;
+  /**
+   * Extrapolation type for the progress animation.
+   * Controls how the progress value behaves outside the threshold range.
+   *
+   * You may want to modify it to achieve some animations for the overscroll scenarios.
+   * @default Extrapolation.CLAMP
+   */
+  progressExtrapolation?: ExtrapolationType;
+  /** Child components that will have access to the header motion context */
+  children: ReactNode;
+}
+
+/**
+ * Context provider component for HeaderMotion.
+ * Manages header animation state and provides it to child components via context.
+ * @template T - The type of scroll ID string
+ */
+function HeaderMotionContextProvider<T extends string>({
+  progressThreshold = DEFAULT_PROGRESS_THRESHOLD,
+  measureDynamic = DEFAULT_MEASURE_DYNAMIC,
+  measureDynamicMode = 'mount',
+  activeScrollId,
+  progressExtrapolation = Extrapolation.CLAMP,
+  children,
+}: HeaderMotionProps<T>) {
+  const [dynamicMeasurement, setDynamicMeasurement] = useState<
+    number | undefined
+  >(undefined);
+  const [originalHeaderHeight, setOriginalHeaderHeight] = useState(0);
+
+  const setOrUpdateDynamicMeasurement =
+    useCallback<MeasureAnimatedHeaderAndSet>(
+      (e) => {
+        const measured = measureDynamic(e);
+        setDynamicMeasurement((prevMeasurement) => {
+          if (prevMeasurement !== undefined && measureDynamicMode === 'mount') {
+            return prevMeasurement;
+          }
+
+          return measured;
+        });
+      },
+      [measureDynamicMode, measureDynamic, setDynamicMeasurement]
+    );
+
+  const calculatedProgressThreshold = useMemo(() => {
+    if (typeof progressThreshold === 'number') {
+      return progressThreshold;
+    }
+
+    if (dynamicMeasurement === undefined) {
+      return Infinity;
+    }
+    return progressThreshold(dynamicMeasurement);
+  }, [dynamicMeasurement, progressThreshold]);
+
+  const measureTotalHeight = useCallback<MeasureAnimatedHeaderAndSet>(
+    (e) => {
+      const measuredValue = e.nativeEvent.layout.height;
+      setOriginalHeaderHeight(measuredValue);
+    },
+    [setOriginalHeaderHeight]
+  );
+
+  const scrollValues = useSharedValue<ScrollValues>({
+    [DEFAULT_SCROLL_ID]: getInitialScrollValue(),
+  });
+
+  useAnimatedReaction(
+    () => activeScrollId?.get(),
+    (id) => {
+      if (!id || scrollValues.get()[id]) {
+        return;
+      }
+
+      scrollValues.modify((value) => {
+        (value as ScrollValues)[id] = getInitialScrollValue();
+        return value;
+      });
+    }
+  );
+
+  const progress = useDerivedValue(() => {
+    const id = activeScrollId?.get() ?? DEFAULT_SCROLL_ID;
+    const scrollValue = scrollValues.get()[id];
+
+    if (!scrollValue) {
+      return 0;
+    }
+
+    const { min, current } = scrollValue;
+    return interpolate(
+      current,
+      [min, min + calculatedProgressThreshold],
+      [0, 1],
+      progressExtrapolation
+    );
+  });
+
+  const ctxValue = useMemo(
+    () => ({
+      progress,
+      originalHeaderHeight,
+      measureDynamic: setOrUpdateDynamicMeasurement,
+      measureTotalHeight,
+      progressThreshold: calculatedProgressThreshold,
+      scrollValues,
+      activeScrollId: activeScrollId as SharedValue<string> | undefined,
+    }),
+    [
+      originalHeaderHeight,
+      progress,
+      measureTotalHeight,
+      setOrUpdateDynamicMeasurement,
+      scrollValues,
+      activeScrollId,
+      calculatedProgressThreshold,
+    ]
+  );
+
+  return (
+    <HeaderMotionContext.Provider value={ctxValue}>
+      {children}
+    </HeaderMotionContext.Provider>
+  );
+}
+
+export { HeaderMotionContextProvider };

package/src/components/ScrollManager.tsx

@@ -0,0 +1,58 @@
+import { useScrollManager } from '../hooks';
+import type { ScrollManagerConfig } from '../types';
+import type { ReactNode } from 'react';
+
+type ScrollManagerRenderChildren = (
+  scrollableProps: ScrollManagerConfig['scrollableProps'],
+  options: ScrollManagerConfig['headerMotionContext']
+) => ReactNode;
+
+export interface HeaderMotionScrollManagerProps {
+  /**
+   * Optional unique identifier for this scroll view.
+   * Use this when you have multiple scroll views (e.g., in tabs) to track them separately.
+   */
+  scrollId?: string;
+  /**
+   * Render function that receives scroll props and header context.
+   * Use this to create custom scroll implementations that integrate with HeaderMotion.
+   */
+  children: ScrollManagerRenderChildren;
+}
+
+/**
+ * ScrollManager component that provides scroll tracking functionality for custom scroll implementations. Uses {@link useScrollManager} under the hood.
+ * Must be used within a HeaderMotion component.
+ *
+ * This is useful when you need to use a scroll component that isn't directly supported
+ * (like a custom scroll view or third-party list components).
+ *
+ * @example
+ * ```tsx
+ * <HeaderMotion>
+ *   <HeaderMotion.ScrollManager>
+ *     {(scrollableProps, { originalHeaderHeight }) => (
+ *       <CustomScrollView {...scrollableProps}>
+ *         <View style={{ paddingTop: originalHeaderHeight }}>
+ *           <Text>Content</Text>
+ *         </View>
+ *       </CustomScrollView>
+ *     )}
+ *   </HeaderMotion.ScrollManager>
+ * </HeaderMotion>
+ * ```
+ */
+export function HeaderMotionScrollManager({
+  children,
+  scrollId,
+}: HeaderMotionScrollManagerProps) {
+  if (typeof children !== 'function') {
+    throw new Error(
+      'HeaderMotion.ScrollManager only accepts render function as the only child.'
+    );
+  }
+
+  const { scrollableProps, headerMotionContext } = useScrollManager(scrollId);
+
+  return children(scrollableProps, headerMotionContext);
+}

package/src/components/ScrollView.tsx

@@ -0,0 +1,58 @@
+import Animated, {
+  type AnimatedScrollViewProps,
+} from 'react-native-reanimated';
+import { HeaderMotionScrollManager } from './ScrollManager';
+
+export type HeaderMotionScrollViewProps = AnimatedScrollViewProps & {
+  /**
+   * Optional unique identifier for this scroll view.
+   * Use this when you have multiple scroll views (e.g. in tabs) to track them separately.
+   */
+  scrollId?: string;
+};
+
+/**
+ * Animated ScrollView component that integrates with HeaderMotion.
+ * Automatically handles scroll tracking and header animation synchronization.
+ * Must be used within a HeaderMotion component.
+ *
+ * @example
+ * ```tsx
+ * <HeaderMotion>
+ *   <HeaderMotion.ScrollView>
+ *     <MyScrollableContent />
+ *   </HeaderMotion.ScrollView>
+ * </HeaderMotion>
+ * ```
+ */
+export function HeaderMotionScrollView({
+  scrollId,
+  children,
+  contentContainerStyle,
+  ...props
+}: HeaderMotionScrollViewProps) {
+  return (
+    <HeaderMotionScrollManager scrollId={scrollId}>
+      {(
+        { onScroll, ...scrollViewProps },
+        { originalHeaderHeight, minHeightContentContainerStyle }
+      ) => (
+        <Animated.ScrollView
+          {...scrollViewProps}
+          {...props}
+          onScroll={onScroll}
+        >
+          <Animated.View
+            style={[
+              minHeightContentContainerStyle,
+              { paddingTop: originalHeaderHeight },
+              contentContainerStyle,
+            ]}
+          >
+            {children}
+          </Animated.View>
+        </Animated.ScrollView>
+      )}
+    </HeaderMotionScrollManager>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,6 @@
+export * from './FlatList';
+export * from './Header';
+export * from './HeaderBase';
+export * from './HeaderMotion';
+export * from './ScrollManager';
+export * from './ScrollView';

package/src/context.ts

@@ -0,0 +1,20 @@
+import { createContext } from 'react';
+import { type SharedValue } from 'react-native-reanimated';
+import type {
+  MeasureAnimatedHeaderAndSet,
+  Progress,
+  ScrollValues,
+} from './types';
+
+interface HeaderMotionContextType {
+  progress: Progress;
+  measureTotalHeight: MeasureAnimatedHeaderAndSet;
+  measureDynamic: MeasureAnimatedHeaderAndSet;
+  scrollValues: SharedValue<ScrollValues>;
+  activeScrollId: SharedValue<string> | undefined;
+  progressThreshold: number;
+  originalHeaderHeight: number;
+}
+
+export const HeaderMotionContext =
+  createContext<HeaderMotionContextType | null>(null);

package/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export * from './useActiveScrollId';
+export * from './useMotionProgress';
+export * from './useScrollManager';