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

package/src/index.ts

@@ -1,76 +1,122 @@
 import {
-  AnimatedHeaderBase,
-  HeaderBase,
+  createHeaderMotionScrollable,
+  Bridge,
   HeaderMotionContextProvider,
-  HeaderMotionFlatList,
-  HeaderMotionHeader,
-  HeaderMotionScrollManager,
-  HeaderMotionScrollView,
+  FlatList,
+  Header,
+  NavigationBridge,
+  ScrollManager,
+  ScrollView,
+  type CreateHeaderMotionScrollableOptions,
+  type HeaderProps,
+  type HeaderMotionBridgeProps,
   type HeaderMotionFlatListProps,
-  type HeaderMotionHeaderProps,
+  type HeaderMotionNavigationBridgeProps,
   type HeaderMotionProps,
   type HeaderMotionScrollManagerProps,
+  type HeaderMotionScrollableOwnProps,
   type HeaderMotionScrollViewProps,
 } from './components';
-import type { ReactElement } from 'react';
+import type { HeaderDynamicProps } from './types';
 
-/**
- * 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.
+type HeaderMotionCompound = typeof HeaderMotionContextProvider & {
+  /**
+   * Header container that measures the total header height and can optionally
+   * make the header surface pannable.
+   *
+   * Use `HeaderMotion.Header.Dynamic` inside it to mark the part of the header
+   * that should define the collapse distance.
+   */
+  Header: typeof Header;
+  /**
+   * Captures the current HeaderMotion context and exposes it through a render
+   * function so it can be forwarded across a React tree boundary.
+   *
+   * This is primarily useful for navigation-rendered headers.
+   */
+  Bridge: typeof Bridge;
+  /**
+   * Re-provides a previously captured HeaderMotion context value in another
+   * subtree.
+   *
+   * This is primarily useful for navigation libraries that render headers
+   * outside the screen subtree where `HeaderMotion` lives.
+   */
+  NavigationBridge: typeof NavigationBridge;
+  /**
+   * Render-prop wrapper for managing a custom scrollable.
+   *
+   * Prefer `createHeaderMotionScrollable()` for most custom integrations. Use
+   * `ScrollManager` only when the factory approach is not flexible enough.
    */
-  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;
+  ScrollManager: typeof ScrollManager;
+  /**
+   * Pre-wired `Animated.ScrollView` that participates in HeaderMotion's scroll
+   * tracking and header offsetting.
+   */
+  ScrollView: typeof ScrollView;
+  /**
+   * Pre-wired `Animated.FlatList` that participates in HeaderMotion's scroll
+   * tracking and header offsetting.
+   */
+  FlatList: typeof FlatList;
 };
 
 /**
  * Main HeaderMotion component.
- * A compound component that provides context for collapsible header animations.
+ * Root provider and compound entrypoint for the library.
+ *
+ * It tracks header measurements, derives the shared `progress` value, and
+ * exposes the pre-wired subcomponents used to connect headers and scrollables.
  *
  * @example
  * ```tsx
  * <HeaderMotion>
- *   <HeaderMotion.Header>
- *     {(headerProps) => (
+ *   <HeaderMotion.Bridge>
+ *     {(value) => (
  *       <Stack.Screen
  *         options={{
  *           header: () => (
- *             <MyAnimatedHeader {...headerProps} />
+ *             <HeaderMotion.NavigationBridge value={value}>
+ *               <MyAnimatedHeader />
+ *             </HeaderMotion.NavigationBridge>
  *           ),
  *         }}
  *       />
  *     )}
- *   </HeaderMotion.Header>
+ *   </HeaderMotion.Bridge>
  *   <HeaderMotion.ScrollView>
  *     <MyScrollableContent />
  *   </HeaderMotion.ScrollView>
  * </HeaderMotion>
  * ```
  */
-const HeaderMotion = HeaderMotionContextProvider as HeaderMotionComponent;
-HeaderMotion.Header = HeaderMotionHeader;
-HeaderMotion.ScrollManager = HeaderMotionScrollManager;
-HeaderMotion.ScrollView = HeaderMotionScrollView;
-HeaderMotion.FlatList = HeaderMotionFlatList;
+const HeaderMotion: HeaderMotionCompound = Object.assign(
+  HeaderMotionContextProvider,
+  {
+    Header,
+    Bridge,
+    NavigationBridge,
+    ScrollManager,
+    ScrollView,
+    FlatList,
+  }
+);
 
 export default HeaderMotion;
 export * from './hooks';
 export type * from './types';
-export { AnimatedHeaderBase, HeaderBase };
+export { createHeaderMotionScrollable };
+export { Bridge, Header, NavigationBridge };
 export type {
+  CreateHeaderMotionScrollableOptions,
+  HeaderDynamicProps,
   HeaderMotionFlatListProps,
-  HeaderMotionHeaderProps,
+  HeaderMotionBridgeProps,
+  HeaderMotionNavigationBridgeProps,
   HeaderMotionProps,
   HeaderMotionScrollManagerProps,
+  HeaderMotionScrollableOwnProps,
   HeaderMotionScrollViewProps,
+  HeaderProps,
 };

package/src/types.ts

@@ -1,13 +1,58 @@
 import type { ReactElement } from 'react';
 import type {
   LayoutChangeEvent,
-  RefreshControlProps,
   ScrollViewProps,
+  ViewProps,
 } from 'react-native';
-import type { AnimatedRef, SharedValue } from 'react-native-reanimated';
+import type {
+  AnimatedProps,
+  AnimatedRef,
+  SharedValue,
+} from 'react-native-reanimated';
 import { DEFAULT_SCROLL_ID } from './utils/defaults';
+import type { InstanceOrElement } from 'react-native-reanimated/lib/typescript/commonTypes';
+import type {
+  GestureStateChangeEvent,
+  PanGestureHandlerEventPayload,
+} from 'react-native-gesture-handler';
+import type { WithDecayConfig } from 'react-native-reanimated';
 
 export type Progress = SharedValue<number>;
+export type HeaderMotionOffsetStrategy =
+  | 'padding'
+  | 'margin'
+  | 'top'
+  | 'translate'
+  | 'none';
+
+export interface HeaderMotionOffsetProps {
+  /**
+   * How the scrollable content should be pushed below the measured header.
+   *
+   * `padding` is the safest default for most screens. `margin`, `top`, and
+   * `translate` can be useful when the scrollable or its children need a
+   * different layout behavior.
+   *
+   * `top` and `translate` add bottom compensation so the end of the content
+   * remains reachable.
+   *
+   * @default 'padding'
+   */
+  headerOffsetStrategy?: HeaderMotionOffsetStrategy;
+  /**
+   * Adds a minimum content height so scrollables with short content can still collapse the
+   * header completely.
+   *
+   * **Experimental: this relies on extra layout measurement and may still be
+   * refined.**
+   *
+   * Enable this when some screens do not have enough content to naturally
+   * scroll through the full collapse distance.
+   *
+   * @default false
+   */
+  ensureScrollableContentMinHeight?: boolean;
+}
 
 export type ProgressThreshold =
   | number
@@ -29,44 +74,59 @@ 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 interface MotionProgress {
+  progress: Progress;
+  progressThreshold: SharedValue<number>;
+}
+
+export type HeaderPanDecayEvent =
+  GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+
+export type HeaderPanDecayConfig =
+  | WithDecayConfig
+  | ((event: HeaderPanDecayEvent) => WithDecayConfig);
 
-export type WithCollapsiblePagedHeaderProps<
-  Tab extends string = string,
-  T extends Record<string, unknown> = Record<string, unknown>
-> = WithCollapsibleHeaderProps<T> & {
-  onTabChange: (newTab: Tab) => void;
-  activeTab: Tab;
+export type HeaderAsChildProps = {
+  asChild: true;
+  children: ReactElement;
 };
 
-export interface MotionProgress {
-  progress: Progress;
-  progressThreshold: number;
+export type HeaderDefaultProps = AnimatedProps<ViewProps> & {
+  asChild?: false;
+};
+
+export type HeaderDynamicProps = HeaderDefaultProps | HeaderAsChildProps;
+
+export interface HeaderMotionBridgeValue extends MotionProgress {
   measureTotalHeight: MeasureAnimatedHeaderAndSet;
   measureDynamic: MeasureAnimatedHeaderAndSet;
+  headerPanMomentumOffset: SharedValue<number | null>;
+  scrollValues: SharedValue<ScrollValues>;
+  activeScrollId: SharedValue<string> | undefined;
+  scrollToRef: React.RefObject<ScrollTo | null>;
+  originalHeaderHeight: number;
 }
 
 export interface ScrollManagerHeaderMotionContext {
   originalHeaderHeight: number;
-  minHeightContentContainerStyle:
-    | {}
-    | {
-        minHeight: number;
-      };
+  contentContainerMinHeight?: number;
 }
 
-export interface ScrollManagerConfig {
-  scrollableProps: Required<
-    Pick<ScrollViewProps, 'onScroll' | 'scrollEventThrottle'>
-  > & {
-    refreshControl?: ReactElement<RefreshControlProps>;
-    ref: AnimatedRef<any>; // TODO: better typing
+export interface ScrollManagerConfig<TRef extends InstanceOrElement = any> {
+  scrollableProps: Pick<ScrollViewProps, 'onScroll' | 'onLayout'> & {
+    refreshControl?: ReactElement;
+    ref: AnimatedRef<TRef>;
   };
   headerMotionContext: ScrollManagerHeaderMotionContext;
 }
 
+export type ScrollTo = (y: number, options?: ScrollToOptions) => void;
+
 export type ScrollHandlerContext = {
   lastOffset: number | undefined;
 };
+
+interface ScrollToOptions {
+  isValueDelta?: boolean;
+  animated?: boolean;
+}

package/src/utils/defaults.ts

@@ -1,15 +1,21 @@
-import type { MeasureAnimatedHeader, ProgressThreshold } from '../types';
+import type {
+  HeaderMotionOffsetStrategy,
+  MeasureAnimatedHeader,
+  ProgressThreshold,
+} from '../types';
 
 const DEFAULT_PROGRESS_THRESHOLD: ProgressThreshold = (measuredHeaderValue) =>
   measuredHeaderValue;
 const DEFAULT_MEASURE_DYNAMIC: MeasureAnimatedHeader = (e) =>
   e.nativeEvent.layout.height;
+const DEFAULT_HEADER_OFFSET_STRATEGY: HeaderMotionOffsetStrategy = 'padding';
 
 // 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_HEADER_OFFSET_STRATEGY,
   DEFAULT_MEASURE_DYNAMIC,
   DEFAULT_PROGRESS_THRESHOLD,
   DEFAULT_SCROLL_ID,

package/src/utils/header.tsx

@@ -0,0 +1,52 @@
+import {
+  Fragment,
+  cloneElement,
+  isValidElement,
+  type ReactElement,
+} from 'react';
+import type { ViewProps } from 'react-native';
+
+export type SlottableElementProps = {
+  onLayout?: ViewProps['onLayout'];
+};
+
+export type SlottableElement = ReactElement<SlottableElementProps>;
+
+export function composeOnLayoutHandlers(
+  userHandler: ViewProps['onLayout'],
+  internalHandler: ViewProps['onLayout']
+) {
+  return (e: Parameters<NonNullable<ViewProps['onLayout']>>[0]) => {
+    internalHandler?.(e);
+    userHandler?.(e);
+  };
+}
+
+export function resolveSlottableChild(
+  componentName: string,
+  child: ReactElement
+) {
+  if (!isValidElement(child) || child.type === Fragment) {
+    throw new Error(
+      `${componentName} with \`asChild\` expects a single valid React element child that accepts \`onLayout\`.`
+    );
+  }
+
+  return child as SlottableElement;
+}
+
+export function cloneWithOnLayout(
+  child: SlottableElement,
+  onLayout: ViewProps['onLayout'],
+  componentName: string
+) {
+  if (!isValidElement(child)) {
+    throw new Error(
+      `${componentName} with \`asChild\` expects a valid React element child.`
+    );
+  }
+
+  return cloneElement(child, {
+    onLayout: composeOnLayoutHandlers(child.props.onLayout, onLayout),
+  });
+}

package/src/utils/headerOffsetStyle.ts

@@ -0,0 +1,40 @@
+import type { SharedValue } from 'react-native-reanimated';
+import type { HeaderMotionOffsetStrategy } from '../types';
+import { DEFAULT_HEADER_OFFSET_STRATEGY } from './defaults';
+
+type HeaderOffsetValue = number | SharedValue<number>;
+
+type HeaderOffsetStyle =
+  | undefined
+  | { paddingTop: HeaderOffsetValue }
+  | { marginTop: HeaderOffsetValue }
+  | { top: HeaderOffsetValue; paddingBottom: HeaderOffsetValue }
+  | {
+      transform: [{ translateY: HeaderOffsetValue }];
+      paddingBottom: HeaderOffsetValue;
+    };
+
+export function resolveHeaderOffsetStyle(
+  originalHeaderHeight: HeaderOffsetValue,
+  headerOffsetStrategy: HeaderMotionOffsetStrategy = DEFAULT_HEADER_OFFSET_STRATEGY
+): HeaderOffsetStyle {
+  switch (headerOffsetStrategy) {
+    case 'none':
+      return undefined;
+    case 'margin':
+      return { marginTop: originalHeaderHeight };
+    case 'top':
+      return {
+        top: originalHeaderHeight,
+        paddingBottom: originalHeaderHeight,
+      };
+    case 'translate':
+      return {
+        transform: [{ translateY: originalHeaderHeight }],
+        paddingBottom: originalHeaderHeight,
+      };
+    case 'padding':
+    default:
+      return { paddingTop: originalHeaderHeight };
+  }
+}

package/src/utils/index.ts

@@ -1,2 +1,5 @@
 export * from './defaults';
+export * from './header';
+export * from './headerOffsetStyle';
 export * from './values';
+export * from './refreshControl';

package/src/utils/refreshControl.tsx

@@ -0,0 +1,118 @@
+import {
+  cloneElement,
+  createElement,
+  isValidElement,
+  type ReactElement,
+} from 'react';
+import { RefreshControl, type RefreshControlProps } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+import Animated, { useAnimatedProps } from 'react-native-reanimated';
+
+// FIXME: Types are a mess here
+
+const AnimatedRefreshControl = Animated.createAnimatedComponent(RefreshControl);
+
+type MaybeShared<T> = T | SharedValue<T | undefined>;
+
+export interface ResolveRefreshControlOptions {
+  refreshControl?: MaybeShared<ReactElement<RefreshControlProps>>;
+  refreshing?: MaybeShared<boolean>;
+  onRefresh?: MaybeShared<() => void>;
+  progressViewOffset: MaybeShared<number> | SharedValue<number>;
+}
+
+export function resolveRefreshControl({
+  refreshControl,
+  refreshing,
+  onRefresh,
+  progressViewOffset,
+}: ResolveRefreshControlOptions):
+  | ReactElement<
+      RefreshControlProps | React.ComponentProps<typeof AnimatedRefreshControl>
+    >
+  | undefined {
+  if (!refreshControl) {
+    return createRefreshControlWithOffset({
+      refreshing,
+      onRefresh,
+      progressViewOffset,
+    });
+  }
+
+  return isValidElement<RefreshControlProps>(refreshControl)
+    ? injectProgressViewOffset(refreshControl, progressViewOffset)
+    : undefined;
+}
+
+function createRefreshControlWithOffset({
+  refreshing,
+  onRefresh,
+  progressViewOffset,
+}: Omit<ResolveRefreshControlOptions, 'refreshControl'>) {
+  if (!onRefresh) {
+    return undefined;
+  }
+
+  return createElement(ResolvedRefreshControl, {
+    refreshing: (refreshing as boolean) ?? false,
+    onRefresh: onRefresh as () => void,
+    progressViewOffset: progressViewOffset as number,
+  }) as ReactElement<RefreshControlProps>;
+}
+
+function injectProgressViewOffset(
+  refreshControl: ReactElement<RefreshControlProps>,
+  progressViewOffset: MaybeShared<number> | SharedValue<number>
+) {
+  const offset = refreshControl.props.progressViewOffset ?? progressViewOffset;
+
+  if (!isSharedValue<number>(offset)) {
+    return cloneElement(refreshControl, {
+      progressViewOffset: offset as number,
+    });
+  }
+
+  return createElement(ResolvedRefreshControl, {
+    ...refreshControl.props,
+    progressViewOffset: progressViewOffset as number,
+  });
+}
+
+function ResolvedRefreshControl({
+  refreshing,
+  onRefresh,
+  progressViewOffset,
+  ...props
+}: React.ComponentProps<typeof AnimatedRefreshControl>) {
+  const animatedProps = useAnimatedProps<RefreshControlProps>(() => {
+    return {
+      ...(isSharedValue(refreshing) ? { refreshing: refreshing.value } : {}),
+      ...(isSharedValue(onRefresh) ? { onRefresh: onRefresh.value } : {}),
+      ...(isSharedValue(progressViewOffset)
+        ? { progressViewOffset: progressViewOffset.value }
+        : {}),
+    };
+  });
+
+  const nonAnimatedProps = {
+    ...(isSharedValue(refreshing) ? {} : { refreshing }),
+    ...(isSharedValue(onRefresh) ? {} : { onRefresh }),
+    ...(isSharedValue(progressViewOffset) ? {} : { progressViewOffset }),
+  };
+
+  return (
+    <AnimatedRefreshControl
+      {...props}
+      {...nonAnimatedProps}
+      refreshing={nonAnimatedProps.refreshing as boolean}
+      animatedProps={animatedProps}
+    />
+  );
+}
+
+function isSharedValue<T>(
+  value: MaybeShared<T> | SharedValue<T>
+): value is SharedValue<T> {
+  'worklet';
+  return typeof value === 'object' && value !== null && 'value' in value;
+}

package/src/utils/values.ts

@@ -1,6 +1,62 @@
-import type { ScrollValue } from '../types';
+import type { SharedValue } from 'react-native-reanimated';
+import type { ScrollValue, ScrollValues } from '../types';
+import { DEFAULT_SCROLL_ID } from './defaults';
 
 export function getInitialScrollValue(): ScrollValue {
   'worklet';
   return { min: 0, current: 0 };
 }
+
+export function ensureScrollValueRegistered(
+  scrollValues: SharedValue<ScrollValues>,
+  id: string
+): ScrollValues {
+  'worklet';
+
+  const values = scrollValues.get();
+  if (values[id]) {
+    return values;
+  }
+
+  scrollValues.modify((value) => {
+    if (!value[id]) {
+      (value as ScrollValues)[id] = getInitialScrollValue();
+    }
+
+    return value;
+  });
+
+  return scrollValues.get();
+}
+
+export function warnIfMissingActiveScrollId(
+  scrollValues: ScrollValues,
+  id: string,
+  activeScrollId: string | undefined
+): void {
+  'worklet';
+
+  if (!__DEV__ || activeScrollId || id === DEFAULT_SCROLL_ID) {
+    return;
+  }
+
+  let nonDefaultCount = 0;
+  let nonDefaultIds = '';
+
+  for (const key in scrollValues) {
+    if (key === DEFAULT_SCROLL_ID) {
+      continue;
+    }
+
+    nonDefaultCount += 1;
+    nonDefaultIds = nonDefaultIds ? `${nonDefaultIds}, ${key}` : key;
+  }
+
+  if (nonDefaultCount < 1) {
+    return;
+  }
+
+  console.warn(
+    `[react-native-header-motion] Explicit scrollIds (${nonDefaultIds}) are registered but no activeScrollId was provided. Pass useActiveScrollId(...).sv to <HeaderMotion activeScrollId={...}> to keep header motion deterministic.`
+  );
+}

package/lib/module/components/HeaderBase.js

@@ -1,59 +0,0 @@
-"use strict";
-
-import { StyleSheet, View } from 'react-native';
-import Animated from 'react-native-reanimated';
-import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * Base header component with absolute positioning.
- * Provides a foundation for building headers that need to be positioned absolutely.
- *
- * @example
- * ```tsx
- * <HeaderBase
- *   onLayout={measureTotalHeight}
- * >
- *   ...
- * </HeaderBase>
- * ```
- */
-export function HeaderBase({
-  style,
-  ...rest
-}) {
-  return /*#__PURE__*/_jsx(View, {
-    style: [style, styles.container],
-    ...rest
-  });
-}
-
-/**
- * Animated version of HeaderBase using Reanimated's Animated.View.
- * Use this when you need to animate the header based on scroll progress.
- *
- * @example
- * ```tsx
- * <AnimatedHeaderBase
- *   onLayout={measureTotalHeight}
- *   style={[{ paddingTop: insets.top }, animatedStyle]}
- * >
- *   ...
- * </AnimatedHeaderBase>
- * ```
- */
-export function AnimatedHeaderBase({
-  style,
-  ...rest
-}) {
-  return /*#__PURE__*/_jsx(Animated.View, {
-    style: [style, styles.container],
-    ...rest
-  });
-}
-const styles = StyleSheet.create({
-  container: {
-    position: 'absolute',
-    left: 0,
-    right: 0
-  }
-});
-//# sourceMappingURL=HeaderBase.js.map

package/lib/module/components/HeaderBase.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["StyleSheet","View","Animated","jsx","_jsx","HeaderBase","style","rest","styles","container","AnimatedHeaderBase","create","position","left","right"],"sourceRoot":"../../../src","sources":["components/HeaderBase.tsx"],"mappings":";;AAAA,SAASA,UAAU,EAAEC,IAAI,QAAwB,cAAc;AAC/D,OAAOC,QAAQ,MAA8B,yBAAyB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAKvE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,UAAUA,CAAC;EAAEC,KAAK;EAAE,GAAGC;AAAsB,CAAC,EAAE;EAC9D,oBAAOH,IAAA,CAACH,IAAI;IAACK,KAAK,EAAE,CAACA,KAAK,EAAEE,MAAM,CAACC,SAAS,CAAE;IAAA,GAAKF;EAAI,CAAG,CAAC;AAC7D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASG,kBAAkBA,CAAC;EACjCJ,KAAK;EACL,GAAGC;AACoB,CAAC,EAAE;EAC1B,oBAAOH,IAAA,CAACF,QAAQ,CAACD,IAAI;IAACK,KAAK,EAAE,CAACA,KAAK,EAAEE,MAAM,CAACC,SAAS,CAAE;IAAA,GAAKF;EAAI,CAAG,CAAC;AACtE;AAEA,MAAMC,MAAM,GAAGR,UAAU,CAACW,MAAM,CAAC;EAC/BF,SAAS,EAAE;IACTG,QAAQ,EAAE,UAAU;IACpBC,IAAI,EAAE,CAAC;IACPC,KAAK,EAAE;EACT;AACF,CAAC,CAAC","ignoreList":[]}