react-native-screen-transitions 3.0.0-rc.2 → 3.0.0-rc.4

package/src/shared/components/controllers/blank-stack-lifecycle.tsx

@@ -0,0 +1,70 @@
+import { useLayoutEffect } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import type { BlankStackDescriptor } from "../../../blank-stack/types";
+import { useStackNavigationContext } from "../../../blank-stack/utils/with-stack-navigation";
+import useStableCallback from "../../hooks/use-stable-callback";
+import { useKeys } from "../../providers/keys.provider";
+import { AnimationStore } from "../../stores/animation.store";
+import { startScreenTransition } from "../../utils/animation/start-screen-transition";
+import { resetStoresForScreen } from "../../utils/reset-stores-for-screen";
+
+export interface Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Lifecycle controller built out for Blank Stack implementation.
+ */
+export const BlankStackScreenLifecycleController = ({ children }: Props) => {
+	const { current } = useKeys<BlankStackDescriptor>();
+	const { handleCloseRoute, closingRouteKeysShared } =
+		useStackNavigationContext();
+
+	const animations = AnimationStore.getAll(current.route.key);
+
+	const handleInitialize = useStableCallback(() => {
+		startScreenTransition({
+			target: "open",
+			spec: current.options.transitionSpec,
+			animations,
+		});
+	});
+
+	const handleCleanup = useStableCallback(() => {
+		resetStoresForScreen(current);
+	});
+
+	const handleCloseEnd = useStableCallback((finished: boolean) => {
+		if (!finished) {
+			return;
+		}
+		handleCloseRoute({ route: current.route });
+	});
+
+	useAnimatedReaction(
+		() => ({
+			keys: closingRouteKeysShared.value,
+		}),
+		({ keys }) => {
+			if (!keys.includes(current.route.key)) {
+				return;
+			}
+
+			startScreenTransition({
+				target: "close",
+				spec: current.options.transitionSpec,
+				animations,
+				onAnimationFinish: handleCloseEnd,
+			});
+		},
+	);
+
+	useLayoutEffect(() => {
+		handleInitialize();
+		return () => {
+			handleCleanup();
+		};
+	}, [handleInitialize, handleCleanup]);
+
+	return children;
+};

package/src/shared/components/controllers/native-stack-lifecycle.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useLayoutEffect } from "react";
+import { useDerivedValue } from "react-native-reanimated";
+import type { NativeStackDescriptor } from "../../../native-stack/types";
+import { useSharedValueState } from "../../hooks/reanimated/use-shared-value-state";
+import useStableCallback from "../../hooks/use-stable-callback";
+import { useGestureContext } from "../../providers/gestures.provider";
+import { useKeys } from "../../providers/keys.provider";
+import { AnimationStore } from "../../stores/animation.store";
+import { TRUE } from "../../types/state.types";
+import { startScreenTransition } from "../../utils/animation/start-screen-transition";
+import { resetStoresForScreen } from "../../utils/reset-stores-for-screen";
+
+export interface Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Lifecycle controller built out for Native Stack implementation.
+ */
+export const NativeStackScreenLifecycleController = ({ children }: Props) => {
+	const { current } = useKeys<NativeStackDescriptor>();
+	const { ancestorContext } = useGestureContext();
+
+	const isAncestorDismissingViaGesture = useSharedValueState(
+		useDerivedValue(() => {
+			"worklet";
+			return (
+				ancestorContext?.gestureAnimationValues.isDismissing?.value ?? false
+			);
+		}),
+	);
+
+	const animations = AnimationStore.getAll(current.route.key);
+
+	const handleBeforeRemove = useStableCallback((e: any) => {
+		const isEnabled = current.options.enableTransitions;
+
+		const isFirstScreen = current.navigation.getState().index === 0;
+
+		// If transitions are disabled, or an ancestor is dismissing via gesture, or this is the first screen of the stack, reset the stores
+		if (!isEnabled || isAncestorDismissingViaGesture || isFirstScreen) {
+			animations.closing.set(TRUE);
+			resetStoresForScreen(current);
+			return;
+		}
+
+		e.preventDefault();
+		const onAnimationFinish = (finished: boolean) => {
+			if (finished) {
+				current.navigation.dispatch(e.data.action);
+
+				// we'll ensure the dispatch is complete before resetting stores
+				requestAnimationFrame(() => {
+					resetStoresForScreen(current);
+				});
+			}
+		};
+
+		startScreenTransition({
+			target: "close",
+			spec: current.options.transitionSpec,
+			onAnimationFinish,
+			animations,
+		});
+	});
+
+	const handleInitialize = useStableCallback(() => {
+		startScreenTransition({
+			target: "open",
+			spec: current.options.transitionSpec,
+			animations,
+		});
+	});
+
+	useEffect(() => {
+		const unsubscribe = current.navigation.addListener(
+			"beforeRemove",
+			handleBeforeRemove,
+		);
+
+		return unsubscribe;
+	}, [current.navigation, handleBeforeRemove]);
+
+	useLayoutEffect(handleInitialize, []);
+
+	return children;
+};

package/src/shared/hooks/animation/use-screen-animation.tsx

@@ -5,10 +5,12 @@ import { type SharedValue, useDerivedValue } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import type { NativeStackScreenTransitionConfig } from "../../../native-stack/types";
 import { DEFAULT_SCREEN_TRANSITION_STATE } from "../../constants";
+import { useFlagsContext } from "../../providers/flags.provider";
 import {
 	type TransitionDescriptor,
 	useKeys,
 } from "../../providers/keys.provider";
+import { useStackAnimationValues } from "../../providers/routes.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
 import type {
@@ -16,6 +18,7 @@ import type {
 	ScreenTransitionState,
 } from "../../types/animation.types";
 import type { ScreenTransitionConfig } from "../../types/core.types";
+import { computeStackProgress } from "../../utils/animation/compute-stack-progress";
 import { derivations } from "../../utils/animation/derivations";
 import { createBounds } from "../../utils/bounds";
 
@@ -25,30 +28,42 @@ type BuiltState = {
 	animating: SharedValue<number>;
 	gesture: GestureStoreMap;
 	route: RouteProp<ParamListBase>;
+	unwrapped: ScreenTransitionState;
 };
 
-const unwrap = (
-	s: BuiltState | undefined,
-	key: string | undefined,
-): ScreenTransitionState | undefined => {
+const createScreenTransitionState = (
+	route: RouteProp<ParamListBase>,
+): ScreenTransitionState => ({
+	progress: 0,
+	closing: 0,
+	animating: 0,
+	gesture: {
+		x: 0,
+		y: 0,
+		normalizedX: 0,
+		normalizedY: 0,
+		isDismissing: 0,
+		isDragging: 0,
+		direction: null,
+	},
+	route,
+});
+
+const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 	"worklet";
-	if (!s || !key) return undefined;
-
-	return {
-		progress: s.progress.value,
-		closing: s.closing.value,
-		animating: s.animating.value,
-		gesture: {
-			x: s.gesture.x.value,
-			y: s.gesture.y.value,
-			normalizedX: s.gesture.normalizedX.value,
-			normalizedY: s.gesture.normalizedY.value,
-			isDismissing: s.gesture.isDismissing.value,
-			isDragging: s.gesture.isDragging.value,
-			direction: s.gesture.direction.value,
-		},
-		route: s.route,
-	};
+	const out = s.unwrapped;
+	out.progress = s.progress.value;
+	out.closing = s.closing.value;
+	out.animating = s.animating.value;
+	out.gesture.x = s.gesture.x.value;
+	out.gesture.y = s.gesture.y.value;
+	out.gesture.normalizedX = s.gesture.normalizedX.value;
+	out.gesture.normalizedY = s.gesture.normalizedY.value;
+	out.gesture.isDismissing = s.gesture.isDismissing.value;
+	out.gesture.isDragging = s.gesture.isDragging.value;
+	out.gesture.direction = s.gesture.direction.value;
+
+	return out;
 };
 
 const useBuildScreenTransitionState = (
@@ -65,18 +80,25 @@ const useBuildScreenTransitionState = (
 			animating: AnimationStore.getAnimation(key, "animating"),
 			gesture: GestureStore.getRouteGestures(key),
 			route: descriptor.route,
+			unwrapped: createScreenTransitionState(descriptor.route),
 		};
 	}, [key, descriptor?.route]);
 };
 
-const hasTransitionsEnabled = (options?: ScreenTransitionConfig) => {
+const hasTransitionsEnabled = (
+	options: ScreenTransitionConfig | undefined,
+	alwaysOn: boolean,
+) => {
 	"worklet";
+	if (alwaysOn) return true;
 	return !!(options as NativeStackScreenTransitionConfig)?.enableTransitions;
 };
 
 export function _useScreenAnimation() {
 	const dimensions = useWindowDimensions();
 	const insets = useSafeAreaInsets();
+	const flags = useFlagsContext();
+	const transitionsAlwaysOn = flags?.TRANSITIONS_ALWAYS_ON ?? false;
 
 	const {
 		current: currentDescriptor,
@@ -88,32 +110,41 @@ export function _useScreenAnimation() {
 	const nextAnimation = useBuildScreenTransitionState(nextDescriptor);
 	const prevAnimation = useBuildScreenTransitionState(previousDescriptor);
 
+	const currentRouteKey = currentDescriptor?.route?.key;
+	const stackAnimationValues = useStackAnimationValues(currentRouteKey);
+
 	const screenInterpolatorProps = useDerivedValue<
 		Omit<ScreenInterpolationProps, "bounds">
 	>(() => {
 		"worklet";
 
-		const previous = unwrap(prevAnimation, previousDescriptor?.route.key);
+		const previous = prevAnimation ? unwrapInto(prevAnimation) : undefined;
 
-		const next = hasTransitionsEnabled(nextDescriptor?.options)
-			? unwrap(nextAnimation, nextDescriptor?.route.key)
-			: undefined;
+		const next =
+			nextAnimation &&
+			hasTransitionsEnabled(nextDescriptor?.options, transitionsAlwaysOn)
+				? unwrapInto(nextAnimation)
+				: undefined;
 
-		const current =
-			unwrap(currentAnimation, currentDescriptor?.route.key) ??
-			DEFAULT_SCREEN_TRANSITION_STATE;
+		const current = currentAnimation
+			? unwrapInto(currentAnimation)
+			: DEFAULT_SCREEN_TRANSITION_STATE;
 
-		const helpers = derivations({
+		const { progress, ...helpers } = derivations({
 			current,
 			next,
 		});
 
+		const stackProgress = computeStackProgress(stackAnimationValues, progress);
+
 		return {
 			layouts: { screen: dimensions },
 			insets,
 			previous,
 			current,
 			next,
+			progress,
+			stackProgress,
 			...helpers,
 		};
 	});

package/src/shared/hooks/gestures/use-build-gestures.tsx

@@ -26,7 +26,10 @@ import { useKeys } from "../../providers/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
 
-import { type GestureDirection, GestureOffsetState } from "../../types/gesture.types";
+import {
+	type GestureDirection,
+	GestureOffsetState,
+} from "../../types/gesture.types";
 import { startScreenTransition } from "../../utils/animation/start-screen-transition";
 import { applyOffsetRules } from "../../utils/gesture/check-gesture-activation";
 import { determineDismissal } from "../../utils/gesture/determine-dismissal";
@@ -37,12 +40,12 @@ import useStableCallbackValue from "../use-stable-callback-value";
 
 interface BuildGesturesHookProps {
 	scrollConfig: SharedValue<ScrollConfig | null>;
-	parentContext?: GestureContextType | null;
+	ancestorContext?: GestureContextType | null;
 }
 
 export const useBuildGestures = ({
 	scrollConfig,
-	parentContext,
+	ancestorContext,
 }: BuildGesturesHookProps): {
 	panGesture: GestureType;
 	nativeGesture: GestureType;
@@ -93,8 +96,8 @@ export const useBuildGestures = ({
 
 	const handleDismiss = useCallback(() => {
 		// If an ancestor navigator is already dismissing, skip this dismiss to
-		// avoid racing with the parent
-		if (parentContext?.gestureAnimationValues.isDismissing?.value) {
+		// avoid racing with the ancestor
+		if (ancestorContext?.gestureAnimationValues.isDismissing?.value) {
 			return;
 		}
 
@@ -113,7 +116,7 @@ export const useBuildGestures = ({
 			source: current.route.key,
 			target: state.key,
 		});
-	}, [current, parentContext]);
+	}, [current, ancestorContext]);
 
 	const onTouchesDown = useStableCallbackValue((e: GestureTouchEvent) => {
 		"worklet";
@@ -127,7 +130,7 @@ export const useBuildGestures = ({
 			"worklet";
 
 			// If an ancestor navigator is already dismissing via gesture, block new gestures here.
-			if (parentContext?.gestureAnimationValues.isDismissing?.value) {
+			if (ancestorContext?.gestureAnimationValues.isDismissing?.value) {
 				gestureOffsetState.value = GestureOffsetState.FAILED;
 				manager.fail();
 				return;
@@ -335,6 +338,11 @@ export const useBuildGestures = ({
 			.onEnd(onEnd)
 			.blocksExternalGesture(nativeGesture);
 
+		// Allow ancestors to block child native gestures
+		if (ancestorContext?.panGesture && nativeGesture) {
+			ancestorContext.panGesture.blocksExternalGesture(nativeGesture);
+		}
+
 		return {
 			panGesture,
 			nativeGesture,
@@ -348,5 +356,6 @@ export const useBuildGestures = ({
 		onUpdate,
 		onEnd,
 		gestureAnimationValues,
+		ancestorContext,
 	]);
 };

package/src/shared/hooks/gestures/use-scroll-registry.tsx

@@ -12,7 +12,7 @@ interface ScrollProgressHookProps {
 }
 
 export const useScrollRegistry = (props: ScrollProgressHookProps) => {
-	const { scrollConfig, parentContext } = useGestureContext();
+	const { scrollConfig, ancestorContext } = useGestureContext();
 
 	const scrollHandler = useAnimatedScrollHandler({
 		onScroll: (event) => {
@@ -35,8 +35,8 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 				return v;
 			});
 
-			if (parentContext?.scrollConfig) {
-				parentContext.scrollConfig.modify((v: Any) => {
+			if (ancestorContext?.scrollConfig) {
+				ancestorContext.scrollConfig.modify((v: Any) => {
 					"worklet";
 					if (v === null) {
 						return {
@@ -76,8 +76,8 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 				v.contentHeight = height;
 				return v;
 			});
-			if (parentContext?.scrollConfig) {
-				parentContext.scrollConfig.modify((v: Any) => {
+			if (ancestorContext?.scrollConfig) {
+				ancestorContext.scrollConfig.modify((v: Any) => {
 					"worklet";
 					if (v === null) {
 						return {
@@ -117,8 +117,8 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 			v.layoutWidth = width;
 			return v;
 		});
-		if (parentContext?.scrollConfig) {
-			parentContext.scrollConfig.modify((v: Any) => {
+		if (ancestorContext?.scrollConfig) {
+			ancestorContext.scrollConfig.modify((v: Any) => {
 				"worklet";
 				if (v === null) {
 					return {

package/src/shared/providers/flags.provider.tsx

@@ -0,0 +1,21 @@
+import createProvider from "../utils/create-provider";
+
+interface FlagsValue {
+	TRANSITIONS_ALWAYS_ON: boolean;
+}
+
+interface FlagsProviderProps {
+	TRANSITIONS_ALWAYS_ON?: boolean;
+	children: React.ReactNode;
+}
+
+const { FlagsProvider, useFlagsContext } = createProvider("Flags", {
+	guarded: false,
+})<FlagsProviderProps, FlagsValue>(
+	({ TRANSITIONS_ALWAYS_ON = false, children }) => ({
+		value: { TRANSITIONS_ALWAYS_ON },
+		children,
+	}),
+);
+
+export { FlagsProvider, useFlagsContext };

package/src/shared/providers/gestures.provider.tsx

@@ -6,6 +6,7 @@ import type { SharedValue } from "react-native-reanimated";
 import { useSharedValue } from "react-native-reanimated";
 import { useBuildGestures } from "../hooks/gestures/use-build-gestures";
 import type { GestureStoreMap } from "../stores/gesture.store";
+import { useKeys } from "./keys.provider";
 
 export type ScrollConfig = {
 	x: number;
@@ -21,7 +22,7 @@ export interface GestureContextType {
 	nativeGesture: GestureType;
 	scrollConfig: SharedValue<ScrollConfig | null>;
 	gestureAnimationValues: GestureStoreMap;
-	parentContext: GestureContextType | null;
+	ancestorContext: GestureContextType | undefined;
 }
 
 type GestureProviderProps = {
@@ -30,15 +31,43 @@ type GestureProviderProps = {
 
 const GestureContext = createContext<GestureContextType | undefined>(undefined);
 
+/**
+ * Provider that creates gesture handling for a screen.
+ * If the current screen doesn't have gestures enabled but a parent does,
+ * we pass through the parent's context so scrollable children can coordinate
+ * with the ancestor's gestures.
+ */
 export const ScreenGestureProvider = ({ children }: GestureProviderProps) => {
-	const parentContext = useContext(GestureContext);
+	const ancestorContext = useContext(GestureContext);
+	const { current } = useKeys();
 
+	const hasOwnGestures = current.options.gestureEnabled === true;
+
+	// If this screen doesn't have its own gestures but an ancestor does,
+	// pass through so scrollable children coordinate with that ancestor
+	if (!hasOwnGestures && ancestorContext) {
+		return children;
+	}
+
+	return (
+		<ScreenGestureProviderInner ancestorContext={ancestorContext}>
+			{children}
+		</ScreenGestureProviderInner>
+	);
+};
+
+const ScreenGestureProviderInner = ({
+	children,
+	ancestorContext,
+}: GestureProviderProps & {
+	ancestorContext: GestureContextType | undefined;
+}) => {
 	const scrollConfig = useSharedValue<ScrollConfig | null>(null);
 
 	const { panGesture, nativeGesture, gestureAnimationValues } =
 		useBuildGestures({
 			scrollConfig,
-			parentContext,
+			ancestorContext,
 		});
 
 	const value: GestureContextType = useMemo(
@@ -47,14 +76,14 @@ export const ScreenGestureProvider = ({ children }: GestureProviderProps) => {
 			scrollConfig,
 			nativeGesture,
 			gestureAnimationValues,
-			parentContext: parentContext || null,
+			ancestorContext,
 		}),
 		[
 			panGesture,
 			scrollConfig,
 			nativeGesture,
 			gestureAnimationValues,
-			parentContext,
+			ancestorContext,
 		],
 	);