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

package/src/hooks/useActiveScrollId.ts

@@ -3,17 +3,18 @@ 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.
+ * Keeps a React state value and a shared value in sync for the currently active
+ * scrollable.
  *
- * 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.
+ * Use this when one header is shared across multiple scroll views, for example
+ * pager pages or tabs. Pass `values.sv` to `HeaderMotion` and use the setter
+ * whenever the active page changes.
  *
  * @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
+ * - an object with both the React `state` and shared-value `sv`
+ * - a setter that updates both in lockstep
  *
  * @example
  * ```tsx

package/src/hooks/useHeaderMotionBridge.ts

@@ -0,0 +1,15 @@
+import { useHeaderMotionContextOrThrow } from '../context';
+import type { HeaderMotionBridgeValue } from '../types';
+
+/**
+ * Returns the full internal HeaderMotion context value.
+ *
+ * Most app code should use `useMotionProgress()` instead. Reach for this hook
+ * only when you need to carry HeaderMotion context across a tree boundary and
+ * re-provide it somewhere else.
+ */
+export function useHeaderMotionBridge(): HeaderMotionBridgeValue {
+  return useHeaderMotionContextOrThrow(
+    'useHeaderMotionBridge must be used within <HeaderMotion />. Use it only when bridging context into a separate subtree with <HeaderMotion.Bridge /> and <HeaderMotion.NavigationBridge />.'
+  );
+}

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,56 +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 } =
-    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,
   };
 }