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

package/src/hooks/useMotionProgress.test.ts

@@ -0,0 +1,67 @@
+const mockUseHeaderMotionContextOrThrow = jest.fn();
+
+jest.mock('../context', () => ({
+  __esModule: true,
+  useHeaderMotionContextOrThrow: (...args: any[]) =>
+    mockUseHeaderMotionContextOrThrow(...args),
+}));
+
+import { useHeaderMotionBridge } from './useHeaderMotionBridge';
+import { useMotionProgress } from './useMotionProgress';
+
+function createSharedValue<T>(value: T) {
+  return {
+    get: jest.fn(() => value),
+    set: jest.fn(),
+    value,
+  };
+}
+
+const bridgeValue = {
+  progress: createSharedValue(0),
+  progressThreshold: createSharedValue(120),
+  measureTotalHeight: jest.fn(),
+  measureDynamic: jest.fn(),
+  headerPanMomentumOffset: createSharedValue<number | null>(null),
+  scrollValues: createSharedValue({}),
+  activeScrollId: undefined,
+  scrollToRef: { current: null },
+  originalHeaderHeight: 0,
+};
+
+describe('motion hooks', () => {
+  beforeEach(() => {
+    mockUseHeaderMotionContextOrThrow.mockReset();
+  });
+
+  it('useMotionProgress returns only progress and progressThreshold', () => {
+    mockUseHeaderMotionContextOrThrow.mockReturnValue(bridgeValue);
+
+    expect(useMotionProgress()).toEqual({
+      progress: bridgeValue.progress,
+      progressThreshold: bridgeValue.progressThreshold,
+    });
+    expect(mockUseHeaderMotionContextOrThrow).toHaveBeenCalledWith(
+      'useMotionProgress must be used within <HeaderMotion /> or <HeaderMotion.NavigationBridge />. If you are rendering inside a navigation header, bridge the context with <HeaderMotion.Bridge /> and <HeaderMotion.NavigationBridge />.'
+    );
+  });
+
+  it('useHeaderMotionBridge returns the full bridge value', () => {
+    mockUseHeaderMotionContextOrThrow.mockReturnValue(bridgeValue);
+
+    expect(useHeaderMotionBridge()).toBe(bridgeValue);
+    expect(mockUseHeaderMotionContextOrThrow).toHaveBeenCalledWith(
+      'useHeaderMotionBridge must be used within <HeaderMotion />. Use it only when bridging context into a separate subtree with <HeaderMotion.Bridge /> and <HeaderMotion.NavigationBridge />.'
+    );
+  });
+
+  it('rethrows missing-context errors from the helper hook', () => {
+    const error = new Error('missing context');
+    mockUseHeaderMotionContextOrThrow.mockImplementation(() => {
+      throw error;
+    });
+
+    expect(() => useMotionProgress()).toThrow(error);
+    expect(() => useHeaderMotionBridge()).toThrow(error);
+  });
+});

package/src/hooks/useMotionProgress.ts

@@ -1,64 +1,31 @@
-import { useContext } from 'react';
-import { HeaderMotionContext } from '../context';
+import { useHeaderMotionContextOrThrow } from '../context';
 import type { MotionProgress } from '../types';
 
 /**
- * Hook to access motion progress values and measuring functions for header animations.
- * Returns the progress value (0-1), threshold, and measurement functions.
+ * Returns the two shared values most header animations actually need:
+ * `progress` and `progressThreshold`.
  *
- * Must be used within a {@link HeaderMotion} component.
+ * Use this inside your animated header components to derive transforms,
+ * opacity, scale, parallax, or any other visual response to scroll.
  *
- * @returns Motion progress values and measuring functions:
- * - `progress`: Shared value from 0 to 1
- * - `progressThreshold`: The threshold at which animation completes
- * - `measureTotalHeight`: Function to measure total header height. Should be passed to the `onLayout` prop of the base of a header, to let scrollables account for the total header height
- * - `measureDynamic`: Function to measure a dimension of choice of the animated element of the header - should be passed to the `onLayout` prop of such. If used, can be used for dynamic calculation of the {@link progressThreshold}.
- *
- * @throws Error if used outside of a {@link HeaderMotion} component
+ * `progress` usually lives in the `0..1` range, where `0` is the expanded
+ * state and `1` is the fully collapsed state. `progressThreshold` is the pixel
+ * distance that corresponds to that transition.
  *
  * @example
  * ```tsx
  * function MyHeader() {
- *   const { progress, progressThreshold, measureTotalHeight, measureDynamic } = useMotionProgress();
- *   const dynamicStyle = useAnimatedStyle(() => {
- *     const translateY = interpolate(
- *       progress.value,
- *       [0, 1],
- *       [0, -progressThreshold],
- *       Extrapolation.CLAMP,
- *     )
- *     return { transform: [{ translateY }] }
- *   })
- *   return (
- *     <AnimatedHeaderBase onLayout={measureTotalHeight}>
- *       <Animated.View onLayout={measureDynamic} style={dynamicStyle} />
- *     </AnimatedHeaderBase>
- *   )
+ *   const { progress, progressThreshold } = useMotionProgress();
  * }
  * ```
  */
 export function useMotionProgress(): MotionProgress {
-  const ctxValue = useContext(HeaderMotionContext);
-  if (!ctxValue) {
-    throw new Error(
-      '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,
-    animatedHeaderBaseProps,
-    activeScrollId,
-  } = ctxValue;
+  const { progress, progressThreshold } = useHeaderMotionContextOrThrow(
+    'useMotionProgress must be used within <HeaderMotion /> or <HeaderMotion.NavigationBridge />. If you are rendering inside a navigation header, bridge the context with <HeaderMotion.Bridge /> and <HeaderMotion.NavigationBridge />.'
+  );
 
   return {
     progress,
-    measureTotalHeight,
-    measureDynamic,
     progressThreshold,
-    animatedHeaderBaseProps,
-    activeScrollId,
   };
 }

package/src/hooks/useScrollManager.ts

@@ -1,18 +1,24 @@
-import { useContext, useCallback, useEffect } from 'react';
+import {
+  useContext,
+  useCallback,
+  useEffect,
+  useState,
+  type ContextType,
+} from 'react';
 import {
   cancelAnimation,
-  measure,
   scrollTo,
   useAnimatedReaction,
   useAnimatedRef,
   useAnimatedScrollHandler,
-  useAnimatedStyle,
+  useSharedValue,
   type AnimatedRef,
   type ScrollHandler,
 } from 'react-native-reanimated';
-import { RuntimeKind, scheduleOnUI } from 'react-native-worklets';
+import { scheduleOnRN, scheduleOnUI } from 'react-native-worklets';
 import { HeaderMotionContext } from '../context';
-import type { ScrollManagerConfig } from '../types';
+import type { ScrollManagerConfig, ScrollHandlerContext } from '../types';
+import type { LayoutChangeEvent } from 'react-native';
 import {
   resolveRefreshControl,
   DEFAULT_SCROLL_ID,
@@ -21,68 +27,33 @@ import {
   type ResolveRefreshControlOptions,
 } from '../utils';
 import type { InstanceOrElement } from 'react-native-reanimated/lib/typescript/commonTypes';
-
-type ScrollHandlerContext = {
-  lastOffset: number | undefined;
-};
+import {
+  useConsumerScrollHandlers,
+  useScrollHandlerComposition,
+  type ConsumerScrollEventHandlers,
+} from './useConsumerScrollHandlers';
 
 const SCROLL_TOLERANCE = 0.5;
 
-/**
- * Hook that manages scroll tracking and synchronization for header animations.
- * Returns props to apply to scrollable components and additional values that help with adjusting styling of the scrollables to header's dimensions.
- *
- * This hook handles:
- * - Scroll position tracking
- * - Synchronization between multiple scroll views (when using multiple scroll IDs)
- * - Content container minimum height calculations for cases where one of the tracked scrollables does not take enough space to reach the progress threshold/
- *
- * Must be used within a HeaderMotion component.
- *
- * @param scrollId - Optional unique identifier for the related scrollable.
- *                   Use when you have multiple scrollables (e.g., in tabs).
- * @param options - Optional configuration object.
- * @param options.animatedRef - Optional animated ref to use instead of creating one internally.
- *                              Useful when you need access to the scroll view ref from outside.
- * @returns Configuration object containing:
- * - `scrollableProps`: Props to apply to scrollable component (onScroll, scrollEventThrottle, ref)
- * - `headerMotionContext`: Header context values (originalHeaderHeight, minHeightContentContainerStyle)
- *
- * @throws Error if used outside of a HeaderMotion component
- *
- * @example
- * ```tsx
- * function CustomScrollComponent() {
- *   const { scrollableProps, headerMotionContext } = useScrollManager('myScroll');
- *
- *   return (
- *     <CustomScrollView {...scrollableProps}>
- *       <View style={{ paddingTop: headerMotionContext.originalHeaderHeight }}>
- *         Content
- *       </View>
- *     </CustomScrollView>
- *   );
- * }
- * ```
- */
-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<TRef>;
-  /**
-   * Optional refresh progress offset override.
-   * When provided, it takes precedence over the automatic offset based on header height.
-   */
-  progressViewOffset?: ResolveRefreshControlOptions['progressViewOffset'];
+type ScrollManagerContextValue = NonNullable<
+  ContextType<typeof HeaderMotionContext>
+>;
+
+interface MinHeightOptions {
+  enabled: boolean;
 }
 
-export function useScrollManager<TRef extends InstanceOrElement = any>(
-  scrollId?: string,
-  options?: UseScrollManagerOptions<TRef>
-): ScrollManagerConfig<TRef> {
+interface SynchronizationOptions<TRef extends InstanceOrElement> {
+  animatedRef: AnimatedRef<TRef>;
+  id: string;
+}
+
+interface ScrollHandlersOptions {
+  consumerHandlers: ConsumerScrollEventHandlers;
+  id: string;
+}
+
+function useScrollManagerContext(): ScrollManagerContextValue {
   const ctxValue = useContext(HeaderMotionContext);
   if (!ctxValue) {
     throw new Error(
@@ -90,24 +61,71 @@ export function useScrollManager<TRef extends InstanceOrElement = any>(
     );
   }
 
+  return ctxValue;
+}
+
+function useScrollManagerContentMinHeight({ enabled }: MinHeightOptions) {
+  const { progressThreshold } = useScrollManagerContext();
+  const preservedScrollContainerHeight = useSharedValue(0);
+  const [contentContainerMinHeight, setContentContainerMinHeight] = useState<
+    number | undefined
+  >(undefined);
+
+  const handleLayout = useCallback(
+    (e: LayoutChangeEvent) => {
+      if (!enabled) {
+        return;
+      }
+
+      const nextHeight = e.nativeEvent.layout.height;
+      scheduleOnUI((height: number) => {
+        'worklet';
+        preservedScrollContainerHeight.set(height);
+        const nextMinHeight = height + progressThreshold.get();
+        scheduleOnRN(setContentContainerMinHeight, nextMinHeight);
+      }, nextHeight);
+    },
+    [enabled, preservedScrollContainerHeight, progressThreshold]
+  );
+
+  useAnimatedReaction(
+    () => progressThreshold.get(),
+    (threshold, previousThreshold) => {
+      if (
+        !enabled ||
+        previousThreshold === null ||
+        previousThreshold === threshold
+      ) {
+        return;
+      }
+
+      const currentHeight = preservedScrollContainerHeight.get();
+      if (currentHeight <= 0) {
+        return;
+      }
+
+      const nextMinHeight = currentHeight + threshold;
+      scheduleOnRN(setContentContainerMinHeight, nextMinHeight);
+    }
+  );
+
+  return {
+    contentContainerMinHeight,
+    handleLayout: enabled ? handleLayout : undefined,
+  };
+}
+
+function useScrollManagerSynchronization<TRef extends InstanceOrElement>({
+  animatedRef,
+  id,
+}: SynchronizationOptions<TRef>) {
   const {
-    scrollValues,
-    progress,
     activeScrollId,
+    progress,
     progressThreshold,
-    originalHeaderHeight,
     scrollToRef,
-    headerPanMomentumOffset,
-  } = ctxValue;
-  const id = scrollId ?? DEFAULT_SCROLL_ID;
-
-  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;
+    scrollValues,
+  } = useScrollManagerContext();
 
   useAnimatedReaction(
     () => activeScrollId?.get(),
@@ -137,13 +155,11 @@ export function useScrollManager<TRef extends InstanceOrElement = any>(
         });
       }, id);
     };
-  }, [scrollValues, id]);
+  }, [id, scrollValues]);
 
   useAnimatedReaction(
     () => progress.value,
     (newProgress, oldProgress) => {
-      // FUTURE: If really needed for, can use other scroll handlers to only do this either on scroll end or between scroll end and momentum end in onScroll (keep context in shared value)
-      // Only sync inactive scroll views when we have multiple tabs being tracked
       const currentActiveScrollId = activeScrollId?.get();
       if (
         !currentActiveScrollId ||
@@ -178,10 +194,26 @@ export function useScrollManager<TRef extends InstanceOrElement = any>(
       }
     }
   );
+}
+
+function useScrollManagerHandlers({
+  consumerHandlers,
+  id,
+}: ScrollHandlersOptions) {
+  const {
+    activeScrollId,
+    headerPanMomentumOffset,
+    progressThreshold,
+    scrollValues,
+  } = useScrollManagerContext();
+  const { onScroll, onBeginDrag, onEndDrag, onMomentumBegin, onMomentumEnd } =
+    useConsumerScrollHandlers(consumerHandlers);
 
-  const onScroll = useCallback<ScrollHandler<ScrollHandlerContext>>(
+  const handleScroll = useCallback<ScrollHandler<ScrollHandlerContext>>(
     (e, ctx) => {
       'worklet';
+      onScroll?.(e);
+
       const newCurrent = e.contentOffset.y;
 
       if (
@@ -209,13 +241,6 @@ export function useScrollManager<TRef extends InstanceOrElement = any>(
       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;
@@ -236,40 +261,152 @@ export function useScrollManager<TRef extends InstanceOrElement = any>(
         return value;
       });
     },
-    [scrollValues, id, activeScrollId, progressThreshold]
+    [activeScrollId, id, onScroll, progressThreshold, scrollValues]
   );
 
-  const onBeginDrag = useCallback<ScrollHandler<ScrollHandlerContext>>(() => {
-    'worklet';
-    if (headerPanMomentumOffset.get() === null) {
-      return;
-    }
+  const handleBeginDrag = useCallback<ScrollHandler<ScrollHandlerContext>>(
+    (e) => {
+      'worklet';
+      onBeginDrag?.(e);
+
+      if (headerPanMomentumOffset.get() === null) {
+        return;
+      }
 
-    cancelAnimation(headerPanMomentumOffset);
-    headerPanMomentumOffset.set(null);
-  }, [headerPanMomentumOffset]);
+      cancelAnimation(headerPanMomentumOffset);
+      headerPanMomentumOffset.set(null);
+    },
+    [headerPanMomentumOffset, onBeginDrag]
+  );
 
-  const animatedOnScroll = useAnimatedScrollHandler({
-    onBeginDrag,
-    onScroll,
+  return useAnimatedScrollHandler({
+    onBeginDrag: handleBeginDrag,
+    onScroll: handleScroll,
+    onEndDrag,
+    onMomentumBegin,
+    onMomentumEnd,
   });
+}
+export interface UseScrollManagerOptions<TRef extends InstanceOrElement = any>
+  extends Omit<ResolveRefreshControlOptions, 'progressViewOffset'>,
+    ConsumerScrollEventHandlers {
+  /**
+   * Animated ref for the managed scrollable.
+   *
+   * Provide this when the caller also needs imperative access to the same
+   * scrollable instance. Otherwise the hook creates one internally.
+   */
+  animatedRef?: AnimatedRef<TRef>;
+  /**
+   * Overrides the refresh indicator offset.
+   *
+   * By default, HeaderMotion derives this from the measured header height so
+   * pull-to-refresh starts below the header. Override it only when you need a
+   * custom refresh placement.
+   */
+  progressViewOffset?: ResolveRefreshControlOptions['progressViewOffset'];
+  /**
+   * Ensures short content can still scroll far enough to fully collapse the
+   * header.
+   *
+   * **Experimental: this relies on extra layout measurement and may still be
+   * refined.**
+   *
+   * Enable this when your content is sometimes shorter than the viewport and
+   * you still want the header to reach the collapsed state.
+   */
+  ensureScrollableContentMinHeight?: boolean;
+}
+
+/**
+ * Wires a custom scrollable into HeaderMotion.
+ *
+ * Most code should not use this hook directly.
+ *
+ * **Prefer `createHeaderMotionScrollable()` whenever possible.** It gives
+ * you the same integration in a reusable component wrapper with less manual
+ * wiring. Reach for `useScrollManager()` only in more complex cases where the
+ * factory API is not enough, for example when a third-party scrollable needs
+ * highly custom composition.
+ *
+ * It returns two things:
+ * - `scrollableProps`: the event handlers / ref / refresh-control props that
+ *   should go on the scrollable itself
+ * - `headerMotionContext`: layout values you can use to offset the content
+ *   below the measured header
+ *
+ * In multi-scroll setups, pass a unique `scrollId` for each scrollable.
+ * In single-scroll setups, you usually do not need one.
+ *
+ * If you need the same fallback behavior but prefer render-prop composition
+ * over a hook, use `HeaderMotion.ScrollManager`.
+ *
+ * @param scrollId Optional unique identifier for the managed scrollable.
+ * @param options Optional configuration for refs, refresh handling, user
+ * scroll callbacks, and short-content fallback behavior.
+ * @returns Object containing:
+ * - `scrollableProps`: props to spread onto the scrollable (`ref`, managed
+ *   `onScroll`, optional `onLayout`, and resolved `refreshControl`)
+ * - `headerMotionContext`: layout values for offsetting the content container
+ *   (`originalHeaderHeight` and optional `contentContainerMinHeight`)
+ *
+ * @example
+ * ```tsx
+ * function CustomScrollComponent() {
+ *   const { scrollableProps, headerMotionContext } = useScrollManager('myScroll');
+ *
+ *   return (
+ *     <CustomScrollView {...scrollableProps}>
+ *       <View
+ *         style={{
+ *           paddingTop: headerMotionContext.originalHeaderHeight,
+ *           minHeight: headerMotionContext.contentContainerMinHeight,
+ *         }}
+ *       >
+ *         Content
+ *       </View>
+ *     </CustomScrollView>
+ *   );
+ * }
+ * ```
+ */
+export function useScrollManager<TRef extends InstanceOrElement = any>(
+  scrollId?: string,
+  options?: UseScrollManagerOptions<TRef>
+): ScrollManagerConfig<TRef> {
+  const { originalHeaderHeight } = useScrollManagerContext();
+  const id = scrollId ?? DEFAULT_SCROLL_ID;
 
-  const minHeightContentContainerStyle = useAnimatedStyle(() => {
-    const threshold = progressThreshold.get();
+  const ensureScrollableContentMinHeight =
+    options?.ensureScrollableContentMinHeight ?? false;
+  const refreshControl = options?.refreshControl;
+  const refreshing = options?.refreshing;
+  const onRefresh = options?.onRefresh;
+  const progressViewOffset =
+    options?.progressViewOffset ?? originalHeaderHeight;
 
-    if (globalThis.__RUNTIME_KIND === RuntimeKind.ReactNative) {
-      return {};
-    }
+  const localRef = useAnimatedRef<TRef>();
+  const animatedRef = options?.animatedRef ?? localRef;
 
-    const measurement = measure(animatedRef);
+  const { contentContainerMinHeight, handleLayout } =
+    useScrollManagerContentMinHeight({
+      enabled: ensureScrollableContentMinHeight,
+    });
 
-    if (!measurement) {
-      return {};
-    }
+  useScrollManagerSynchronization({
+    id,
+    animatedRef,
+  });
 
-    return {
-      minHeight: measurement.height + threshold,
-    };
+  const animatedOnScroll = useScrollManagerHandlers({
+    id,
+    consumerHandlers: {
+      onScroll: options?.onScroll,
+      onScrollBeginDrag: options?.onScrollBeginDrag,
+      onScrollEndDrag: options?.onScrollEndDrag,
+      onMomentumScrollBegin: options?.onMomentumScrollBegin,
+      onMomentumScrollEnd: options?.onMomentumScrollEnd,
+    },
   });
 
   const resolvedRefreshControl = resolveRefreshControl({
@@ -280,14 +417,14 @@ export function useScrollManager<TRef extends InstanceOrElement = any>(
   });
 
   const scrollableProps = {
-    onScroll: animatedOnScroll,
-    scrollEventThrottle: 16,
+    onScroll: useScrollHandlerComposition(animatedOnScroll, options?.onScroll),
+    onLayout: handleLayout,
     ref: animatedRef,
     refreshControl: resolvedRefreshControl,
   };
   const headerMotionContext = {
     originalHeaderHeight,
-    minHeightContentContainerStyle,
+    contentContainerMinHeight,
   };
 
   return { scrollableProps, headerMotionContext };