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

package/src/components/createHeaderMotionScrollable.tsx

@@ -0,0 +1,438 @@
+import {
+  forwardRef,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ComponentRef,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from 'react';
+import type { LayoutChangeEvent, ScrollViewProps } from 'react-native';
+import Animated, {
+  type AnimatedProps,
+  type AnimatedRef,
+} from 'react-native-reanimated';
+import type { InstanceOrElement } from 'react-native-reanimated/lib/typescript/commonTypes';
+import { useScrollManager, type UseScrollManagerOptions } from '../hooks';
+import type { HeaderMotionOffsetProps } from '../types';
+import { resolveHeaderOffsetStyle } from '../utils';
+
+export type HeaderMotionScrollableOwnProps<
+  TRef extends InstanceOrElement = any
+> = HeaderMotionOffsetProps & {
+  /**
+   * Unique identifier for this scrollable when one header is shared across
+   * multiple scrollables.
+   */
+  scrollId?: string;
+  /**
+   * Animated ref to reuse instead of letting HeaderMotion create one.
+   */
+  animatedRef?: AnimatedRef<TRef> | AnimatedRef;
+};
+
+export interface CreateHeaderMotionScrollableOptions<
+  TIsComponentAnimated extends boolean = boolean
+> {
+  displayName?: string;
+  /**
+   * If true, this function will NOT call Animated.createAnimatedComponent internally.
+   * Useful when you are creating a HeaderMotionScrollable from lists that already export their
+   * own (Re)animated components (e.g. LegendList).
+   *
+   * @default false
+   */
+  isComponentAnimated?: TIsComponentAnimated;
+  /**
+   * Controls how HeaderMotion injects content-container spacing.
+   *
+   * - `children`: wraps `children` in an inner `Animated.View`
+   * - `renderScrollComponent`: injects a custom scroll component that wraps the content
+   *
+   * Use `children` for ScrollView-like components. Use
+   * `renderScrollComponent` for FlatList-like components that own their
+   * internal scroll container.
+   *
+   * @default 'renderScrollComponent'
+   */
+  contentContainerMode?: ContentContainerMode;
+}
+
+export function createHeaderMotionScrollable<
+  TScrollableComponent extends ScrollableComponent,
+  TIsComponentAnimated extends boolean = false
+>(
+  ScrollableComponent: TScrollableComponent,
+  options?: CreateHeaderMotionScrollableOptions<TIsComponentAnimated>
+): HeaderMotionScrollableComponent<TScrollableComponent, TIsComponentAnimated> {
+  const {
+    isComponentAnimated = false,
+    contentContainerMode = 'renderScrollComponent',
+    displayName = `HeaderMotion(${getDisplayName(
+      ScrollableComponent as {
+        displayName?: string;
+        name?: string;
+      }
+    )})`,
+  } = options || {};
+
+  const AnimatedScrollable = (
+    isComponentAnimated
+      ? ScrollableComponent
+      : Animated.createAnimatedComponent(ScrollableComponent)
+  ) as ScrollableImplementationComponent;
+
+  function HeaderMotionScrollable(props: ScrollableRuntimeProps) {
+    const {
+      scrollId,
+      animatedRef,
+      headerOffsetStrategy,
+      ensureScrollableContentMinHeight = false,
+      contentContainerStyle,
+      refreshControl,
+      refreshing,
+      onRefresh,
+      progressViewOffset,
+      onScroll,
+      onScrollBeginDrag,
+      onScrollEndDrag,
+      onMomentumScrollBegin,
+      onMomentumScrollEnd,
+      ...rest
+    } = props;
+
+    const { scrollableProps, headerMotionContext } = useScrollManager(
+      scrollId,
+      {
+        refreshControl:
+          (refreshControl as UseScrollManagerOptions['refreshControl']) ??
+          undefined,
+        refreshing: refreshing ?? undefined,
+        onRefresh: onRefresh ?? undefined,
+        progressViewOffset,
+        onScroll,
+        onScrollBeginDrag,
+        onScrollEndDrag,
+        onMomentumScrollBegin,
+        onMomentumScrollEnd,
+        animatedRef,
+        ensureScrollableContentMinHeight,
+      }
+    );
+
+    const {
+      onScroll: managedOnScroll,
+      onLayout: managedOnLayout,
+      refreshControl: managedRefreshControl,
+      ref,
+      ...scrollViewProps
+    } = scrollableProps;
+    const { originalHeaderHeight, contentContainerMinHeight } =
+      headerMotionContext;
+
+    const userOnLayoutRef = useRef<UserOnLayout>(rest.onLayout as UserOnLayout);
+    useLayoutEffect(() => {
+      userOnLayoutRef.current = rest.onLayout as UserOnLayout;
+    });
+
+    const managedContentContainerStyle = useMemo(
+      () => [
+        ensureScrollableContentMinHeight &&
+        contentContainerMinHeight !== undefined
+          ? { minHeight: contentContainerMinHeight }
+          : undefined,
+        resolveHeaderOffsetStyle(originalHeaderHeight, headerOffsetStrategy),
+        contentContainerStyle,
+      ],
+      [
+        contentContainerStyle,
+        contentContainerMinHeight,
+        ensureScrollableContentMinHeight,
+        headerOffsetStrategy,
+        originalHeaderHeight,
+      ]
+    );
+
+    const refreshControlProps = managedRefreshControl && {
+      refreshControl: managedRefreshControl,
+    };
+
+    const handleLayout = useCallback(
+      (e: LayoutChangeEvent) => {
+        managedOnLayout?.(e);
+        userOnLayoutRef.current?.(e);
+      },
+      [managedOnLayout]
+    );
+
+    const contentContainerProps = useContentContainerProps({
+      children: rest.children,
+      mode: contentContainerMode,
+      style: managedContentContainerStyle,
+    });
+
+    return (
+      <AnimatedScrollable
+        {...scrollViewProps}
+        {...rest}
+        {...refreshControlProps}
+        {...contentContainerProps}
+        ref={ref}
+        onLayout={handleLayout}
+        onScroll={managedOnScroll}
+      />
+    );
+  }
+
+  const TypedHeaderMotionScrollable =
+    HeaderMotionScrollable as HeaderMotionScrollableComponent<
+      TScrollableComponent,
+      TIsComponentAnimated
+    >;
+
+  TypedHeaderMotionScrollable.displayName = displayName;
+  return TypedHeaderMotionScrollable;
+}
+
+function useContentContainerProps({
+  children: rawChildren,
+  mode,
+  style,
+}: {
+  children?: ReactNode;
+  mode: ContentContainerMode;
+  style?: any;
+}) {
+  const renderScrollComponent = useCallback(
+    (props: ScrollViewProps) => (
+      <AnimatedScrollContainer {...props} contentContainerStyle={style} />
+    ),
+    [style]
+  );
+
+  const children = <Animated.View style={style}>{rawChildren}</Animated.View>;
+
+  if (mode === 'children') {
+    return { children };
+  }
+
+  return {
+    renderScrollComponent,
+  };
+}
+
+const AnimatedScrollContainer = forwardRef<
+  ComponentRef<typeof Animated.ScrollView>,
+  ScrollViewProps
+>(({ children, contentContainerStyle, ...rest }, ref) => {
+  return (
+    <Animated.ScrollView {...rest} ref={ref}>
+      <Animated.View style={contentContainerStyle}>{children}</Animated.View>
+    </Animated.ScrollView>
+  );
+});
+
+function getDisplayName(ScrollableComponent: {
+  displayName?: string;
+  name?: string;
+}) {
+  return (
+    ScrollableComponent.displayName ?? ScrollableComponent.name ?? 'Scrollable'
+  );
+}
+
+type UserOnLayout = ScrollViewProps['onLayout'] | undefined;
+
+// TODO: From here below Codex did some absolute TypeScript magic but it seems to work
+// Having limited time, I can't spend more on adjusting this to make it less convoluted
+// But what matters is that it seems that for the user the types work very well
+
+type ContentContainerMode = 'children' | 'renderScrollComponent';
+
+type ScrollableComponent =
+  | ((props: any) => ReactElement | null)
+  | (new (...args: any[]) => any);
+
+declare const noListItemSymbol: unique symbol;
+type NoListItem = { readonly [noListItemSymbol]: true };
+
+type ScrollableComponentProps<TScrollableComponent> =
+  TScrollableComponent extends new (props: infer TProps, ...args: any[]) => any
+    ? TProps
+    : TScrollableComponent extends (props: infer TProps, ...args: any[]) => any
+    ? TProps
+    : never;
+
+type IsUnknown<TValue> = unknown extends TValue
+  ? [keyof TValue] extends [never]
+    ? true
+    : false
+  : false;
+
+type ReplaceUnknownDeep<TValue, TReplacement> = IsUnknown<TValue> extends true
+  ? TReplacement
+  : TValue extends (...args: infer TArgs) => infer TResult
+  ? (
+      ...args: {
+        [TIndex in keyof TArgs]: ReplaceUnknownDeep<
+          TArgs[TIndex],
+          TReplacement
+        >;
+      }
+    ) => TResult
+  : TValue extends readonly (infer TItem)[]
+  ? readonly ReplaceUnknownDeep<TItem, TReplacement>[]
+  : TValue extends object
+  ? {
+      [TKey in keyof TValue]: ReplaceUnknownDeep<TValue[TKey], TReplacement>;
+    }
+  : TValue;
+
+type MaybeAnimatedProps<
+  TProps extends object,
+  TIsComponentAnimated
+> = TIsComponentAnimated extends true ? TProps : AnimatedProps<TProps>;
+
+type ResolveListItemProps<TProps extends object, TListItem> = [
+  TListItem
+] extends [NoListItem]
+  ? TProps
+  : ReplaceUnknownDeep<TProps, TListItem>;
+
+type ExtractDataProp<TProps> = TProps extends { data?: infer TData }
+  ? TData
+  : TProps extends { data: infer TData }
+  ? TData
+  : never;
+
+type ExtractListItemFromData<TData> = TData extends
+  | ReadonlyArray<infer TItem>
+  | null
+  | undefined
+  ? TItem
+  : TData extends ArrayLike<infer TItem> | null | undefined
+  ? TItem
+  : never;
+
+type HasGenericDataProp<TProps> = IsUnknown<
+  ExtractListItemFromData<ExtractDataProp<TProps>>
+>;
+
+type ExtractRefTargetFromRef<TRef> = TRef extends Ref<infer TInstance>
+  ? TInstance
+  : TRef extends AnimatedRef<infer TInstance>
+  ? TInstance
+  : never;
+
+type ExtractRefTargetFromProps<TProps> = TProps extends { ref?: infer TRef }
+  ? ExtractRefTargetFromRef<TRef>
+  : TProps extends { ref: infer TRef }
+  ? ExtractRefTargetFromRef<TRef>
+  : never;
+
+type ResolveScrollableRefTarget<TScrollableComponent, TProps> = [
+  ExtractRefTargetFromProps<TProps>
+] extends [never]
+  ? TScrollableComponent extends new (...args: any[]) => infer TInstance
+    ? TInstance extends InstanceOrElement
+      ? TInstance
+      : any
+    : any
+  : ExtractRefTargetFromProps<TProps> extends InstanceOrElement
+  ? ExtractRefTargetFromProps<TProps>
+  : any;
+
+type HeaderMotionScrollableBaseProps<
+  TScrollableComponent extends ScrollableComponent,
+  TIsComponentAnimated extends boolean,
+  TListItem = NoListItem
+> = ResolveListItemProps<
+  MaybeAnimatedProps<
+    ScrollableComponentProps<TScrollableComponent>,
+    TIsComponentAnimated
+  >,
+  TListItem
+>;
+
+type HeaderMotionScrollablePublicProps<
+  TScrollableComponent extends ScrollableComponent,
+  TIsComponentAnimated extends boolean,
+  TListItem = NoListItem
+> = HeaderMotionScrollableBaseProps<
+  TScrollableComponent,
+  TIsComponentAnimated,
+  TListItem
+> &
+  HeaderMotionScrollableOwnProps<
+    ResolveScrollableRefTarget<
+      TScrollableComponent,
+      HeaderMotionScrollableBaseProps<
+        TScrollableComponent,
+        TIsComponentAnimated,
+        TListItem
+      >
+    >
+  >;
+
+type HeaderMotionGenericScrollableComponent<
+  TScrollableComponent extends ScrollableComponent,
+  TIsComponentAnimated extends boolean
+> = {
+  <TListItem = any>(
+    props: HeaderMotionScrollablePublicProps<
+      TScrollableComponent,
+      TIsComponentAnimated,
+      TListItem
+    >
+  ): ReactElement | null;
+  displayName?: string;
+};
+
+type HeaderMotionStaticScrollableComponent<
+  TScrollableComponent extends ScrollableComponent,
+  TIsComponentAnimated extends boolean
+> = {
+  (
+    props: HeaderMotionScrollablePublicProps<
+      TScrollableComponent,
+      TIsComponentAnimated
+    >
+  ): ReactElement | null;
+  displayName?: string;
+};
+
+type HeaderMotionScrollableComponent<
+  TScrollableComponent extends ScrollableComponent,
+  TIsComponentAnimated extends boolean
+> = HasGenericDataProp<
+  ScrollableComponentProps<TScrollableComponent>
+> extends true
+  ? HeaderMotionGenericScrollableComponent<
+      TScrollableComponent,
+      TIsComponentAnimated
+    >
+  : HeaderMotionStaticScrollableComponent<
+      TScrollableComponent,
+      TIsComponentAnimated
+    >;
+
+type ScrollableRuntimeProps = HeaderMotionScrollableOwnProps & {
+  children?: ReactNode;
+  contentContainerStyle?: ScrollViewProps['contentContainerStyle'];
+  onScroll?: ScrollViewProps['onScroll'];
+  onScrollBeginDrag?: ScrollViewProps['onScrollBeginDrag'];
+  onScrollEndDrag?: ScrollViewProps['onScrollEndDrag'];
+  onMomentumScrollBegin?: ScrollViewProps['onMomentumScrollBegin'];
+  onMomentumScrollEnd?: ScrollViewProps['onMomentumScrollEnd'];
+  refreshControl?: ReactElement | null;
+  refreshing?: UseScrollManagerOptions['refreshing'] | null;
+  onRefresh?: UseScrollManagerOptions['onRefresh'] | null;
+  progressViewOffset?: UseScrollManagerOptions['progressViewOffset'];
+  [key: string]: unknown;
+};
+
+type ScrollableImplementationComponent = (
+  props: ScrollableRuntimeProps
+) => ReactElement | null;

package/src/components/index.ts

@@ -1,6 +1,8 @@
+export * from './Bridge';
 export * from './FlatList';
 export * from './Header';
-export * from './HeaderBase';
+export * from './NavigationBridge';
 export * from './HeaderMotion';
 export * from './ScrollManager';
 export * from './ScrollView';
+export * from './createHeaderMotionScrollable';

package/src/context.ts

@@ -1,27 +1,14 @@
-import { createContext } from 'react';
-import { type SharedValue } from 'react-native-reanimated';
-import type {
-  AnimatedHeaderBaseMotionProps,
-  MeasureAnimatedHeaderAndSet,
-  Progress,
-  ScrollTo,
-  ScrollValues,
-} from './types';
+import { createContext, useContext } from 'react';
+import type { HeaderMotionBridgeValue } from './types';
 
-interface HeaderMotionContextType {
-  progress: Progress;
-  measureTotalHeight: MeasureAnimatedHeaderAndSet;
-  measureDynamic: MeasureAnimatedHeaderAndSet;
-  enableHeaderPan: boolean;
-  headerPanMomentumOffset: SharedValue<number | null>;
-  animatedHeaderBaseProps: AnimatedHeaderBaseMotionProps;
-  scrollValues: SharedValue<ScrollValues>;
-  activeScrollId: SharedValue<string> | undefined;
-  progressThreshold: SharedValue<number>;
-  originalHeaderHeight: SharedValue<number>;
+export const HeaderMotionContext =
+  createContext<HeaderMotionBridgeValue | null>(null);
 
-  scrollToRef: React.RefObject<ScrollTo | null>;
-}
+export function useHeaderMotionContextOrThrow(errorMessage: string) {
+  const ctxValue = useContext(HeaderMotionContext);
+  if (!ctxValue) {
+    throw new Error(errorMessage);
+  }
 
-export const HeaderMotionContext =
-  createContext<HeaderMotionContextType | null>(null);
+  return ctxValue;
+}

package/src/hooks/index.ts

@@ -1,3 +1,4 @@
 export * from './useActiveScrollId';
+export * from './useHeaderMotionBridge';
 export * from './useMotionProgress';
 export * from './useScrollManager';

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/useConsumerScrollHandlers.ts

@@ -0,0 +1,148 @@
+import { useCallback } from 'react';
+import {
+  useComposedEventHandler,
+  type AnimatedScrollViewProps,
+  type ScrollHandler,
+  type ScrollHandlerProcessed,
+} from 'react-native-reanimated';
+import { scheduleOnRN } from 'react-native-worklets';
+import type { ScrollHandlerContext } from '../types';
+
+type ConsumerScrollHandler = (event: unknown) => void;
+type AnimatedScrollViewOnScroll = AnimatedScrollViewProps['onScroll'];
+type ScrollEvent = Parameters<ScrollHandler<Record<string, unknown>>>[0];
+
+export type ConsumerScrollEventHandlers = Pick<
+  AnimatedScrollViewProps,
+  | 'onScroll'
+  | 'onScrollBeginDrag'
+  | 'onScrollEndDrag'
+  | 'onMomentumScrollBegin'
+  | 'onMomentumScrollEnd'
+>;
+
+export interface ConsumerScrollBridges {
+  onScroll?: (event: ScrollEvent) => void;
+  onBeginDrag?: (event: ScrollEvent) => void;
+  onEndDrag?: (event: ScrollEvent) => void;
+  onMomentumBegin?: (event: ScrollEvent) => void;
+  onMomentumEnd?: (event: ScrollEvent) => void;
+}
+
+export function useConsumerScrollHandlers({
+  onScroll,
+  onScrollBeginDrag,
+  onScrollEndDrag,
+  onMomentumScrollBegin,
+  onMomentumScrollEnd,
+}: ConsumerScrollEventHandlers): ConsumerScrollBridges {
+  const consumerOnScroll =
+    typeof onScroll === 'function'
+      ? (onScroll as ConsumerScrollHandler)
+      : undefined;
+  const consumerOnScrollBeginDrag =
+    typeof onScrollBeginDrag === 'function'
+      ? (onScrollBeginDrag as ConsumerScrollHandler)
+      : undefined;
+  const consumerOnScrollEndDrag =
+    typeof onScrollEndDrag === 'function'
+      ? (onScrollEndDrag as ConsumerScrollHandler)
+      : undefined;
+  const consumerOnMomentumScrollBegin =
+    typeof onMomentumScrollBegin === 'function'
+      ? (onMomentumScrollBegin as ConsumerScrollHandler)
+      : undefined;
+  const consumerOnMomentumScrollEnd =
+    typeof onMomentumScrollEnd === 'function'
+      ? (onMomentumScrollEnd as ConsumerScrollHandler)
+      : undefined;
+
+  const onScrollBridge = useCallback(
+    (event: ScrollEvent) => {
+      'worklet';
+      if (!consumerOnScroll) {
+        return;
+      }
+      scheduleOnRN(consumerOnScroll, { nativeEvent: event } as unknown);
+    },
+    [consumerOnScroll]
+  );
+
+  const onBeginDragBridge = useCallback(
+    (event: ScrollEvent) => {
+      'worklet';
+      if (!consumerOnScrollBeginDrag) {
+        return;
+      }
+      scheduleOnRN(consumerOnScrollBeginDrag, {
+        nativeEvent: event,
+      } as unknown);
+    },
+    [consumerOnScrollBeginDrag]
+  );
+
+  const onEndDragBridge = useCallback(
+    (event: ScrollEvent) => {
+      'worklet';
+      if (!consumerOnScrollEndDrag) {
+        return;
+      }
+      scheduleOnRN(consumerOnScrollEndDrag, { nativeEvent: event } as unknown);
+    },
+    [consumerOnScrollEndDrag]
+  );
+
+  const onMomentumBeginBridge = useCallback(
+    (event: ScrollEvent) => {
+      'worklet';
+      if (!consumerOnMomentumScrollBegin) {
+        return;
+      }
+      scheduleOnRN(consumerOnMomentumScrollBegin, {
+        nativeEvent: event,
+      } as unknown);
+    },
+    [consumerOnMomentumScrollBegin]
+  );
+
+  const onMomentumEndBridge = useCallback(
+    (event: ScrollEvent) => {
+      'worklet';
+      if (!consumerOnMomentumScrollEnd) {
+        return;
+      }
+      scheduleOnRN(consumerOnMomentumScrollEnd, {
+        nativeEvent: event,
+      } as unknown);
+    },
+    [consumerOnMomentumScrollEnd]
+  );
+
+  return {
+    onScroll: onScrollBridge,
+    onBeginDrag: onBeginDragBridge,
+    onEndDrag: onEndDragBridge,
+    onMomentumBegin: onMomentumBeginBridge,
+    onMomentumEnd: onMomentumEndBridge,
+  };
+}
+
+export function useScrollHandlerComposition(
+  ownScrollHandler: ScrollHandlerProcessed<ScrollHandlerContext>,
+  consumerScrollHandler: AnimatedScrollViewOnScroll | undefined
+) {
+  // TODO: I guess the typing here could be more precise
+  const consumerWorkletHandler = isAnimatedScrollHandler(consumerScrollHandler)
+    ? (consumerScrollHandler as ScrollHandlerProcessed<ScrollHandlerContext>)
+    : null;
+
+  return useComposedEventHandler([ownScrollHandler, consumerWorkletHandler]);
+}
+
+function isAnimatedScrollHandler(
+  handler: AnimatedScrollViewOnScroll | undefined
+): handler is AnimatedScrollViewOnScroll {
+  // FUTURE: we could be checking just by typeof handler === 'object'?
+  // This seems safer for now, unless Reanimated changes this shape. Revisit
+  return !!handler && 'workletEventHandler' in handler;
+}

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