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

package/src/components/HeaderMotion.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useEffect, useMemo } from 'react';
+import { useCallback, useRef, useEffect, useMemo, useState } from 'react';
 import {
   Extrapolation,
   interpolate,
@@ -52,53 +52,68 @@ const resolveScrollIdForProgress = (
 
 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}.
+   * Distance that maps the active scrollable from `progress = 0`
+   * to `progress = 1`.
    *
-   * Defaults to a function that returns the return value of `measureDynamic` unchanged.
+   * Use a number when the collapse distance is fixed. Use a function when the
+   * distance should depend on what `measureDynamic` reads from
+   * `HeaderMotion.Header.Dynamic`.
+   *
+   * A common pattern is to measure the height of the part of the header that
+   * should disappear and use that as the threshold.
    */
   progressThreshold?: ProgressThreshold;
   /**
-   * Function to measure a dimension of choice of the animated element of the header.
-   *
-   * Receives the layout change event from React Native.
+   * Reads the value that should define the "collapsible" part of the header.
    *
-   * 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}.
+   * This is called from `HeaderMotion.Header.Dynamic` on layout. The returned
+   * number feeds `progressThreshold` when you provide that prop as a function.
    *
-   * Defaults to measuring the height from the event.
+   * By default, the library measures the dynamic section's height. Override
+   * this when the collapse distance should be based on something else, for
+   * example width or a derived value from the layout event.
    */
   measureDynamic?: MeasureAnimatedHeader;
   /**
-   * Mode for measuring dynamic header height.
+   * Controls when `measureDynamic` is allowed to update.
+   *
    * - '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
+   * - 'update': Re-measure whenever `HeaderMotion.Header.Dynamic` lays out again
+   *
+   * Use `'mount'` for stable headers. Use `'update'` when the dynamic section
+   * can change size after mount, for example after async data loads or content
+   * expansion.
+   *
    * @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.
+   * Shared value that tells HeaderMotion which scrollable currently owns the
+   * header progress in multi-scroll setups.
+   *
+   * Pass this when one header is shared across multiple scrollables, such as
+   * tabs or pager pages. Each scrollable should also get its own `scrollId`.
    */
   activeScrollId?: SharedValue<T>;
   /**
-   * Extrapolation type for the progress animation.
-   * Controls how the progress value behaves outside the threshold range.
+   * Controls how `progress` behaves outside the `[0, threshold]` range.
+   *
+   * The default clamps the value between `0` and `1`. Relax this if you want
+   * to animate overscroll or other out-of-range states.
    *
-   * You may want to modify it to achieve some animations for the overscroll scenarios.
    * @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 */
+  /** Descendants that should participate in the shared header-motion state. */
   children: ReactNode;
 }
 
 /**
- * Context provider component for HeaderMotion.
- * Manages header animation state and provides it to child components via context.
+ * Root provider for a header-motion setup.
+ *
+ * It tracks the measured header layout, the active scroll position, and the
+ * derived `progress` shared value consumed by your animated header UI.
+ *
  * @template T - The type of scroll ID string
  */
 function HeaderMotionContextProvider<T extends string>({
@@ -107,11 +122,10 @@ function HeaderMotionContextProvider<T extends string>({
   measureDynamicMode = 'mount',
   activeScrollId,
   progressExtrapolation = Extrapolation.CLAMP,
-  enableHeaderPan = false,
   children,
 }: HeaderMotionProps<T>) {
   const dynamicMeasurement = useSharedValue<number | undefined>(undefined);
-  const originalHeaderHeight = useSharedValue(0);
+  const [originalHeaderHeight, setOriginalHeaderHeight] = useState(0);
   const progressThresholdValue = useSharedValue(
     typeof progressThreshold === 'number' ? progressThreshold : Infinity
   );
@@ -131,11 +145,11 @@ function HeaderMotionContextProvider<T extends string>({
         }
 
         dynamicMeasurement.set(measured);
-        progressThresholdValue.set(
+        const nextThreshold =
           typeof progressThreshold === 'number'
             ? progressThreshold
-            : progressThreshold(measured)
-        );
+            : progressThreshold(measured);
+        progressThresholdValue.set(nextThreshold);
       },
       [
         measureDynamicMode,
@@ -153,21 +167,17 @@ function HeaderMotionContextProvider<T extends string>({
     }
 
     const measured = dynamicMeasurement.get();
-    progressThresholdValue.set(
-      measured === undefined ? Infinity : progressThreshold(measured)
-    );
+    const nextThreshold =
+      measured === undefined ? Infinity : progressThreshold(measured);
+    progressThresholdValue.set(nextThreshold);
   }, [progressThreshold, dynamicMeasurement, progressThresholdValue]);
 
   const measureTotalHeight = useCallback<MeasureAnimatedHeaderAndSet>(
     (e) => {
       const measuredValue = e.nativeEvent.layout.height;
-      if (originalHeaderHeight.get() === measuredValue) {
-        return;
-      }
-
-      originalHeaderHeight.set(measuredValue);
+      setOriginalHeaderHeight(measuredValue);
     },
-    [originalHeaderHeight]
+    [setOriginalHeaderHeight]
   );
 
   const scrollValues = useSharedValue<ScrollValues>({
@@ -212,24 +222,13 @@ function HeaderMotionContextProvider<T extends string>({
   // 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,
-      enableHeaderPan,
       headerPanMomentumOffset,
-      animatedHeaderBaseProps,
       progressThreshold: progressThresholdValue,
       scrollValues,
       scrollToRef,
@@ -239,9 +238,7 @@ function HeaderMotionContextProvider<T extends string>({
       originalHeaderHeight,
       progress,
       measureTotalHeight,
-      enableHeaderPan,
       headerPanMomentumOffset,
-      animatedHeaderBaseProps,
       setOrUpdateDynamicMeasurement,
       scrollValues,
       activeScrollId,

package/src/components/HeaderPanBoundary.tsx

@@ -0,0 +1,92 @@
+import { useMemo, type ReactElement } from 'react';
+import { Platform } from 'react-native';
+import {
+  Gesture,
+  GestureDetector,
+  GestureHandlerRootView,
+} from 'react-native-gesture-handler';
+import { useAnimatedReaction, withDecay } from 'react-native-reanimated';
+import type {
+  HeaderPanDecayConfig,
+  HeaderPanDecayEvent,
+  HeaderMotionBridgeValue,
+} from '../types';
+
+const PLATFORM_PANNING_ENABLED = Platform.select({
+  default: true,
+  android: false,
+});
+
+type HeaderPanBoundaryProps = Pick<
+  HeaderMotionBridgeValue,
+  'scrollToRef' | 'headerPanMomentumOffset'
+> & {
+  children: ReactElement;
+  pannable?: boolean;
+  panDecayConfig?: HeaderPanDecayConfig;
+  withGestureHandlerRootView?: boolean;
+};
+
+export function HeaderPanBoundary({
+  children,
+  pannable = false,
+  panDecayConfig,
+  scrollToRef,
+  headerPanMomentumOffset,
+  withGestureHandlerRootView = false,
+}: HeaderPanBoundaryProps) {
+  useAnimatedReaction(
+    () => headerPanMomentumOffset.get(),
+    (offset, prevOffset) => {
+      if (offset !== null) {
+        const dy = offset - (prevOffset ?? 0);
+        scrollToRef.current?.(dy);
+      }
+    }
+  );
+
+  const isPanEnabled = PLATFORM_PANNING_ENABLED && pannable;
+
+  const pan = useMemo(
+    () =>
+      Gesture.Pan()
+        .enabled(isPanEnabled)
+        .onChange((e) => {
+          const dy = e.changeY;
+          scrollToRef.current?.(dy);
+        })
+        .onEnd((e) => {
+          const resolvedConfig = resolvePanDecayConfig(panDecayConfig, e);
+          headerPanMomentumOffset.set(
+            withDecay(resolvedConfig, () => headerPanMomentumOffset.set(null))
+          );
+        })
+        .shouldCancelWhenOutside(false),
+    [headerPanMomentumOffset, isPanEnabled, panDecayConfig, scrollToRef]
+  );
+
+  const content = <GestureDetector gesture={pan}>{children}</GestureDetector>;
+
+  if (!withGestureHandlerRootView) {
+    return content;
+  }
+
+  return <GestureHandlerRootView>{content}</GestureHandlerRootView>;
+}
+
+function resolvePanDecayConfig(
+  panDecayConfig: HeaderPanDecayConfig | undefined,
+  event: HeaderPanDecayEvent
+) {
+  'worklet';
+
+  const resolvedConfig =
+    typeof panDecayConfig === 'function'
+      ? panDecayConfig(event)
+      : panDecayConfig;
+
+  return {
+    ...resolvedConfig,
+    velocity: resolvedConfig?.velocity ?? event.velocityY,
+  };
+}

package/src/components/NavigationBridge.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import { HeaderMotionContext } from '../context';
+import type { HeaderMotionBridgeValue } from '../types';
+
+export interface HeaderMotionNavigationBridgeProps {
+  /**
+   * Previously captured HeaderMotion context value to re-provide in another
+   * subtree.
+   */
+  value: HeaderMotionBridgeValue;
+  /** Subtree that should regain access to HeaderMotion context. */
+  children: ReactNode;
+}
+
+/**
+ * Re-provides HeaderMotion context in a different part of the React tree.
+ *
+ * This is primarily useful for navigation libraries that render headers outside
+ * the screen subtree where `HeaderMotion` itself lives.
+ */
+export function NavigationBridge({
+  value,
+  children,
+}: HeaderMotionNavigationBridgeProps) {
+  return (
+    <HeaderMotionContext.Provider value={value}>
+      {children}
+    </HeaderMotionContext.Provider>
+  );
+}

package/src/components/ScrollManager.tsx

@@ -12,23 +12,27 @@ 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.
+   * Unique identifier for this scrollable in multi-scroll setups.
+   *
+   * Omit it for single-scroll screens.
    */
   scrollId?: string;
   /**
-   * Render function that receives scroll props and header context.
-   * Use this to create custom scroll implementations that integrate with HeaderMotion.
+   * Render function that receives:
+   * - the props to spread onto your scrollable
+   * - the layout values needed to offset content below the header
    */
   children: ScrollManagerRenderChildren<TRef>;
 }
 
 /**
- * ScrollManager component that provides scroll tracking functionality for custom scroll implementations. Uses {@link useScrollManager} under the hood.
- * Must be used within a HeaderMotion component.
+ * Render-prop wrapper around `useScrollManager()`.
  *
- * 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).
+ * **Most code should prefer `createHeaderMotionScrollable()` instead.**
+ *
+ * Use `ScrollManager` only when the factory approach is not enough and you
+ * still need HeaderMotion to manage a custom scrollable through render-prop
+ * composition.
  *
  * @example
  * ```tsx
@@ -45,9 +49,7 @@ export interface HeaderMotionScrollManagerProps<
  * </HeaderMotion>
  * ```
  */
-export function HeaderMotionScrollManager<
-  TRef extends InstanceOrElement = any
->({
+export function ScrollManager<TRef extends InstanceOrElement = any>({
   children,
   scrollId,
   animatedRef,
@@ -55,6 +57,11 @@ export function HeaderMotionScrollManager<
   refreshing,
   onRefresh,
   progressViewOffset,
+  onScroll,
+  onScrollBeginDrag,
+  onScrollEndDrag,
+  onMomentumScrollBegin,
+  onMomentumScrollEnd,
 }: HeaderMotionScrollManagerProps<TRef>) {
   if (typeof children !== 'function') {
     throw new Error(
@@ -70,6 +77,11 @@ export function HeaderMotionScrollManager<
       refreshing,
       onRefresh,
       progressViewOffset,
+      onScroll,
+      onScrollBeginDrag,
+      onScrollEndDrag,
+      onMomentumScrollBegin,
+      onMomentumScrollEnd,
     }
   );
 

package/src/components/ScrollView.tsx

@@ -1,21 +1,18 @@
+import type { ReactElement } from 'react';
 import Animated, {
-  type AnimatedRef,
   type AnimatedScrollViewProps,
 } from 'react-native-reanimated';
-import { HeaderMotionScrollManager } from './ScrollManager';
+import {
+  createHeaderMotionScrollable,
+  type HeaderMotionScrollableOwnProps,
+} from './createHeaderMotionScrollable';
 
-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;
-  /**
-   * 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<Animated.ScrollView> | AnimatedRef;
-};
+export type HeaderMotionScrollViewProps = AnimatedScrollViewProps &
+  HeaderMotionScrollableOwnProps<Animated.ScrollView>;
+
+type HeaderMotionScrollViewComponent = (
+  props: HeaderMotionScrollViewProps
+) => ReactElement | null;
 
 /**
  * Animated ScrollView component that integrates with HeaderMotion.
@@ -31,49 +28,8 @@ export type HeaderMotionScrollViewProps = AnimatedScrollViewProps & {
  * </HeaderMotion>
  * ```
  */
-export function HeaderMotionScrollView({
-  scrollId,
-  animatedRef,
-  children,
-  contentContainerStyle,
-  refreshControl,
-  ...props
-}: HeaderMotionScrollViewProps) {
-  return (
-    <HeaderMotionScrollManager
-      scrollId={scrollId}
-      animatedRef={animatedRef as AnimatedRef<Animated.ScrollView>}
-      refreshControl={refreshControl}
-    >
-      {(
-        {
-          onScroll,
-          ref,
-          refreshControl: managedRefreshControl,
-          ...scrollViewProps
-        },
-        { originalHeaderHeight, minHeightContentContainerStyle }
-      ) => (
-        <Animated.ScrollView
-          {...scrollViewProps}
-          {...props}
-          ref={ref}
-          onScroll={onScroll}
-          {...(managedRefreshControl && {
-            refreshControl: managedRefreshControl,
-          })}
-        >
-          <Animated.View
-            style={[
-              minHeightContentContainerStyle,
-              { paddingTop: originalHeaderHeight },
-              contentContainerStyle,
-            ]}
-          >
-            {children}
-          </Animated.View>
-        </Animated.ScrollView>
-      )}
-    </HeaderMotionScrollManager>
-  );
-}
+export const ScrollView = createHeaderMotionScrollable(Animated.ScrollView, {
+  displayName: 'HeaderMotion.ScrollView',
+  contentContainerMode: 'children',
+  isComponentAnimated: true,
+}) as HeaderMotionScrollViewComponent;