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

package/src/hooks/useScrollManager.ts

@@ -1,84 +1,59 @@
-import { useContext, useCallback, useEffect } from 'react';
 import {
-  measure,
+  useContext,
+  useCallback,
+  useEffect,
+  useState,
+  type ContextType,
+} from 'react';
+import {
+  cancelAnimation,
   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, ScrollValues } from '../types';
-import { DEFAULT_SCROLL_ID, getInitialScrollValue } from '../utils';
+import type { ScrollManagerConfig, ScrollHandlerContext } from '../types';
+import type { LayoutChangeEvent } from 'react-native';
 import {
   resolveRefreshControl,
+  DEFAULT_SCROLL_ID,
+  ensureScrollValueRegistered,
+  warnIfMissingActiveScrollId,
   type ResolveRefreshControlOptions,
-} from './refreshControl';
+} from '../utils';
+import type { InstanceOrElement } from 'react-native-reanimated/lib/typescript/commonTypes';
 import {
   useConsumerScrollHandlers,
   useScrollHandlerComposition,
   type ConsumerScrollEventHandlers,
 } from './useConsumerScrollHandlers';
 
-/**
- * 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
-  extends Omit<ResolveRefreshControlOptions, 'progressViewOffset'>,
-    ConsumerScrollEventHandlers {
-  /**
-   * 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>;
-  /**
-   * Optional refresh progress offset override.
-   * When provided, it takes precedence over the automatic offset based on header height.
-   */
-  progressViewOffset?: ResolveRefreshControlOptions['progressViewOffset'];
+const SCROLL_TOLERANCE = 0.5;
+
+type ScrollManagerContextValue = NonNullable<
+  ContextType<typeof HeaderMotionContext>
+>;
+
+interface MinHeightOptions {
+  enabled: boolean;
 }
 
-export function useScrollManager(
-  scrollId?: string,
-  options?: UseScrollManagerOptions
-): ScrollManagerConfig {
+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(
@@ -86,31 +61,89 @@ export function useScrollManager(
     );
   }
 
+  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,
-  } = ctxValue;
-  const id = scrollId ?? DEFAULT_SCROLL_ID;
+    scrollToRef,
+    scrollValues,
+  } = useScrollManagerContext();
 
-  const localRef = useAnimatedRef<any>(); // TODO: better typing
-  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);
 
-  const { onScroll, onBeginDrag, onEndDrag, onMomentumBegin, onMomentumEnd } =
-    useConsumerScrollHandlers({
-      onScroll: options?.onScroll,
-      onScrollBeginDrag: options?.onScrollBeginDrag,
-      onScrollEndDrag: options?.onScrollEndDrag,
-      onMomentumScrollBegin: options?.onMomentumScrollBegin,
-      onMomentumScrollEnd: options?.onMomentumScrollEnd,
-    });
+      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 () => {
@@ -122,13 +155,11 @@ export function useScrollManager(
         });
       }, 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 ||
@@ -138,25 +169,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;
 
@@ -168,61 +194,219 @@ export function useScrollManager(
       }
     }
   );
+}
 
-  const scrollHandler = useCallback<ScrollHandler>(
-    (e) => {
+function useScrollManagerHandlers({
+  consumerHandlers,
+  id,
+}: ScrollHandlersOptions) {
+  const {
+    activeScrollId,
+    headerPanMomentumOffset,
+    progressThreshold,
+    scrollValues,
+  } = useScrollManagerContext();
+  const { onScroll, onBeginDrag, onEndDrag, onMomentumBegin, onMomentumEnd } =
+    useConsumerScrollHandlers(consumerHandlers);
+
+  const handleScroll = useCallback<ScrollHandler<ScrollHandlerContext>>(
+    (e, ctx) => {
       'worklet';
       onScroll?.(e);
 
+      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;
+
+      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;
       });
     },
-    [scrollValues, id, activeScrollId, progressThreshold, onScroll]
+    [activeScrollId, id, onScroll, progressThreshold, scrollValues]
+  );
+
+  const handleBeginDrag = useCallback<ScrollHandler<ScrollHandlerContext>>(
+    (e) => {
+      'worklet';
+      onBeginDrag?.(e);
+
+      if (headerPanMomentumOffset.get() === null) {
+        return;
+      }
+
+      cancelAnimation(headerPanMomentumOffset);
+      headerPanMomentumOffset.set(null);
+    },
+    [headerPanMomentumOffset, onBeginDrag]
   );
 
-  const animatedScrollHandler = useAnimatedScrollHandler({
-    onScroll: scrollHandler,
-    onBeginDrag,
+  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;
+}
 
-  const minHeightContentContainerStyle = useAnimatedStyle(() => {
-    if (globalThis.__RUNTIME_KIND === RuntimeKind.ReactNative) {
-      return {};
-    }
+/**
+ * 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 measurement = measure(animatedRef);
+  const ensureScrollableContentMinHeight =
+    options?.ensureScrollableContentMinHeight ?? false;
+  const refreshControl = options?.refreshControl;
+  const refreshing = options?.refreshing;
+  const onRefresh = options?.onRefresh;
+  const progressViewOffset =
+    options?.progressViewOffset ?? originalHeaderHeight;
 
-    if (!measurement) {
-      return {};
-    }
+  const localRef = useAnimatedRef<TRef>();
+  const animatedRef = options?.animatedRef ?? localRef;
 
-    return {
-      minHeight: measurement.height + progressThreshold,
-    };
+  const { contentContainerMinHeight, handleLayout } =
+    useScrollManagerContentMinHeight({
+      enabled: ensureScrollableContentMinHeight,
+    });
+
+  useScrollManagerSynchronization({
+    id,
+    animatedRef,
+  });
+
+  const animatedOnScroll = useScrollManagerHandlers({
+    id,
+    consumerHandlers: {
+      onScroll: options?.onScroll,
+      onScrollBeginDrag: options?.onScrollBeginDrag,
+      onScrollEndDrag: options?.onScrollEndDrag,
+      onMomentumScrollBegin: options?.onMomentumScrollBegin,
+      onMomentumScrollEnd: options?.onMomentumScrollEnd,
+    },
   });
 
   const resolvedRefreshControl = resolveRefreshControl({
@@ -233,17 +417,14 @@ export function useScrollManager(
   });
 
   const scrollableProps = {
-    onScroll: useScrollHandlerComposition(
-      animatedScrollHandler,
-      options?.onScroll
-    ),
-    scrollEventThrottle: 16,
+    onScroll: useScrollHandlerComposition(animatedOnScroll, options?.onScroll),
+    onLayout: handleLayout,
     ref: animatedRef,
     refreshControl: resolvedRefreshControl,
   };
   const headerMotionContext = {
     originalHeaderHeight,
-    minHeightContentContainerStyle,
+    contentContainerMinHeight,
   };
 
   return { scrollableProps, headerMotionContext };