react-native-header-motion 0.1.0

package/src/hooks/useActiveScrollId.ts

@@ -0,0 +1,59 @@
+import { useCallback, useMemo, useState } from 'react';
+import { useSharedValue } from 'react-native-reanimated';
+import type { ActiveScrollIdValues, SetActiveScrollId } from '../types';
+
+/**
+ * Hook to manage active scroll ID for multi-scroll scenarios (e.g. tabs with different scroll views).
+ * Returns both a state value and a shared value, along with a setter function.
+ *
+ * Use this when you have multiple scroll views (like in a tabbed interface) and need to
+ * track which one is currently active. Pass the shared value to `HeaderMotion`'s `activeScrollId` prop.
+ *
+ * @template T - The type of the scroll ID string
+ * @param initialActiveScrollId - The initial active scroll ID
+ * @returns A tuple containing:
+ * - `[0]`: Object with `state` (React state) and `sv` (shared value) for the active scroll ID
+ * - `[1]`: Function to set the active scroll ID
+ *
+ * @example
+ * ```tsx
+ * function TabbedScrollView() {
+ *   const [activeScroll, setActiveScroll] = useActiveScrollId('tab1');
+ *
+ *   return (
+ *     <HeaderMotion activeScrollId={activeScroll.sv}>
+ *       <Tabs onTabChange={setActiveScroll}>
+ *         <Tab id="tab1" />
+ *         <Tab id="tab2" />
+ *       </Tabs>
+ *     </HeaderMotion>
+ *   );
+ * }
+ * ```
+ */
+export function useActiveScrollId<T extends string>(
+  initialActiveScrollId: T
+): [ActiveScrollIdValues<T>, SetActiveScrollId<T>] {
+  const [activeScrollIdState, setActiveScrollIdState] = useState<T>(
+    initialActiveScrollId
+  );
+  const activeScrollIdSv = useSharedValue<T>(initialActiveScrollId);
+
+  const setActiveScrollId = useCallback<SetActiveScrollId<T>>(
+    (newId) => {
+      setActiveScrollIdState(newId);
+      activeScrollIdSv.set(newId);
+    },
+    [setActiveScrollIdState, activeScrollIdSv]
+  );
+
+  const values = useMemo<ActiveScrollIdValues<T>>(
+    () => ({
+      state: activeScrollIdState,
+      sv: activeScrollIdSv,
+    }),
+    [activeScrollIdState, activeScrollIdSv]
+  );
+
+  return [values, setActiveScrollId];
+}

package/src/hooks/useMotionProgress.ts

@@ -0,0 +1,56 @@
+import { useContext } from 'react';
+import { HeaderMotionContext } 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.
+ *
+ * Must be used within a {@link HeaderMotion} component.
+ *
+ * @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
+ *
+ * @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>
+ *   )
+ * }
+ * ```
+ */
+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 } =
+    ctxValue;
+
+  return {
+    progress,
+    measureTotalHeight,
+    measureDynamic,
+    progressThreshold,
+  };
+}

package/src/hooks/useScrollManager.ts

@@ -0,0 +1,186 @@
+import { useContext, useCallback, useEffect } from 'react';
+import {
+  measure,
+  scrollTo,
+  useAnimatedReaction,
+  useAnimatedRef,
+  useAnimatedScrollHandler,
+  useAnimatedStyle,
+  type ScrollHandler,
+} 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';
+
+/**
+ * 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).
+ * @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 function useScrollManager(scrollId?: string): ScrollManagerConfig {
+  const ctxValue = useContext(HeaderMotionContext);
+  if (!ctxValue) {
+    throw new Error(
+      'useScrollManager must be used within a HeaderMotion component'
+    );
+  }
+
+  const {
+    scrollValues,
+    progress,
+    activeScrollId,
+    progressThreshold,
+    originalHeaderHeight,
+  } = ctxValue;
+  const id = scrollId ?? DEFAULT_SCROLL_ID;
+
+  const animatedRef = useAnimatedRef<any>(); // TODO: better typing
+
+  useEffect(() => {
+    return () => {
+      scheduleOnUI((scrollIdToDelete) => {
+        scrollValues.modify((value) => {
+          'worklet';
+          delete value[scrollIdToDelete];
+          return value;
+        });
+      }, id);
+    };
+  }, [scrollValues, id]);
+
+  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 ||
+        id === currentActiveScrollId ||
+        oldProgress === null
+      ) {
+        return;
+      }
+
+      if (!scrollValues.get()[id]) {
+        scrollValues.modify((value) => {
+          (value as ScrollValues)[id] = getInitialScrollValue();
+          return value;
+        });
+      }
+
+      let newCur = -1;
+
+      scrollValues.modify((value) => {
+        let scrollValue = value[id];
+        if (!scrollValue) {
+          (value as ScrollValues)[id] = getInitialScrollValue();
+          scrollValue = value[id]!;
+        }
+
+        const progressDiff = oldProgress - newProgress;
+        newCur = scrollValue.current - progressDiff * progressThreshold;
+        const newMin = newCur - newProgress * progressThreshold;
+        scrollValue.current = newCur;
+        scrollValue.min = newMin;
+
+        return value;
+      });
+
+      if (newCur >= 0) {
+        scrollTo(animatedRef, 0, newCur, false);
+      }
+    }
+  );
+
+  const scrollHandler = useCallback<ScrollHandler>(
+    (e) => {
+      'worklet';
+
+      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);
+        }
+
+        return value;
+      });
+    },
+    [scrollValues, id, activeScrollId, progressThreshold]
+  );
+
+  const onScroll = useAnimatedScrollHandler(scrollHandler);
+
+  const minHeightContentContainerStyle = useAnimatedStyle(() => {
+    if (globalThis.__RUNTIME_KIND === RuntimeKind.ReactNative) {
+      return {};
+    }
+
+    const measurement = measure(animatedRef);
+
+    if (!measurement) {
+      return {};
+    }
+
+    return {
+      minHeight: measurement.height + progressThreshold,
+    };
+  });
+
+  const scrollableProps = {
+    onScroll,
+    scrollEventThrottle: 16,
+    ref: animatedRef,
+  };
+  const headerMotionContext = {
+    originalHeaderHeight,
+    minHeightContentContainerStyle,
+  };
+
+  return { scrollableProps, headerMotionContext };
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+import {
+  AnimatedHeaderBase,
+  HeaderBase,
+  HeaderMotionContextProvider,
+  HeaderMotionFlatList,
+  HeaderMotionHeader,
+  HeaderMotionScrollManager,
+  HeaderMotionScrollView,
+  type HeaderMotionFlatListProps,
+  type HeaderMotionHeaderProps,
+  type HeaderMotionProps,
+  type HeaderMotionScrollManagerProps,
+  type HeaderMotionScrollViewProps,
+} from './components';
+import type { ReactElement } from 'react';
+
+/**
+ * Compound component type for HeaderMotion.
+ * Provides the main context provider and sub-components for building collapsible headers.
+ */
+type HeaderMotionComponent = {
+  /** Main context provider component */
+  <T extends string>(props: HeaderMotionProps<T>): ReactElement;
+  /** Component for providing motion progress properties to animated headers.
+   * Use to pass props to the header components in React Navigation / Expo Router, which cannot access HeaderMotion's context and `useMotionProgress` otherwise.
+   */
+  Header: typeof HeaderMotionHeader;
+  /** Component for custom scroll implementations */
+  ScrollManager: typeof HeaderMotionScrollManager;
+  /** Animated ScrollView component with header motion integration */
+  ScrollView: typeof HeaderMotionScrollView;
+  /** Animated FlatList component with header motion integration */
+  FlatList: typeof HeaderMotionFlatList;
+};
+
+/**
+ * Main HeaderMotion component.
+ * A compound component that provides context for collapsible header animations.
+ *
+ * @example
+ * ```tsx
+ * <HeaderMotion>
+ *   <HeaderMotion.Header>
+ *     {(headerProps) => (
+ *       <Stack.Screen
+ *         options={{
+ *           header: () => (
+ *             <MyAnimatedHeader {...headerProps} />
+ *           ),
+ *         }}
+ *       />
+ *     )}
+ *   </HeaderMotion.Header>
+ *   <HeaderMotion.ScrollView>
+ *     <MyScrollableContent />
+ *   </HeaderMotion.ScrollView>
+ * </HeaderMotion>
+ * ```
+ */
+const HeaderMotion = HeaderMotionContextProvider as HeaderMotionComponent;
+HeaderMotion.Header = HeaderMotionHeader;
+HeaderMotion.ScrollManager = HeaderMotionScrollManager;
+HeaderMotion.ScrollView = HeaderMotionScrollView;
+HeaderMotion.FlatList = HeaderMotionFlatList;
+
+export default HeaderMotion;
+export * from './hooks';
+export type * from './types';
+export { AnimatedHeaderBase, HeaderBase };
+export type {
+  HeaderMotionFlatListProps,
+  HeaderMotionHeaderProps,
+  HeaderMotionProps,
+  HeaderMotionScrollManagerProps,
+  HeaderMotionScrollViewProps,
+};

package/src/types.ts

@@ -0,0 +1,62 @@
+import type { LayoutChangeEvent, ScrollViewProps } from 'react-native';
+import type { AnimatedRef, SharedValue } from 'react-native-reanimated';
+import { DEFAULT_SCROLL_ID } from './utils/defaults';
+
+export type Progress = SharedValue<number>;
+
+export type ProgressThreshold =
+  | number
+  | ((measuredHeaderValue: number) => number);
+export type MeasureAnimatedHeader = (e: LayoutChangeEvent) => number;
+export type MeasureAnimatedHeaderAndSet = (e: LayoutChangeEvent) => void;
+
+export type ActiveScrollIdValues<T extends string = string> = {
+  state: T;
+  sv: SharedValue<T>;
+};
+export type SetActiveScrollId<T extends string> = (newId: T) => void;
+
+export interface ScrollValue {
+  min: number;
+  current: number;
+}
+export type ScrollValues = Record<string, ScrollValue> & {
+  [key in typeof DEFAULT_SCROLL_ID]?: ScrollValue;
+};
+
+export type WithCollapsibleHeaderProps<
+  T extends Record<string, unknown> = Record<string, unknown>
+> = T & MotionProgress;
+
+export type WithCollapsiblePagedHeaderProps<
+  Tab extends string = string,
+  T extends Record<string, unknown> = Record<string, unknown>
+> = WithCollapsibleHeaderProps<T> & {
+  onTabChange: (newTab: Tab) => void;
+  activeTab: Tab;
+};
+
+export interface MotionProgress {
+  progress: Progress;
+  progressThreshold: number;
+  measureTotalHeight: MeasureAnimatedHeaderAndSet;
+  measureDynamic: MeasureAnimatedHeaderAndSet;
+}
+
+export interface ScrollManagerHeaderMotionContext {
+  originalHeaderHeight: number;
+  minHeightContentContainerStyle:
+    | {}
+    | {
+        minHeight: number;
+      };
+}
+
+export interface ScrollManagerConfig {
+  scrollableProps: Required<
+    Pick<ScrollViewProps, 'onScroll' | 'scrollEventThrottle'>
+  > & {
+    ref: AnimatedRef<any>; // TODO: better typing
+  };
+  headerMotionContext: ScrollManagerHeaderMotionContext;
+}

package/src/utils/defaults.ts

@@ -0,0 +1,16 @@
+import type { MeasureAnimatedHeader, ProgressThreshold } from '../types';
+
+const DEFAULT_PROGRESS_THRESHOLD: ProgressThreshold = (measuredHeaderValue) =>
+  measuredHeaderValue;
+const DEFAULT_MEASURE_DYNAMIC: MeasureAnimatedHeader = (e) =>
+  e.nativeEvent.layout.height;
+
+// Symbol doesn't work?
+// const DEFAULT_SCROLL_ID = Symbol("HEADER_MOTION_DEFAULT_SCROLL_ID");
+const DEFAULT_SCROLL_ID = '__HEADER_MOTION_DEFAULT_SCROLL_ID__';
+
+export {
+  DEFAULT_MEASURE_DYNAMIC,
+  DEFAULT_PROGRESS_THRESHOLD,
+  DEFAULT_SCROLL_ID,
+};

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './defaults';
+export * from './values';

package/src/utils/values.ts

@@ -0,0 +1,6 @@
+import type { ScrollValue } from '../types';
+
+export function getInitialScrollValue(): ScrollValue {
+  'worklet';
+  return { min: 0, current: 0 };
+}