@react-navigation/core 8.0.0-alpha.3 → 8.0.0-alpha.31

package/src/useNavigationCache.tsx

@@ -23,8 +23,8 @@ type Options<
     Partial<NavigationProp<ParamListBase, string, any, any, any>>;
   setOptions: (
     cb: (
-      options: Record<string, ScreenOptions>
-    ) => Record<string, ScreenOptions>
+      options: Record<string, Partial<ScreenOptions> | undefined>
+    ) => Record<string, Partial<ScreenOptions> | undefined>
   ) => void;
   router: Router<State, NavigationAction>;
   emitter: NavigationEventEmitter<EventMap>;
@@ -72,8 +72,8 @@ export function useNavigationCache<
   router,
   emitter,
 }: Options<State, ScreenOptions, EventMap>) {
-  const parentNavigationHelpers = React.useContext(NavigationContext);
-  const { stackRef } = React.useContext(NavigationBuilderContext);
+  const parentNavigationHelpers = React.use(NavigationContext);
+  const { stackRef } = React.use(NavigationBuilderContext);
 
   // Cache object which holds navigation objects for each screen
   // We use `React.useMemo` instead of `React.useRef` coz we want to invalidate it when deps change
@@ -91,27 +91,15 @@ export function useNavigationCache<
     [getState, parentNavigationHelpers, navigation, setOptions, emitter]
   );
 
-  cache.current = routes.reduce<
+  const next = routes.reduce<
     NavigationCache<State, ScreenOptions, EventMap, ActionHelpers>
   >((acc, route) => {
     const previous = cache.current[route.key];
 
-    type Thunk =
-      | NavigationAction
-      | ((state: State) => NavigationAction | null | undefined);
-
     if (previous) {
       // If a cached navigation object already exists, reuse it
       acc[route.key] = previous;
     } else {
-      const dispatch = (thunk: Thunk) => {
-        const action = typeof thunk === 'function' ? thunk(getState()) : thunk;
-
-        if (action != null) {
-          navigation.dispatch({ source: route.key, ...action });
-        }
-      };
-
       const withStack = (callback: () => void) => {
         let isStackSet = false;
 
@@ -134,6 +122,23 @@ export function useNavigationCache<
         }
       };
 
+      const dispatch = (
+        thunk:
+          | NavigationAction
+          | ((state: State) => NavigationAction | null | undefined)
+      ) => {
+        withStack(() =>
+          React.startTransition(() => {
+            const action =
+              typeof thunk === 'function' ? thunk(getState()) : thunk;
+
+            if (action != null) {
+              navigation.dispatch({ source: route.key, ...action });
+            }
+          })
+        );
+      };
+
       const actions = {
         ...router.actionCreators,
         ...CommonActions,
@@ -142,10 +147,8 @@ export function useNavigationCache<
       const helpers = Object.keys(actions).reduce<Record<string, () => void>>(
         (acc, name) => {
           acc[name] = (...args: any) =>
-            withStack(() =>
-              // @ts-expect-error: name is a valid key, but TypeScript is dumb
-              dispatch(actions[name](...args))
-            );
+            // @ts-expect-error: name is a valid key, but TypeScript is dumb
+            dispatch(actions[name](...args));
 
           return acc;
         },
@@ -160,7 +163,7 @@ export function useNavigationCache<
         ...helpers,
         // FIXME: too much work to fix the types for now
         ...(emitter.create(route.key) as any),
-        dispatch: (thunk: Thunk) => withStack(() => dispatch(thunk)),
+        dispatch,
         getParent: (routeName) => {
           if (routeName === route.name) {
             // If the passed route name is the same as the current route's name,
@@ -174,7 +177,7 @@ export function useNavigationCache<
 
           return parentNavigationHelpers;
         },
-        setOptions: (options: object) => {
+        setOptions: (options: Partial<ScreenOptions>) => {
           setOptions((o) => ({
             ...o,
             [route.key]: { ...o[route.key], ...options },
@@ -183,7 +186,7 @@ export function useNavigationCache<
         isFocused: () => {
           const state = rest.getState();
 
-          if (state.routes[state.index].key !== route.key) {
+          if (state.routes[state.index]?.key !== route.key) {
             return false;
           }
 
@@ -197,5 +200,9 @@ export function useNavigationCache<
     return acc;
   }, {});
 
-  return cache.current;
+  React.useInsertionEffect(() => {
+    cache.current = next;
+  });
+
+  return next;
 }

package/src/useNavigationHelpers.tsx

@@ -19,9 +19,9 @@ type Options<State extends NavigationState, Action extends NavigationAction> = {
   onAction: (action: NavigationAction) => boolean;
   onUnhandledAction: (action: NavigationAction) => void;
   getState: () => State;
+  state: State;
   emitter: NavigationEventEmitter<any>;
   router: Router<State, Action>;
-  stateRef: React.RefObject<State | null>;
 };
 
 /**
@@ -37,11 +37,28 @@ export function useNavigationHelpers<
   onAction,
   onUnhandledAction,
   getState,
+  state,
   emitter,
   router,
-  stateRef,
 }: Options<State, Action>) {
-  const parentNavigationHelpers = React.useContext(NavigationContext);
+  const parentNavigationHelpers = React.use(NavigationContext);
+
+  // In some cases (e.g. route names change), internal state might have changed
+  // But it hasn't been committed yet, so hasn't propagated to any listeners
+  // During this time, we need to return the internal state in `getState`
+  // Otherwise it can return an inconsistent state during render in children
+  // This may affect hooks like `useNavigationState` that need to read the state during render
+  // To avoid this, we use a ref for render phase, and immediately clear it on commit
+  // The ref won't be cleared if the render is discarded, e.g. when interrupted
+  // So we also track the stored state the render was based on
+  // Then ignore the ref once the stored state changes due to another dispatch
+  const stateRef = React.useRef<{ state: State; base: State } | null>(null);
+
+  stateRef.current = { state, base: getState() };
+
+  React.useInsertionEffect(() => {
+    stateRef.current = null;
+  });
 
   return React.useMemo(() => {
     const dispatch = (op: Action | ((state: State) => Action)) => {
@@ -87,16 +104,16 @@ export function useNavigationHelpers<
         );
       },
       getState: (): State => {
+        const current = getState();
+        const pending = stateRef.current;
+
         // FIXME: Workaround for when the state is read during render
-        // By this time, we haven't committed the new state yet
-        // Without this `useSyncExternalStore` will keep reading the old state
-        // This may result in `useNavigationState` or `useIsFocused` returning wrong values
-        // Apart from `useSyncExternalStore`, `getState` should never be called during render
-        if (stateRef.current != null) {
-          return stateRef.current;
+        // Apart from subscriptions, `getState` should never be called during render
+        if (pending != null && pending.base === current) {
+          return pending.state;
         }
 
-        return getState();
+        return current;
       },
     } as NavigationHelpers<ParamListBase, EventMap> & ActionHelpers;
 

package/src/useNavigationIndependentTree.tsx

@@ -3,5 +3,5 @@ import * as React from 'react';
 import { NavigationIndependentTreeContext } from './NavigationIndependentTreeContext';
 
 export function useNavigationIndependentTree() {
-  return React.useContext(NavigationIndependentTreeContext);
+  return React.use(NavigationIndependentTreeContext);
 }

package/src/useNavigationState.tsx

@@ -1,18 +1,19 @@
 import type { NavigationState, ParamListBase } from '@react-navigation/routers';
 import * as React from 'react';
-import useLatestCallback from 'use-latest-callback';
-import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector';
 
-import type {
-  NavigationListForNested,
-  NavigationProp,
-  RootNavigator,
-} from './types';
-import { useNavigation } from './useNavigation';
+import type { NavigationListForNested, RootNavigator } from './types';
+
+type NavigationStateEvent = 'update' | 'commit';
 
 type NavigationStateListener = {
   getState: () => NavigationState<ParamListBase>;
-  subscribe: (callback: () => void) => () => void;
+  getSnapshot: () => NavigationState<ParamListBase>;
+  subscribe: (callback: (event: NavigationStateEvent) => void) => () => void;
+};
+
+type NavigationStateEntry = {
+  listener: NavigationStateListener;
+  state: NavigationState<ParamListBase>;
 };
 
 type NavigationStateForNested<
@@ -35,8 +36,8 @@ type NavigationStateForNested<
 export function useNavigationState<
   const T,
   const Navigator = RootNavigator,
-  const RouteName extends
-    keyof NavigationListForNested<Navigator> = keyof NavigationListForNested<Navigator>,
+  const RouteName extends keyof NavigationListForNested<Navigator> =
+    keyof NavigationListForNested<Navigator>,
 >(
   routeName: RouteName,
   selector: (state: NavigationStateForNested<Navigator, RouteName>) => T
@@ -45,99 +46,161 @@ export function useNavigationState<T>(
   selector: (state: NavigationState<ParamListBase>) => T
 ): T;
 export function useNavigationState(...args: unknown[]): unknown {
-  let navigation: NavigationProp<ParamListBase> | undefined,
-    stateListener: NavigationStateListener | undefined,
-    selector;
+  const selector = typeof args[0] === 'string' ? args[1] : args[0];
 
-  if (typeof args[0] === 'string') {
-    // `useNavigation` uses `use` internally, so it's fine to call it conditionally
-    // @ts-expect-error we can't specify the type here
-    // eslint-disable-next-line react-hooks/rules-of-hooks
-    navigation = useNavigation(args[0]);
-    selector = args[1];
-  } else {
-    selector = args[0];
+  if (typeof selector !== 'function') {
+    throw new Error(
+      `A selector function must be provided (got ${typeof selector}).`
+    );
   }
 
-  if (navigation == null) {
-    stateListener = React.use(NavigationStateListenerContext);
+  // @ts-expect-error: the public overloads guarantee the selector's type, but
+  // the `unknown[]` implementation signature can't express it
+  const select: (state: NavigationState<ParamListBase>) => unknown = selector;
+
+  let listener: NavigationStateListener | undefined;
+
+  if (typeof args[0] === 'string') {
+    const name = args[0];
+    const listeners = React.use(NamedNavigationStateListenerListContext);
 
-    if (stateListener == null) {
+    listener = listeners?.[name];
+
+    if (listener == null) {
+      throw new Error(
+        `Couldn't find a navigator for the route '${name}' in any of the parent screens. Is your component inside the correct screen?`
+      );
+    }
+  } else {
+    listener = React.use(NavigationStateListenerContext);
+
+    if (listener == null) {
       throw new Error(
         "Couldn't get the navigation state. Is your component inside a navigator?"
       );
     }
   }
 
-  const subscribe = React.useCallback(
-    (callback: () => void) => {
-      if (navigation) {
-        return navigation.addListener('state', callback);
-      } else if (stateListener) {
-        return stateListener.subscribe(callback);
-      } else {
-        throw new Error(
-          "Couldn't subscribe to navigation state changes. This is not expected."
-        );
+  const { getState, getSnapshot, subscribe } = listener;
+
+  // The store can contain state from a transition that hasn't committed yet.
+  // Reading it during render can show state that doesn't match the navigator in that render.
+  // The reducer lets React process state in the same render lane as the navigator.
+  const [entry, dispatch] = React.useReducer(
+    (previous: NavigationStateEntry, event: NavigationStateEvent) => {
+      // Navigation state can change between the dispatch and the reducer running.
+      // Reading here ensures the processed event uses the state for that render.
+      const state = event === 'update' ? getState() : getSnapshot();
+
+      if (
+        previous.listener === listener &&
+        (previous.state === state ||
+          (event === 'update' &&
+            Object.is(select(previous.state), select(state))))
+      ) {
+        return previous;
       }
+
+      return { listener, state };
     },
-    [navigation, stateListener]
+    undefined,
+    () => ({ listener, state: getState() })
   );
 
-  const getSnapshot = navigation
-    ? navigation.getState
-    : stateListener?.getState;
+  let state = entry.state;
 
-  if (getSnapshot == null) {
-    throw new Error("Couldn't get the navigation state. This is not expected.");
-  }
+  const committedRef = React.useRef<{
+    entry: NavigationStateEntry | null;
+    state: NavigationState<ParamListBase>;
+    select: (state: NavigationState<ParamListBase>) => unknown;
+  }>({ entry: null, state, select });
 
-  if (typeof selector !== 'function') {
-    throw new Error(
-      `A selector function must be provided (got ${typeof selector}).`
-    );
+  React.useInsertionEffect(() => {
+    committedRef.current = { entry, state, select };
+  });
+
+  const snapshot = getSnapshot();
+
+  const behind =
+    state !== snapshot &&
+    // A different listener means the state belongs to another navigator.
+    // This can happen when the passed route name changes.
+    (entry.listener !== listener ||
+      // An entry that advanced past the last commit is at least as new as the snapshot.
+      // An entry that didn't advance while the committed state changed is older.
+      entry === committedRef.current.entry);
+
+  if (behind) {
+    state = snapshot;
+    dispatch('commit');
   }
 
-  const value = useSyncExternalStoreWithSelector(
-    subscribe,
-    getSnapshot,
-    getSnapshot,
-    // @ts-expect-error we can't infer the type here
-    selector
-  );
+  React.useLayoutEffect(() => {
+    const check = (event: NavigationStateEvent) => {
+      const { state, select } = committedRef.current;
+
+      // An 'update' event follows the latest state in the lane the update was made in.
+      // A 'commit' event syncs the reducer to the state committed by the navigator.
+      const target = event === 'update' ? getState() : getSnapshot();
+
+      if (state !== target && !Object.is(select(state), select(target))) {
+        dispatch(event);
+      }
+    };
 
-  return value;
+    const unsubscribe = subscribe(check);
+
+    // The reducer may not match the committed state when the subscription starts.
+    // This happens on mount during a transition or an update before subscribing.
+    check('commit');
+
+    return unsubscribe;
+  }, [getState, getSnapshot, subscribe]);
+
+  return select(state);
 }
 
 export function NavigationStateListenerProvider({
   state,
+  getState,
+  subscribe,
   children,
 }: {
   state: NavigationState<ParamListBase>;
+  getState: () => NavigationState<ParamListBase>;
+  subscribe: (callback: () => void) => () => void;
   children: React.ReactNode;
 }) {
-  const listeners = React.useRef<(() => void)[]>([]);
+  const snapshotRef = React.useRef(state);
 
-  const getState = useLatestCallback(() => state);
-
-  const subscribe = useLatestCallback((callback: () => void) => {
-    listeners.current.push(callback);
+  React.useInsertionEffect(() => {
+    snapshotRef.current = state;
+  }, [state]);
 
-    return () => {
-      listeners.current = listeners.current.filter((cb) => cb !== callback);
-    };
-  });
+  const [listeners] = React.useState(
+    () => new Set<(event: NavigationStateEvent) => void>()
+  );
 
-  React.useEffect(() => {
-    listeners.current.forEach((callback) => callback());
-  }, [state]);
+  React.useLayoutEffect(() => {
+    listeners.forEach((listener) => listener('commit'));
+  }, [listeners, state]);
 
   const context = React.useMemo(
     () => ({
       getState,
-      subscribe,
+      getSnapshot: () => snapshotRef.current,
+      subscribe: (callback: (event: NavigationStateEvent) => void) => {
+        const unsubscribe = subscribe(() => callback('update'));
+
+        listeners.add(callback);
+
+        return () => {
+          listeners.delete(callback);
+          unsubscribe();
+        };
+      },
     }),
-    [getState, subscribe]
+    [getState, listeners, subscribe]
   );
 
   return (
@@ -147,6 +210,42 @@ export function NavigationStateListenerProvider({
   );
 }
 
-const NavigationStateListenerContext = React.createContext<
+export function NamedNavigationStateListenerProvider({
+  name,
+  children,
+}: {
+  name: string;
+  children: React.ReactNode;
+}) {
+  const listener = React.use(NavigationStateListenerContext);
+
+  if (listener == null) {
+    throw new Error(
+      "Couldn't find a navigation state listener. This is likely because the navigator doesn't render its content under 'NavigationContent'."
+    );
+  }
+
+  const parents = React.use(NamedNavigationStateListenerListContext);
+
+  const listeners = React.useMemo(
+    () => ({
+      ...parents,
+      [name]: listener,
+    }),
+    [listener, name, parents]
+  );
+
+  return (
+    <NamedNavigationStateListenerListContext.Provider value={listeners}>
+      {children}
+    </NamedNavigationStateListenerListContext.Provider>
+  );
+}
+
+export const NavigationStateListenerContext = React.createContext<
   NavigationStateListener | undefined
 >(undefined);
+
+export const NamedNavigationStateListenerListContext = React.createContext<
+  Record<string, NavigationStateListener> | undefined
+>(undefined);

package/src/useOnAction.tsx

@@ -7,20 +7,23 @@ import type {
 } from '@react-navigation/routers';
 import * as React from 'react';
 
+import { ConsumedParamsContext } from './ConsumedParamsContext';
+import { getLoaderForStateChange } from './DataLoading';
 import {
   type ChildActionListener,
   type ChildBeforeRemoveListener,
   NavigationBuilderContext,
 } from './NavigationBuilderContext';
+import { StaticTreeContext } from './StaticTreeContext';
 import type { EventMapCore } from './types';
 import type { NavigationEventEmitter } from './useEventEmitter';
 import { shouldPreventRemove, useOnPreventRemove } from './useOnPreventRemove';
 
-type Options = {
-  router: Router<NavigationState, NavigationAction>;
-  key?: string;
-  getState: () => NavigationState;
-  setState: (state: NavigationState | PartialState<NavigationState>) => void;
+type Options<State extends NavigationState> = {
+  router: Router<State, NavigationAction>;
+  key?: string | undefined;
+  getState: () => State;
+  setState: (state: State | PartialState<State>) => void;
   actionListeners: ChildActionListener[];
   beforeRemoveListeners: Record<string, ChildBeforeRemoveListener | undefined>;
   routerConfigOptions: RouterConfigOptions;
@@ -36,7 +39,7 @@ type Options = {
  *
  * When the action handler handles as action, it returns `true`, otherwise `false`.
  */
-export function useOnAction({
+export function useOnAction<State extends NavigationState>({
   router,
   getState,
   setState,
@@ -45,18 +48,22 @@ export function useOnAction({
   beforeRemoveListeners,
   routerConfigOptions,
   emitter,
-}: Options) {
+}: Options<State>) {
   const {
     onAction: onActionParent,
     onRouteFocus: onRouteFocusParent,
     addListener: addListenerParent,
     onDispatchAction,
-  } = React.useContext(NavigationBuilderContext);
+    flushUpdates,
+  } = React.use(NavigationBuilderContext);
+
+  const tree = React.use(StaticTreeContext);
+  const consumedParams = React.use(ConsumedParamsContext);
 
   const routerConfigOptionsRef =
     React.useRef<RouterConfigOptions>(routerConfigOptions);
 
-  React.useEffect(() => {
+  React.useInsertionEffect(() => {
     routerConfigOptionsRef.current = routerConfigOptions;
   });
 
@@ -65,6 +72,11 @@ export function useOnAction({
       action: NavigationAction,
       visitedNavigators: Set<string> = new Set<string>()
     ) => {
+      // Apply any pending state updates scheduled during render before handling the action
+      // Otherwise the action will be handled with an outdated state,
+      // and the pending updates will overwrite the changes from the action
+      flushUpdates();
+
       const state = getState();
 
       // Since actions can bubble both up and down, they could come to the same navigator again
@@ -87,9 +99,18 @@ export function useOnAction({
         result =
           result === null && action.target === state.key ? state : result;
 
-        if (result !== null) {
-          onDispatchAction(action, state === result);
+        if (result !== null && result.stale !== false) {
+          // Some actions (e.g. `RESET`) may return a stale state from the router
+          // We rehydrate it before storing so the stored state is always usable
+          // Otherwise anything reading the state before the next render
+          // (e.g. another dispatch immediately after) would get an outdated state
+          result = router.getRehydratedState(
+            result,
+            routerConfigOptionsRef.current
+          );
+        }
 
+        if (result !== null) {
           if (state !== result) {
             const isPrevented = shouldPreventRemove(
               emitter,
@@ -100,10 +121,34 @@ export function useOnAction({
             );
 
             if (isPrevented) {
+              onDispatchAction(action, true);
+
               return true;
             }
 
+            if (getState() !== state) {
+              // Listeners for 'beforeRemove' may dispatch actions that change the state
+              // Then the result we have is outdated and would overwrite those changes
+              // So we handle the action again to calculate the result with the latest state
+              return onAction(action, new Set<string>());
+            }
+
+            onDispatchAction(action, false);
+
+            if (tree) {
+              const loader = getLoaderForStateChange(
+                tree,
+                result,
+                state,
+                consumedParams
+              );
+
+              loader?.();
+            }
+
             setState(result);
+          } else {
+            onDispatchAction(action, true);
           }
 
           if (onRouteFocusParent !== undefined) {
@@ -132,7 +177,7 @@ export function useOnAction({
         for (let i = actionListeners.length - 1; i >= 0; i--) {
           const listener = actionListeners[i];
 
-          if (listener(action, visitedNavigators)) {
+          if (listener?.(action, visitedNavigators)) {
             return true;
           }
         }
@@ -143,7 +188,9 @@ export function useOnAction({
     [
       actionListeners,
       beforeRemoveListeners,
+      consumedParams,
       emitter,
+      flushUpdates,
       getState,
       key,
       onActionParent,
@@ -151,6 +198,7 @@ export function useOnAction({
       onRouteFocusParent,
       router,
       setState,
+      tree,
     ]
   );
 
@@ -160,7 +208,7 @@ export function useOnAction({
     beforeRemoveListeners,
   });
 
-  React.useEffect(
+  React.useInsertionEffect(
     () => addListenerParent?.('action', onAction),
     [addListenerParent, onAction]
   );