react-native-header-motion 0.2.0 → 1.0.0-alpha.0

package/src/components/HeaderMotion.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useState } from 'react';
+import { useCallback, useRef, useEffect, useMemo } from 'react';
 import {
   Extrapolation,
   interpolate,
@@ -11,6 +11,7 @@ import {
 import { HeaderMotionContext } from '../context';
 import type { ReactNode } from 'react';
 import type {
+  ScrollTo,
   MeasureAnimatedHeader,
   MeasureAnimatedHeaderAndSet,
   ProgressThreshold,
@@ -23,6 +24,32 @@ import {
   getInitialScrollValue,
 } from '../utils';
 
+const resolveScrollIdForProgress = (
+  scrollValues: ScrollValues,
+  activeScrollIdValue: string | undefined
+) => {
+  'worklet';
+
+  if (activeScrollIdValue) {
+    return activeScrollIdValue;
+  }
+
+  let onlyNonDefaultId: string | null = null;
+  for (const key in scrollValues) {
+    if (key === DEFAULT_SCROLL_ID) {
+      continue;
+    }
+
+    if (onlyNonDefaultId !== null) {
+      return DEFAULT_SCROLL_ID;
+    }
+
+    onlyNonDefaultId = key;
+  }
+
+  return onlyNonDefaultId ?? DEFAULT_SCROLL_ID;
+};
+
 export interface HeaderMotionProps<T extends string> {
   /**
    * The threshold at which the header animation completes (reaches progress = 1).
@@ -61,6 +88,10 @@ export interface HeaderMotionProps<T extends string> {
    * @default Extrapolation.CLAMP
    */
   progressExtrapolation?: ExtrapolationType;
+  /** Enables panning directly on the header surface.
+   * @default false
+   */
+  enableHeaderPan?: boolean;
   /** Child components that will have access to the header motion context */
   children: ReactNode;
 }
@@ -76,45 +107,67 @@ function HeaderMotionContextProvider<T extends string>({
   measureDynamicMode = 'mount',
   activeScrollId,
   progressExtrapolation = Extrapolation.CLAMP,
+  enableHeaderPan = false,
   children,
 }: HeaderMotionProps<T>) {
-  const [dynamicMeasurement, setDynamicMeasurement] = useState<
-    number | undefined
-  >(undefined);
-  const [originalHeaderHeight, setOriginalHeaderHeight] = useState(0);
+  const dynamicMeasurement = useSharedValue<number | undefined>(undefined);
+  const originalHeaderHeight = useSharedValue(0);
+  const progressThresholdValue = useSharedValue(
+    typeof progressThreshold === 'number' ? progressThreshold : Infinity
+  );
+  const headerPanMomentumOffset = useSharedValue<number | null>(null);
 
   const setOrUpdateDynamicMeasurement =
     useCallback<MeasureAnimatedHeaderAndSet>(
       (e) => {
+        const prevMeasurement = dynamicMeasurement.get();
+        if (prevMeasurement !== undefined && measureDynamicMode === 'mount') {
+          return;
+        }
+
         const measured = measureDynamic(e);
-        setDynamicMeasurement((prevMeasurement) => {
-          if (prevMeasurement !== undefined && measureDynamicMode === 'mount') {
-            return prevMeasurement;
-          }
+        if (prevMeasurement === measured) {
+          return;
+        }
 
-          return measured;
-        });
+        dynamicMeasurement.set(measured);
+        progressThresholdValue.set(
+          typeof progressThreshold === 'number'
+            ? progressThreshold
+            : progressThreshold(measured)
+        );
       },
-      [measureDynamicMode, measureDynamic, setDynamicMeasurement]
+      [
+        measureDynamicMode,
+        measureDynamic,
+        dynamicMeasurement,
+        progressThreshold,
+        progressThresholdValue,
+      ]
     );
 
-  const calculatedProgressThreshold = useMemo(() => {
+  useEffect(() => {
     if (typeof progressThreshold === 'number') {
-      return progressThreshold;
+      progressThresholdValue.set(progressThreshold);
+      return;
     }
 
-    if (dynamicMeasurement === undefined) {
-      return Infinity;
-    }
-    return progressThreshold(dynamicMeasurement);
-  }, [dynamicMeasurement, progressThreshold]);
+    const measured = dynamicMeasurement.get();
+    progressThresholdValue.set(
+      measured === undefined ? Infinity : progressThreshold(measured)
+    );
+  }, [progressThreshold, dynamicMeasurement, progressThresholdValue]);
 
   const measureTotalHeight = useCallback<MeasureAnimatedHeaderAndSet>(
     (e) => {
       const measuredValue = e.nativeEvent.layout.height;
-      setOriginalHeaderHeight(measuredValue);
+      if (originalHeaderHeight.get() === measuredValue) {
+        return;
+      }
+
+      originalHeaderHeight.set(measuredValue);
     },
-    [setOriginalHeaderHeight]
+    [originalHeaderHeight]
   );
 
   const scrollValues = useSharedValue<ScrollValues>({
@@ -136,8 +189,10 @@ function HeaderMotionContextProvider<T extends string>({
   );
 
   const progress = useDerivedValue(() => {
-    const id = activeScrollId?.get() ?? DEFAULT_SCROLL_ID;
-    const scrollValue = scrollValues.get()[id];
+    const values = scrollValues.get();
+    const id = resolveScrollIdForProgress(values, activeScrollId?.get());
+    const scrollValue = values[id];
+    const threshold = progressThresholdValue.get();
 
     if (!scrollValue) {
       return 0;
@@ -146,30 +201,51 @@ function HeaderMotionContextProvider<T extends string>({
     const { min, current } = scrollValue;
     return interpolate(
       current,
-      [min, min + calculatedProgressThreshold],
+      [min, min + threshold],
       [0, 1],
       progressExtrapolation
     );
   });
 
+  const scrollToRef = useRef<ScrollTo>(null);
+  // FUTURE: SharedValue-based scrollTo was removed for now because function updates
+  // were not propagating reliably, while it works for refs. Revisit later.
+  // We need to be updating the scrollTo on active scroll ID changes and doing it via state would cause re-renders.
+  // It's a bit of an anti-pattern to use refs for this as well, but I am yet to figure out a better way to pass those if SV won't work.
+  const animatedHeaderBaseProps = useMemo(
+    () => ({
+      enableHeaderPan,
+      scrollToRef,
+      headerPanMomentumOffset,
+    }),
+    [enableHeaderPan, headerPanMomentumOffset]
+  );
+
   const ctxValue = useMemo(
     () => ({
       progress,
       originalHeaderHeight,
       measureDynamic: setOrUpdateDynamicMeasurement,
       measureTotalHeight,
-      progressThreshold: calculatedProgressThreshold,
+      enableHeaderPan,
+      headerPanMomentumOffset,
+      animatedHeaderBaseProps,
+      progressThreshold: progressThresholdValue,
       scrollValues,
+      scrollToRef,
       activeScrollId: activeScrollId as SharedValue<string> | undefined,
     }),
     [
       originalHeaderHeight,
       progress,
       measureTotalHeight,
+      enableHeaderPan,
+      headerPanMomentumOffset,
+      animatedHeaderBaseProps,
       setOrUpdateDynamicMeasurement,
       scrollValues,
       activeScrollId,
-      calculatedProgressThreshold,
+      progressThresholdValue,
     ]
   );
 

package/src/components/ScrollManager.tsx

@@ -1,29 +1,26 @@
-import { useScrollManager } from '../hooks';
+import { useScrollManager, type UseScrollManagerOptions } from '../hooks';
 import type { ScrollManagerConfig } from '../types';
 import type { ReactNode } from 'react';
-import type { AnimatedRef } from 'react-native-reanimated';
+import type { InstanceOrElement } from 'react-native-reanimated/lib/typescript/commonTypes';
 
-type ScrollManagerRenderChildren = (
-  scrollableProps: ScrollManagerConfig['scrollableProps'],
-  options: ScrollManagerConfig['headerMotionContext']
+type ScrollManagerRenderChildren<TRef extends InstanceOrElement = any> = (
+  scrollableProps: ScrollManagerConfig<TRef>['scrollableProps'],
+  options: ScrollManagerConfig<TRef>['headerMotionContext']
 ) => ReactNode;
 
-export interface HeaderMotionScrollManagerProps {
+export interface HeaderMotionScrollManagerProps<
+  TRef extends InstanceOrElement = any
+> extends UseScrollManagerOptions<TRef> {
   /**
    * 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;
-  /**
-   * Optional animated ref to use for the scroll view.
-   * When provided, the scroll manager will use this ref instead of creating its own.
-   */
-  animatedRef?: AnimatedRef<any>;
   /**
    * Render function that receives scroll props and header context.
    * Use this to create custom scroll implementations that integrate with HeaderMotion.
    */
-  children: ScrollManagerRenderChildren;
+  children: ScrollManagerRenderChildren<TRef>;
 }
 
 /**
@@ -48,20 +45,33 @@ export interface HeaderMotionScrollManagerProps {
  * </HeaderMotion>
  * ```
  */
-export function HeaderMotionScrollManager({
+export function HeaderMotionScrollManager<
+  TRef extends InstanceOrElement = any
+>({
   children,
   scrollId,
   animatedRef,
-}: HeaderMotionScrollManagerProps) {
+  refreshControl,
+  refreshing,
+  onRefresh,
+  progressViewOffset,
+}: HeaderMotionScrollManagerProps<TRef>) {
   if (typeof children !== 'function') {
     throw new Error(
       'HeaderMotion.ScrollManager only accepts render function as the only child.'
     );
   }
 
-  const { scrollableProps, headerMotionContext } = useScrollManager(scrollId, {
-    animatedRef,
-  });
+  const { scrollableProps, headerMotionContext } = useScrollManager<TRef>(
+    scrollId,
+    {
+      animatedRef,
+      refreshControl,
+      refreshing,
+      onRefresh,
+      progressViewOffset,
+    }
+  );
 
   return children(scrollableProps, headerMotionContext);
 }

package/src/components/ScrollView.tsx

@@ -14,7 +14,7 @@ export type HeaderMotionScrollViewProps = AnimatedScrollViewProps & {
    * Optional animated ref to use for the scroll view.
    * When provided, the scroll manager will use this ref instead of creating its own.
    */
-  animatedRef?: AnimatedRef<any>;
+  animatedRef?: AnimatedRef<Animated.ScrollView> | AnimatedRef;
 };
 
 /**
@@ -36,18 +36,32 @@ export function HeaderMotionScrollView({
   animatedRef,
   children,
   contentContainerStyle,
+  refreshControl,
   ...props
 }: HeaderMotionScrollViewProps) {
   return (
-    <HeaderMotionScrollManager scrollId={scrollId} animatedRef={animatedRef}>
+    <HeaderMotionScrollManager
+      scrollId={scrollId}
+      animatedRef={animatedRef as AnimatedRef<Animated.ScrollView>}
+      refreshControl={refreshControl}
+    >
       {(
-        { onScroll, ...scrollViewProps },
+        {
+          onScroll,
+          ref,
+          refreshControl: managedRefreshControl,
+          ...scrollViewProps
+        },
         { originalHeaderHeight, minHeightContentContainerStyle }
       ) => (
         <Animated.ScrollView
           {...scrollViewProps}
           {...props}
+          ref={ref}
           onScroll={onScroll}
+          {...(managedRefreshControl && {
+            refreshControl: managedRefreshControl,
+          })}
         >
           <Animated.View
             style={[

package/src/context.ts

@@ -1,8 +1,10 @@
 import { createContext } from 'react';
 import { type SharedValue } from 'react-native-reanimated';
 import type {
+  AnimatedHeaderBaseMotionProps,
   MeasureAnimatedHeaderAndSet,
   Progress,
+  ScrollTo,
   ScrollValues,
 } from './types';
 
@@ -10,10 +12,15 @@ interface HeaderMotionContextType {
   progress: Progress;
   measureTotalHeight: MeasureAnimatedHeaderAndSet;
   measureDynamic: MeasureAnimatedHeaderAndSet;
+  enableHeaderPan: boolean;
+  headerPanMomentumOffset: SharedValue<number | null>;
+  animatedHeaderBaseProps: AnimatedHeaderBaseMotionProps;
   scrollValues: SharedValue<ScrollValues>;
   activeScrollId: SharedValue<string> | undefined;
-  progressThreshold: number;
-  originalHeaderHeight: number;
+  progressThreshold: SharedValue<number>;
+  originalHeaderHeight: SharedValue<number>;
+
+  scrollToRef: React.RefObject<ScrollTo | null>;
 }
 
 export const HeaderMotionContext =

package/src/hooks/useMotionProgress.ts

@@ -44,13 +44,21 @@ export function useMotionProgress(): MotionProgress {
       'useMotionProgress must be used within a <HeaderMotion /> component. If using inside a navigation header, consider using <HeaderMotion.Header /> instead to ensure context access.'
     );
   }
-  const { progress, measureTotalHeight, measureDynamic, progressThreshold } =
-    ctxValue;
+  const {
+    progress,
+    measureTotalHeight,
+    measureDynamic,
+    progressThreshold,
+    animatedHeaderBaseProps,
+    activeScrollId,
+  } = ctxValue;
 
   return {
     progress,
     measureTotalHeight,
     measureDynamic,
     progressThreshold,
+    animatedHeaderBaseProps,
+    activeScrollId,
   };
 }

package/src/hooks/useScrollManager.ts

@@ -1,5 +1,6 @@
 import { useContext, useCallback, useEffect } from 'react';
 import {
+  cancelAnimation,
   measure,
   scrollTo,
   useAnimatedReaction,
@@ -11,8 +12,21 @@ import {
 } from 'react-native-reanimated';
 import { RuntimeKind, scheduleOnUI } from 'react-native-worklets';
 import { HeaderMotionContext } from '../context';
-import type { ScrollManagerConfig, ScrollValues } from '../types';
-import { DEFAULT_SCROLL_ID, getInitialScrollValue } from '../utils';
+import type { ScrollManagerConfig } from '../types';
+import {
+  resolveRefreshControl,
+  DEFAULT_SCROLL_ID,
+  ensureScrollValueRegistered,
+  warnIfMissingActiveScrollId,
+  type ResolveRefreshControlOptions,
+} from '../utils';
+import type { InstanceOrElement } from 'react-native-reanimated/lib/typescript/commonTypes';
+
+type ScrollHandlerContext = {
+  lastOffset: number | undefined;
+};
+
+const SCROLL_TOLERANCE = 0.5;
 
 /**
  * Hook that manages scroll tracking and synchronization for header animations.
@@ -51,18 +65,24 @@ import { DEFAULT_SCROLL_ID, getInitialScrollValue } from '../utils';
  * }
  * ```
  */
-export interface UseScrollManagerOptions {
+export interface UseScrollManagerOptions<TRef extends InstanceOrElement = any>
+  extends Omit<ResolveRefreshControlOptions, 'progressViewOffset'> {
   /**
    * Optional animated ref to use instead of creating one internally.
    * Useful when you need access to the scroll view ref from outside.
    */
-  animatedRef?: AnimatedRef<any>;
+  animatedRef?: AnimatedRef<TRef>;
+  /**
+   * Optional refresh progress offset override.
+   * When provided, it takes precedence over the automatic offset based on header height.
+   */
+  progressViewOffset?: ResolveRefreshControlOptions['progressViewOffset'];
 }
 
-export function useScrollManager(
+export function useScrollManager<TRef extends InstanceOrElement = any>(
   scrollId?: string,
-  options?: UseScrollManagerOptions
-): ScrollManagerConfig {
+  options?: UseScrollManagerOptions<TRef>
+): ScrollManagerConfig<TRef> {
   const ctxValue = useContext(HeaderMotionContext);
   if (!ctxValue) {
     throw new Error(
@@ -76,11 +96,36 @@ export function useScrollManager(
     activeScrollId,
     progressThreshold,
     originalHeaderHeight,
+    scrollToRef,
+    headerPanMomentumOffset,
   } = ctxValue;
   const id = scrollId ?? DEFAULT_SCROLL_ID;
 
-  const localRef = useAnimatedRef<any>(); // TODO: better typing
+  const localRef = useAnimatedRef<TRef>();
   const animatedRef = options?.animatedRef ?? localRef;
+  const refreshControl = options?.refreshControl;
+  const refreshing = options?.refreshing;
+  const onRefresh = options?.onRefresh;
+  const progressViewOffset =
+    options?.progressViewOffset ?? originalHeaderHeight;
+
+  useAnimatedReaction(
+    () => activeScrollId?.get(),
+    (activeId) => {
+      const currentValues = ensureScrollValueRegistered(scrollValues, id);
+      warnIfMissingActiveScrollId(currentValues, id, activeId);
+
+      if (!activeId || activeId === id) {
+        // TODO: Could we just be passing current scrollRef instead of the entire function?
+        scrollToRef.current = (y, scrollOptions = {}) => {
+          'worklet';
+          const { isValueDelta = true, animated = false } = scrollOptions;
+          const newY = isValueDelta ? scrollValues.get()[id]!.current - y : y;
+          scrollTo(animatedRef, 0, newY, animated);
+        };
+      }
+    }
+  );
 
   useEffect(() => {
     return () => {
@@ -108,25 +153,20 @@ export function useScrollManager(
         return;
       }
 
-      if (!scrollValues.get()[id]) {
-        scrollValues.modify((value) => {
-          (value as ScrollValues)[id] = getInitialScrollValue();
-          return value;
-        });
-      }
+      ensureScrollValueRegistered(scrollValues, id);
 
       let newCur = -1;
+      const threshold = progressThreshold.get();
 
       scrollValues.modify((value) => {
-        let scrollValue = value[id];
+        const scrollValue = value[id];
         if (!scrollValue) {
-          (value as ScrollValues)[id] = getInitialScrollValue();
-          scrollValue = value[id]!;
+          return value;
         }
 
         const progressDiff = oldProgress - newProgress;
-        newCur = scrollValue.current - progressDiff * progressThreshold;
-        const newMin = newCur - newProgress * progressThreshold;
+        newCur = scrollValue.current - progressDiff * threshold;
+        const newMin = newCur - newProgress * threshold;
         scrollValue.current = newCur;
         scrollValue.min = newMin;
 
@@ -139,29 +179,58 @@ export function useScrollManager(
     }
   );
 
-  const scrollHandler = useCallback<ScrollHandler>(
-    (e) => {
+  const onScroll = useCallback<ScrollHandler<ScrollHandlerContext>>(
+    (e, ctx) => {
       'worklet';
+      const newCurrent = e.contentOffset.y;
+
+      if (
+        ctx.lastOffset !== undefined &&
+        Math.abs(ctx.lastOffset - newCurrent) < SCROLL_TOLERANCE
+      ) {
+        return;
+      }
+      ctx.lastOffset = newCurrent;
+
+      const threshold = progressThreshold.get();
+      const values = scrollValues.get();
+      const scrollValue = values[id];
+
+      if (!scrollValue) {
+        return;
+      }
+
+      const activeScrollIdValue = activeScrollId?.get();
+      if (activeScrollIdValue && activeScrollIdValue !== id) {
+        return;
+      }
+
+      const oldCurrent = scrollValue.current;
+      const oldMin = scrollValue.min;
+      const isCollapsed = oldCurrent >= oldMin + threshold - 0.001;
+
+      // When the header is fully collapsed and the user is scrolled past the
+      // threshold, progress is mathematically guaranteed to stay at 1:
+      //   min = newCurrent - threshold  →  (newCurrent - min) / threshold = 1
+      // In this case we update the values directly via .get() instead of
+      // .modify(), which avoids triggering the reactive cascade (progress
+      // re-derivation, animated reactions, animated styles). The values are
+      // still updated in-place for tab synchronization correctness.
+      if (isCollapsed && newCurrent >= threshold) {
+        scrollValue.current = newCurrent;
+        scrollValue.min = newCurrent - threshold;
+        return;
+      }
 
       scrollValues.modify((value) => {
         if (!value[id]) {
           return value;
         }
 
-        const activeScrollIdValue = activeScrollId?.get();
-        if (activeScrollIdValue && activeScrollIdValue !== id) {
-          return value;
-        }
-
-        const oldCurrent = value[id].current;
-        const oldMin = value[id].min;
-        const isCollapsed = oldCurrent >= oldMin + progressThreshold - 0.001;
-
-        const newCurrent = e.contentOffset.y;
         value[id].current = newCurrent;
 
         if (isCollapsed) {
-          value[id].min = Math.max(0, newCurrent - progressThreshold);
+          value[id].min = Math.max(0, newCurrent - threshold);
         }
 
         return value;
@@ -170,9 +239,24 @@ export function useScrollManager(
     [scrollValues, id, activeScrollId, progressThreshold]
   );
 
-  const onScroll = useAnimatedScrollHandler(scrollHandler);
+  const onBeginDrag = useCallback<ScrollHandler<ScrollHandlerContext>>(() => {
+    'worklet';
+    if (headerPanMomentumOffset.get() === null) {
+      return;
+    }
+
+    cancelAnimation(headerPanMomentumOffset);
+    headerPanMomentumOffset.set(null);
+  }, [headerPanMomentumOffset]);
+
+  const animatedOnScroll = useAnimatedScrollHandler({
+    onBeginDrag,
+    onScroll,
+  });
 
   const minHeightContentContainerStyle = useAnimatedStyle(() => {
+    const threshold = progressThreshold.get();
+
     if (globalThis.__RUNTIME_KIND === RuntimeKind.ReactNative) {
       return {};
     }
@@ -184,14 +268,22 @@ export function useScrollManager(
     }
 
     return {
-      minHeight: measurement.height + progressThreshold,
+      minHeight: measurement.height + threshold,
     };
   });
 
+  const resolvedRefreshControl = resolveRefreshControl({
+    refreshControl,
+    refreshing,
+    onRefresh,
+    progressViewOffset,
+  });
+
   const scrollableProps = {
-    onScroll,
+    onScroll: animatedOnScroll,
     scrollEventThrottle: 16,
     ref: animatedRef,
+    refreshControl: resolvedRefreshControl,
   };
   const headerMotionContext = {
     originalHeaderHeight,

package/src/types.ts

@@ -1,6 +1,8 @@
+import type { ReactElement } from 'react';
 import type { LayoutChangeEvent, ScrollViewProps } from 'react-native';
 import type { AnimatedRef, SharedValue } from 'react-native-reanimated';
 import { DEFAULT_SCROLL_ID } from './utils/defaults';
+import type { InstanceOrElement } from 'react-native-reanimated/lib/typescript/commonTypes';
 
 export type Progress = SharedValue<number>;
 
@@ -38,13 +40,21 @@ export type WithCollapsiblePagedHeaderProps<
 
 export interface MotionProgress {
   progress: Progress;
-  progressThreshold: number;
+  progressThreshold: SharedValue<number>;
   measureTotalHeight: MeasureAnimatedHeaderAndSet;
   measureDynamic: MeasureAnimatedHeaderAndSet;
+  animatedHeaderBaseProps: AnimatedHeaderBaseMotionProps;
+  activeScrollId: SharedValue<string> | undefined;
+}
+
+export interface AnimatedHeaderBaseMotionProps {
+  enableHeaderPan: boolean;
+  scrollToRef: React.RefObject<ScrollTo | null>;
+  headerPanMomentumOffset: SharedValue<number | null>;
 }
 
 export interface ScrollManagerHeaderMotionContext {
-  originalHeaderHeight: number;
+  originalHeaderHeight: SharedValue<number>;
   minHeightContentContainerStyle:
     | {}
     | {
@@ -52,11 +62,19 @@ export interface ScrollManagerHeaderMotionContext {
       };
 }
 
-export interface ScrollManagerConfig {
+export interface ScrollManagerConfig<TRef extends InstanceOrElement = any> {
   scrollableProps: Required<
     Pick<ScrollViewProps, 'onScroll' | 'scrollEventThrottle'>
   > & {
-    ref: AnimatedRef<any>; // TODO: better typing
+    refreshControl?: ReactElement;
+    ref: AnimatedRef<TRef>;
   };
   headerMotionContext: ScrollManagerHeaderMotionContext;
 }
+
+export type ScrollTo = (y: number, options?: ScrollToOptions) => void;
+
+interface ScrollToOptions {
+  isValueDelta?: boolean;
+  animated?: boolean;
+}