react-native-screen-transitions 2.4.0 → 2.4.2-beta.0

package/src/integrations/blank-stack/components/StackView.tsx

@@ -0,0 +1,106 @@
+import { SafeAreaProviderCompat } from "@react-navigation/elements";
+import {
+  NavigationContext,
+  NavigationRouteContext,
+} from "@react-navigation/native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { ScreenContainer } from "react-native-screens";
+import { RootTransitionAware } from "../../../components/root-transition-aware";
+import { ScreenTransitionProvider } from "../../../providers/screen-transition-provider";
+import type { BlankStackDescriptor } from "../../../types/blank-stack.navigator";
+import { withStackNavigationProvider } from "../utils/with-stack-navigation";
+import { Header } from "./Header";
+import { Screen } from "./Screens";
+
+function isFabric() {
+  return "nativeFabricUIManager" in global;
+}
+
+type SceneViewProps = {
+  descriptor: BlankStackDescriptor;
+  isFocused: boolean;
+  sceneIndex: number;
+};
+
+const SceneView = ({ descriptor }: SceneViewProps) => {
+  const { route, navigation, render } = descriptor;
+
+  return (
+    <NavigationContext.Provider value={navigation}>
+      <NavigationRouteContext.Provider value={route}>
+        <RootTransitionAware>
+          {descriptor.options.headerMode === "screen" && <Header.Screen />}
+          {render()}
+        </RootTransitionAware>
+      </NavigationRouteContext.Provider>
+    </NavigationContext.Provider>
+  );
+};
+
+export const StackView = withStackNavigationProvider(
+  ({
+    activeScreensLimit,
+    descriptors,
+    FloatHeader,
+    focusedIndex,
+    routes,
+    scenes,
+  }) => {
+    return (
+      <GestureHandlerRootView>
+        <SafeAreaProviderCompat>
+          <FloatHeader />
+          <ScreenContainer style={{ flex: 1 }}>
+            {scenes.map((scene, sceneIndex) => {
+              const descriptor = scene.descriptor;
+              const route = scene.route;
+              const isFocused = focusedIndex === sceneIndex;
+              const isBelowFocused = focusedIndex - 1 === sceneIndex;
+
+              const previousDescriptor =
+                scenes[sceneIndex - 1]?.descriptor ?? undefined;
+              const nextDescriptor =
+                scenes[sceneIndex + 1]?.descriptor ?? undefined;
+
+              const isPreloaded = descriptors[route.key] === undefined;
+
+              // On Fabric, when screen is frozen, animated and reanimated values are not updated
+              // due to component being unmounted. To avoid this, we don't freeze the previous screen there
+              const shouldFreeze = isFabric()
+                ? !isPreloaded && !isFocused && !isBelowFocused
+                : !isPreloaded && !isFocused;
+              return (
+                <Screen
+                  key={route.key}
+                  isPreloaded={isPreloaded}
+                  index={sceneIndex}
+                  activeScreensLimit={activeScreensLimit}
+                  routeKey={route.key}
+                  routes={routes}
+                  shouldFreeze={shouldFreeze}
+                  freezeOnBlur={descriptor.options.freezeOnBlur}
+                >
+                  <ScreenTransitionProvider
+                    // @ts-expect-error
+                    previous={previousDescriptor}
+                    // @ts-expect-error
+                    current={descriptor}
+                    // @ts-expect-error
+                    next={nextDescriptor}
+                  >
+                    <SceneView
+                      key={route.key}
+                      isFocused={isFocused}
+                      sceneIndex={sceneIndex}
+                      descriptor={descriptor}
+                    />
+                  </ScreenTransitionProvider>
+                </Screen>
+              );
+            })}
+          </ScreenContainer>
+        </SafeAreaProviderCompat>
+      </GestureHandlerRootView>
+    );
+  }
+);

package/src/integrations/blank-stack/navigators/createBlankStackNavigator.tsx

@@ -0,0 +1,122 @@
+import {
+  createNavigatorFactory,
+  type EventArg,
+  type NavigatorTypeBagBase,
+  type ParamListBase,
+  type StackActionHelpers,
+  StackActions,
+  type StackNavigationState,
+  StackRouter,
+  type StackRouterOptions,
+  type StaticConfig,
+  type TypedNavigator,
+  useNavigationBuilder,
+} from "@react-navigation/native";
+import * as React from "react";
+import { StackView } from "../components/StackView";
+import type {
+  BlankStackNavigationEventMap,
+  BlankStackNavigationOptions,
+  BlankStackNavigationProp,
+  BlankStackNavigatorProps,
+} from "../../../types/blank-stack.navigator";
+
+function BlankStackNavigator({
+  id,
+  initialRouteName,
+  children,
+  layout,
+  screenListeners,
+  screenOptions,
+  screenLayout,
+  ...rest
+}: BlankStackNavigatorProps) {
+  const { state, describe, descriptors, navigation, NavigationContent } =
+    useNavigationBuilder<
+      StackNavigationState<ParamListBase>,
+      StackRouterOptions,
+      StackActionHelpers<ParamListBase>,
+      BlankStackNavigationOptions,
+      BlankStackNavigationEventMap
+    >(StackRouter, {
+      id,
+      initialRouteName,
+      children,
+      layout,
+      screenListeners,
+      screenOptions,
+      screenLayout,
+    });
+
+  React.useEffect(
+    () =>
+      // @ts-expect-error: there may not be a tab navigator in parent
+      navigation?.addListener?.("tabPress", (e: any) => {
+        const isFocused = navigation.isFocused();
+
+        // Run the operation in the next frame so we're sure all listeners have been run
+        // This is necessary to know if preventDefault() has been called
+        requestAnimationFrame(() => {
+          if (
+            state.index > 0 &&
+            isFocused &&
+            !(e as EventArg<"tabPress", true>).defaultPrevented
+          ) {
+            // When user taps on already focused tab and we're inside the tab,
+            // reset the stack to replicate native behaviour
+            navigation.dispatch({
+              ...StackActions.popToTop(),
+              target: state.key,
+            });
+          }
+        });
+      }),
+    [navigation, state.index, state.key]
+  );
+
+  return (
+    <NavigationContent>
+      <StackView
+        {...rest}
+        state={state}
+        navigation={navigation}
+        descriptors={descriptors}
+        describe={describe}
+      />
+    </NavigationContent>
+  );
+}
+
+export function createBlankStackNavigator<
+  const ParamList extends ParamListBase,
+  const NavigatorID extends string | undefined = undefined,
+  const TypeBag extends NavigatorTypeBagBase = {
+    ParamList: ParamList;
+    NavigatorID: NavigatorID;
+    State: StackNavigationState<ParamList>;
+    ScreenOptions: BlankStackNavigationOptions;
+    EventMap: BlankStackNavigationEventMap;
+    NavigationList: {
+      [RouteName in keyof ParamList]: BlankStackNavigationProp<
+        ParamList,
+        RouteName,
+        NavigatorID
+      >;
+    };
+    Navigator: typeof BlankStackNavigator;
+  },
+  const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>
+>(config?: Config): TypedNavigator<TypeBag, Config> {
+  return createNavigatorFactory(BlankStackNavigator)(config);
+}
+
+import { withLayoutContext } from "expo-router";
+
+const { Navigator } = createBlankStackNavigator();
+
+export const BlankStack = withLayoutContext<
+  BlankStackNavigationOptions,
+  typeof Navigator,
+  StackNavigationState<ParamListBase>,
+  BlankStackNavigationEventMap
+>(Navigator);

package/src/integrations/blank-stack/utils/with-stack-navigation/_hooks/use-closing-route-keys.tsx

@@ -0,0 +1,62 @@
+import { useRef } from "react";
+import { useSharedValue } from "react-native-reanimated";
+import useStableCallback from "../../../../../hooks/use-stable-callback";
+
+export const useClosingRouteKeys = () => {
+  const keysRef = useRef<Set<string>>(new Set());
+  const shared = useSharedValue<string[]>([]);
+
+  const add = useStableCallback((key: string) => {
+    const keys = keysRef.current;
+    if (keys.has(key)) {
+      return;
+    }
+
+    keys.add(key);
+    shared.modify((prev) => {
+      "worklet";
+      if (!prev.includes(key)) {
+        prev.push(key);
+      }
+      return prev;
+    });
+  });
+
+  const remove = useStableCallback((key: string) => {
+    const keys = keysRef.current;
+    if (!keys.delete(key)) {
+      return;
+    }
+
+    shared.modify((prev) => {
+      "worklet";
+      const index = prev.indexOf(key);
+      if (index !== -1) {
+        prev.splice(index, 1);
+      }
+      return prev;
+    });
+  });
+
+  const clear = useStableCallback(() => {
+    const keys = keysRef.current;
+    if (!keys.size) {
+      return;
+    }
+
+    keys.clear();
+    shared.modify((prev) => {
+      "worklet";
+      prev.length = 0;
+      return prev;
+    });
+  });
+
+  return {
+    ref: keysRef,
+    shared,
+    add,
+    remove,
+    clear,
+  };
+};

package/src/integrations/blank-stack/utils/with-stack-navigation/_hooks/use-previous.tsx

@@ -0,0 +1,11 @@
+import { useEffect, useRef } from "react";
+
+export const usePrevious = <T,>(value: T): T | null => {
+	const ref = useRef<T>(null);
+
+	useEffect(() => {
+		ref.current = value;
+	});
+
+	return ref.current;
+};

package/src/integrations/blank-stack/utils/with-stack-navigation/_hooks/use-stack-navigation-state.tsx

@@ -0,0 +1,280 @@
+import { type Route, StackActions } from "@react-navigation/native";
+import { useLayoutEffect, useState } from "react";
+import useStableCallback from "../../../../../hooks/use-stable-callback";
+import type { BlankStackDescriptorMap } from "../../../../../types/blank-stack.navigator";
+import type { StackNavigationContextProps } from "../_types";
+import { areDescriptorsEqual } from "../_utils/are-descriptors-equal";
+import { composeDescriptors } from "../_utils/compose-descriptors";
+import { haveSameRouteKeys } from "../_utils/have-same-route-keys";
+import { routesAreIdentical } from "../_utils/routes-are-identical";
+import { useClosingRouteKeys } from "./use-closing-route-keys";
+import { usePrevious } from "./use-previous";
+
+type SyncRoutesWithRemovedParams = {
+  prevRoutes: Route<string>[];
+  prevDescriptors: BlankStackDescriptorMap;
+  nextRoutes: Route<string>[];
+  nextDescriptors: BlankStackDescriptorMap;
+  closingRouteKeys: ReturnType<typeof useClosingRouteKeys>;
+};
+
+/**
+ * Aligns current routes with the latest route data while preserving references
+ * when possible for performance optimization
+ */
+const alignRoutesWithLatest = (
+  currentRoutes: Route<string>[],
+  currentDescriptors: BlankStackDescriptorMap,
+  nextRoutes: Route<string>[],
+  nextDescriptors: BlankStackDescriptorMap
+) => {
+  // Early return for empty current routes
+  if (currentRoutes.length === 0) {
+    return {
+      routes: nextRoutes,
+      descriptors: composeDescriptors(
+        nextRoutes,
+        nextDescriptors,
+        currentDescriptors
+      ),
+    };
+  }
+
+  // Create lookup map for efficient route finding
+  const nextRouteLookup = new Map<string, Route<string>>();
+  for (const route of nextRoutes) {
+    nextRouteLookup.set(route.key, route);
+  }
+
+  // Track if any changes occurred
+  let didChange = currentRoutes.length !== nextRoutes.length;
+
+  // Align routes, updating references where needed
+  const alignedRoutes = currentRoutes.map((route) => {
+    const nextRoute = nextRouteLookup.get(route.key);
+
+    if (!nextRoute) {
+      return route; // Keep current route if not in next
+    }
+
+    if (nextRoute !== route) {
+      didChange = true;
+      return nextRoute; // Update to new route reference
+    }
+
+    return route; // Keep current route reference
+  });
+
+  // Only create new array if changes occurred
+  const routesResult = didChange ? alignedRoutes : currentRoutes;
+
+  return {
+    routes: routesResult,
+    descriptors: composeDescriptors(
+      routesResult,
+      nextDescriptors,
+      currentDescriptors
+    ),
+  };
+};
+
+/**
+ * Synchronizes routes while handling removed routes that may still be animating out.
+ * This manages the complex logic of keeping closing routes visible during transitions.
+ */
+const syncRoutesWithRemoved = ({
+  prevRoutes,
+  prevDescriptors,
+  nextRoutes,
+  nextDescriptors,
+  closingRouteKeys,
+}: SyncRoutesWithRemovedParams) => {
+  if (nextRoutes.length === 0) {
+    closingRouteKeys.clear();
+    return {
+      routes: nextRoutes,
+      descriptors: {},
+    };
+  }
+
+  // Start with next routes, will mutate if needed
+  let derivedRoutes: Route<string>[] = nextRoutes;
+  let mutated = false;
+
+  // Helper to ensure we're working with a mutable copy
+  const ensureMutable = () => {
+    if (!mutated) {
+      derivedRoutes = derivedRoutes.slice();
+      mutated = true;
+    }
+  };
+
+  // Get focused (last) routes for comparison
+  const previousFocusedRoute = prevRoutes[prevRoutes.length - 1];
+  const nextFocusedRoute = nextRoutes[nextRoutes.length - 1];
+
+  // Handle focus changes between routes
+  if (
+    previousFocusedRoute &&
+    nextFocusedRoute &&
+    previousFocusedRoute.key !== nextFocusedRoute.key
+  ) {
+    const nextRouteWasPresent = prevRoutes.some(
+      (route) => route.key === nextFocusedRoute.key
+    );
+    const previousRouteStillPresent = nextRoutes.some(
+      (route) => route.key === previousFocusedRoute.key
+    );
+
+    if (nextRouteWasPresent && !previousRouteStillPresent) {
+      // Previous route was removed, mark as closing
+      closingRouteKeys.add(previousFocusedRoute.key);
+
+      ensureMutable();
+      derivedRoutes.push(previousFocusedRoute);
+    } else {
+      // Next route is now active, not closing
+      closingRouteKeys.remove(nextFocusedRoute.key);
+
+      if (!previousRouteStillPresent) {
+        // Previous route needs to be inserted for transition
+        closingRouteKeys.remove(previousFocusedRoute.key);
+
+        ensureMutable();
+        const insertIndex = Math.max(derivedRoutes.length - 1, 0);
+        derivedRoutes.splice(insertIndex, 0, previousFocusedRoute);
+      }
+    }
+  } else if (nextFocusedRoute) {
+    // Same focused route, ensure it's not marked as closing
+    closingRouteKeys.remove(nextFocusedRoute.key);
+  }
+
+  // Clean up closing keys that are no longer in the route list
+  const activeKeys = new Set(derivedRoutes.map((route) => route.key));
+  for (const key of Array.from(closingRouteKeys.ref.current)) {
+    if (!activeKeys.has(key)) {
+      closingRouteKeys.remove(key);
+    }
+  }
+
+  const routesResult = mutated ? derivedRoutes : nextRoutes;
+
+  return {
+    routes: routesResult,
+    descriptors: composeDescriptors(
+      routesResult,
+      nextDescriptors,
+      prevDescriptors
+    ),
+  };
+};
+
+export const useStackNavigationState = (props: StackNavigationContextProps) => {
+  const previousRoutes = usePrevious(props.state.routes) ?? [];
+  const closingRouteKeys = useClosingRouteKeys();
+
+  const [localState, setLocalState] = useState(() => ({
+    routes: props.state.routes,
+    descriptors: props.descriptors,
+  }));
+
+  useLayoutEffect(() => {
+    const nextRoutesSnapshot = props.state.routes;
+    const previousRoutesSnapshot = previousRoutes;
+
+    setLocalState((current) => {
+      const routeKeysUnchanged = haveSameRouteKeys(
+        previousRoutesSnapshot,
+        nextRoutesSnapshot
+      );
+
+      let derivedRoutes: Route<string>[];
+      let derivedDescriptors: BlankStackDescriptorMap;
+
+      if (routeKeysUnchanged) {
+        const result = alignRoutesWithLatest(
+          current.routes,
+          current.descriptors,
+          nextRoutesSnapshot,
+          props.descriptors
+        );
+
+        derivedRoutes = result.routes;
+        derivedDescriptors = result.descriptors;
+      } else {
+        const fallbackRoutes =
+          previousRoutesSnapshot.length > 0
+            ? previousRoutesSnapshot
+            : current.routes;
+
+        const result = syncRoutesWithRemoved({
+          prevRoutes: fallbackRoutes,
+          prevDescriptors: current.descriptors,
+          nextRoutes: nextRoutesSnapshot,
+          nextDescriptors: props.descriptors,
+          closingRouteKeys,
+        });
+
+        derivedRoutes = result.routes;
+        derivedDescriptors = result.descriptors;
+      }
+
+      const routesChanged = !routesAreIdentical(current.routes, derivedRoutes);
+      const descriptorsChanged = !areDescriptorsEqual(
+        current.descriptors,
+        derivedDescriptors
+      );
+
+      if (!routesChanged && !descriptorsChanged) {
+        return current;
+      }
+
+      return {
+        routes: routesChanged ? derivedRoutes : current.routes,
+        descriptors: descriptorsChanged
+          ? derivedDescriptors
+          : current.descriptors,
+      };
+    });
+  }, [props.state.routes, props.descriptors, previousRoutes, closingRouteKeys]);
+
+  const handleCloseRoute = useStableCallback(
+    ({ route }: { route: Route<string> }) => {
+      if (props.state.routes.some((r) => r.key === route.key)) {
+        props.navigation.dispatch({
+          ...StackActions.pop(),
+          source: route.key,
+          target: props.state.key,
+        });
+        return;
+      }
+
+      closingRouteKeys.remove(route.key);
+
+      setLocalState((current) => {
+        if (!current.routes.some((candidate) => candidate.key === route.key)) {
+          return current;
+        }
+
+        const nextRoutes = current.routes.filter(
+          (candidate) => candidate.key !== route.key
+        );
+
+        const nextDescriptors = { ...current.descriptors };
+        delete nextDescriptors[route.key];
+
+        return {
+          routes: nextRoutes,
+          descriptors: nextDescriptors,
+        };
+      });
+    }
+  );
+
+  return {
+    state: localState,
+    handleCloseRoute,
+    closingRouteKeys,
+  };
+};

package/src/integrations/blank-stack/utils/with-stack-navigation/_types.ts

@@ -0,0 +1,36 @@
+import type {
+  NavigationRoute,
+  ParamListBase,
+  Route,
+  RouteProp,
+  StackNavigationState,
+} from "@react-navigation/native";
+import type React from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type {
+  BlankStackDescriptor,
+  BlankStackDescriptorMap,
+  BlankStackNavigationHelpers,
+  BlankStackScene,
+} from "../../../../types/blank-stack.navigator";
+
+export interface StackNavigationContextValue {
+  routes: NavigationRoute<ParamListBase, string>[];
+  descriptors: BlankStackDescriptorMap;
+  scenes: BlankStackScene[];
+  activeScreensLimit: number;
+  closingRouteKeysShared: SharedValue<string[]>;
+  handleCloseRoute: (payload: { route: Route<string> }) => void;
+  FloatHeader: React.MemoExoticComponent<() => React.JSX.Element | null>;
+  focusedIndex: number;
+}
+
+export interface StackNavigationContextProps {
+  state: StackNavigationState<ParamListBase>;
+  navigation: BlankStackNavigationHelpers;
+  descriptors: BlankStackDescriptorMap;
+  describe: (
+    route: RouteProp<ParamListBase>,
+    placeholder: boolean
+  ) => BlankStackDescriptor;
+}

package/src/integrations/blank-stack/utils/with-stack-navigation/_utils/are-descriptors-equal.ts

@@ -0,0 +1,15 @@
+import type { BlankStackDescriptorMap } from "../../../../../types/blank-stack.navigator";
+
+export const areDescriptorsEqual = (
+  a: BlankStackDescriptorMap,
+  b: BlankStackDescriptorMap
+): boolean => {
+  if (a === b) return true;
+
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+
+  if (aKeys.length !== bKeys.length) return false;
+
+  return aKeys.every((key) => a[key] === b[key]);
+};

package/src/integrations/blank-stack/utils/with-stack-navigation/_utils/calculateActiveScreensLimit.ts

@@ -0,0 +1,29 @@
+import type { NavigationRoute, ParamListBase } from "@react-navigation/native";
+import type { BlankStackDescriptorMap } from "../../../../../types/blank-stack.navigator";
+
+export function calculateActiveScreensLimit(
+  routes: NavigationRoute<ParamListBase, string>[],
+  descriptors: BlankStackDescriptorMap
+): number {
+  if (routes.length === 0) {
+    return 1;
+  }
+
+  let limit = 1;
+
+  for (let i = routes.length - 1; i >= 0; i--) {
+    const route = routes[i];
+
+    const shouldKeepPrevious =
+      descriptors?.[route.key]?.options?.detachPreviousScreen !== true;
+
+    if (shouldKeepPrevious) {
+      limit++;
+      continue;
+    }
+
+    break;
+  }
+
+  return Math.min(limit, routes.length);
+}

package/src/integrations/blank-stack/utils/with-stack-navigation/_utils/compose-descriptors.ts

@@ -0,0 +1,17 @@
+import type { Route } from "@react-navigation/native";
+import type { BlankStackDescriptorMap } from "../../../../../types/blank-stack.navigator";
+
+export const composeDescriptors = (
+  routes: Route<string>[],
+  nextDescriptors: BlankStackDescriptorMap,
+  currentDescriptors: BlankStackDescriptorMap
+): BlankStackDescriptorMap => {
+  const composed: BlankStackDescriptorMap = {};
+
+  for (const route of routes) {
+    composed[route.key] =
+      nextDescriptors[route.key] ?? currentDescriptors[route.key];
+  }
+
+  return composed;
+};

package/src/integrations/blank-stack/utils/with-stack-navigation/_utils/have-same-route-keys.ts

@@ -0,0 +1,12 @@
+import type { Route } from "@react-navigation/native";
+
+export const haveSameRouteKeys = (
+	previous: Route<string>[],
+	next: Route<string>[],
+): boolean => {
+	if (previous.length !== next.length) {
+		return false;
+	}
+
+	return previous.every((route, index) => route?.key === next[index]?.key);
+};