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

package/src/components/Header.tsx

@@ -1,30 +1,166 @@
-import { useMotionProgress } from '../hooks/useMotionProgress';
-import type { MotionProgress } from '../types';
-import type { ReactNode } from 'react';
+import { StyleSheet, type ViewProps } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { useHeaderMotionContextOrThrow } from '../context';
+import type {
+  HeaderAsChildProps,
+  HeaderDefaultProps,
+  HeaderPanDecayConfig,
+} from '../types';
+import {
+  cloneWithOnLayout,
+  composeOnLayoutHandlers,
+  resolveSlottableChild,
+} from '../utils';
+import { HeaderDynamic } from './HeaderDynamic';
+import { HeaderPanBoundary } from './HeaderPanBoundary';
 
-type HeaderRenderChildren = (props: MotionProgress) => ReactNode;
+type HeaderPanProps =
+  | {
+      /** Enables dragging the header itself to scroll the active scrollable.
+       *
+       * This is useful when the header covers a large portion of the screen
+       * and you want the gesture to feel continuous between header and content.
+       *
+       * @default false
+       */
+      pannable: true;
+      /**
+       * Customizes the momentum animation that runs after a header pan ends.
+       *
+       * Use an object for a fixed decay profile. Use a function when the decay
+       * should depend on the end event, for example to dampen or amplify
+       * certain velocities.
+       *
+       * If you provide a function, it runs inside the gesture end worklet and
+       * **must itself be marked with the 'worklet' directive.**
+       */
+      panDecayConfig?: HeaderPanDecayConfig;
+    }
+  | {
+      pannable?: false | undefined;
+      panDecayConfig?: never;
+    };
 
-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;
-}
+export type HeaderProps =
+  | (HeaderDefaultProps &
+      HeaderPanProps & {
+        /**
+         * Applies the default absolute-positioned header layout.
+         *
+         * Leave this enabled for navigation headers and any header that should
+         * visually float above the scrollable content. Disable it only when you
+         * intentionally want the header to participate in normal layout flow.
+         *
+         * @default true
+         */
+        overlay?: boolean;
+        /**
+         * Wraps the pan gesture in `GestureHandlerRootView`.
+         *
+         * Only use this when the rendered header subtree is not already under a
+         * gesture-handler root.
+         *
+         * @default false
+         */
+        withGestureHandlerRootView?: boolean;
+      })
+  | (HeaderAsChildProps &
+      HeaderPanProps & {
+        /**
+         * Wraps the pan gesture in `GestureHandlerRootView`.
+         *
+         * Only use this when the rendered header subtree is not already under a
+         * gesture-handler root.
+         *
+         * @default false
+         */
+        withGestureHandlerRootView?: boolean;
+      });
 
-/**
- * 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 headerOverlayStyle = StyleSheet.create({
+  overlay: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+  },
+}).overlay;
+
+function HeaderRoot(props: HeaderProps) {
+  const ctxValue = useHeaderMotionContextOrThrow(
+    'HeaderMotion.Header 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 />.'
+  );
+
+  if (props.asChild) {
+    const child = resolveSlottableChild('HeaderMotion.Header', props.children);
+
+    return (
+      <HeaderPanBoundary
+        pannable={props.pannable}
+        panDecayConfig={props.panDecayConfig}
+        headerPanMomentumOffset={ctxValue.headerPanMomentumOffset}
+        scrollToRef={ctxValue.scrollToRef}
+        withGestureHandlerRootView={props.withGestureHandlerRootView}
+      >
+        {cloneWithOnLayout(
+          child,
+          ctxValue.measureTotalHeight,
+          'HeaderMotion.Header'
+        )}
+      </HeaderPanBoundary>
     );
   }
 
-  const motionProgressProps = useMotionProgress();
-  return children(motionProgressProps);
+  const {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    asChild: _asChild,
+    overlay = true,
+    pannable,
+    panDecayConfig,
+    onLayout,
+    style,
+    withGestureHandlerRootView,
+    ...rest
+  } = props;
+  const resolvedOnLayout = onLayout as ViewProps['onLayout'] | undefined;
+
+  return (
+    <HeaderPanBoundary
+      pannable={pannable}
+      panDecayConfig={panDecayConfig}
+      headerPanMomentumOffset={ctxValue.headerPanMomentumOffset}
+      scrollToRef={ctxValue.scrollToRef}
+      withGestureHandlerRootView={withGestureHandlerRootView}
+    >
+      <Animated.View
+        {...rest}
+        onLayout={composeOnLayoutHandlers(
+          resolvedOnLayout,
+          ctxValue.measureTotalHeight
+        )}
+        style={[overlay ? headerOverlayStyle : undefined, style]}
+      />
+    </HeaderPanBoundary>
+  );
 }
+
+/**
+ * Header container that measures the total header height for scroll offsetting.
+ *
+ * It renders an `Animated.View` by default, wires the outer header measurement
+ * automatically, and can optionally make the header surface pannable.
+ *
+ * Pair it with `Header.Dynamic` to mark the part of the header that should
+ * drive the collapse threshold.
+ */
+export const Header = Object.assign(HeaderRoot, {
+  /**
+   * Marks the part of the header whose measured layout should define the
+   * collapsible distance.
+   *
+   * In most designs, this is the section that visually disappears while the
+   * header collapses. Its measured value feeds `measureDynamic`, which can in
+   * turn drive `progressThreshold`.
+   */
+  Dynamic: HeaderDynamic,
+});

package/src/components/HeaderDynamic.tsx

@@ -0,0 +1,45 @@
+import type { ViewProps } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { useHeaderMotionContextOrThrow } from '../context';
+import type { HeaderDynamicProps } from '../types';
+import {
+  cloneWithOnLayout,
+  composeOnLayoutHandlers,
+  resolveSlottableChild,
+} from '../utils';
+
+/**
+ * Marks the part of the header whose layout should define the collapsible
+ * distance.
+ *
+ * In most designs, this is the section that visually disappears while the
+ * header collapses. Its measured value feeds `measureDynamic`, which in turn
+ * can drive `progressThreshold`.
+ */
+export function HeaderDynamic(props: HeaderDynamicProps) {
+  const ctxValue = useHeaderMotionContextOrThrow(
+    'HeaderMotion.Header.Dynamic 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 />.'
+  );
+
+  if (props.asChild) {
+    return cloneWithOnLayout(
+      resolveSlottableChild('HeaderMotion.Header.Dynamic', props.children),
+      ctxValue.measureDynamic,
+      'HeaderMotion.Header.Dynamic'
+    );
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { asChild: _asChild, onLayout, ...rest } = props;
+  const resolvedOnLayout = onLayout as ViewProps['onLayout'] | undefined;
+
+  return (
+    <Animated.View
+      {...rest}
+      onLayout={composeOnLayoutHandlers(
+        resolvedOnLayout,
+        ctxValue.measureDynamic
+      )}
+    />
+  );
+}

package/src/components/HeaderMotion.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useState } from 'react';
+import { useCallback, useRef, useEffect, useMemo, useState } 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,51 +24,96 @@ 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).
-   * 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`.
+   *
+   * 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`.
    *
-   * Defaults to a function that returns the return value of `measureDynamic` unchanged.
+   * 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.
+   * Reads the value that should define the "collapsible" part of the header.
    *
-   * Receives the layout change event from React Native.
+   * This is called from `HeaderMotion.Header.Dynamic` on layout. The returned
+   * number feeds `progressThreshold` when you provide that prop as a function.
    *
-   * 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.
+   * 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;
-  /** 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>({
@@ -78,36 +124,53 @@ function HeaderMotionContextProvider<T extends string>({
   progressExtrapolation = Extrapolation.CLAMP,
   children,
 }: HeaderMotionProps<T>) {
-  const [dynamicMeasurement, setDynamicMeasurement] = useState<
-    number | undefined
-  >(undefined);
+  const dynamicMeasurement = useSharedValue<number | undefined>(undefined);
   const [originalHeaderHeight, setOriginalHeaderHeight] = useState(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);
+        const nextThreshold =
+          typeof progressThreshold === 'number'
+            ? progressThreshold
+            : progressThreshold(measured);
+        progressThresholdValue.set(nextThreshold);
       },
-      [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();
+    const nextThreshold =
+      measured === undefined ? Infinity : progressThreshold(measured);
+    progressThresholdValue.set(nextThreshold);
+  }, [progressThreshold, dynamicMeasurement, progressThresholdValue]);
 
   const measureTotalHeight = useCallback<MeasureAnimatedHeaderAndSet>(
     (e) => {
@@ -136,8 +199,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 +211,38 @@ 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 ctxValue = useMemo(
     () => ({
       progress,
       originalHeaderHeight,
       measureDynamic: setOrUpdateDynamicMeasurement,
       measureTotalHeight,
-      progressThreshold: calculatedProgressThreshold,
+      headerPanMomentumOffset,
+      progressThreshold: progressThresholdValue,
       scrollValues,
+      scrollToRef,
       activeScrollId: activeScrollId as SharedValue<string> | undefined,
     }),
     [
       originalHeaderHeight,
       progress,
       measureTotalHeight,
+      headerPanMomentumOffset,
       setOrUpdateDynamicMeasurement,
       scrollValues,
       activeScrollId,
-      calculatedProgressThreshold,
+      progressThresholdValue,
     ]
   );
 

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>
+  );
+}