@react-navigation/core 8.0.0-alpha.4 → 8.0.0-alpha.40

package/src/useNavigationState.tsx

@@ -1,18 +1,20 @@
 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 = {
+  initialStateContext: React.Context<NavigationState<ParamListBase>>;
   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 +37,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,108 +47,244 @@ 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);
+
+    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 (stateListener == null) {
+    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;
+
+  const initialRef = React.useRef(true);
+
+  // We read the initial state from context on mount instead of using getState
+  // This ensures that we get proper state for the current render,
+  // even if the external store has been updated.
+  // We conditionally use `use` to avoid more unnecessary re-renders after first mount.
+  // The context subscription is removed on the next render, which can cause one extra render.
+  const initialState = initialRef.current
+    ? React.use(listener.initialStateContext)
+    : undefined;
+
+  // We track the last committed reducer entry, navigation state, and selector,
+  // so we can check if an update changes the value the component last committed.
+  const committedRef = React.useRef<{
+    entry: NavigationStateEntry | null;
+    state: NavigationState<ParamListBase>;
+    select: (state: NavigationState<ParamListBase>) => unknown;
+  }>({ entry: null, state: initialState ?? getSnapshot(), select });
+
+  // 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 we're processing the same reducer entry as the last commit,
+      // we compare against the state last committed by the component.
+      // We keep the reducer entry to avoid re-renders for unchanged selections.
+      // This means the reducer entry can still hold older navigation state.
+      // If a parent causes another render,
+      // we use the latest snapshot so the selector doesn't read stale state.
+      // We leave the reducer entry unchanged to avoid an extra render.
+      // We save that snapshot in committedRef when the render commits,
+      // so later updates compare against the state we actually rendered,
+      // including when the selector changed.
+      // If the reducer entry is different, we use its own navigation state,
+      // so comparisons include updates already processed in the pending render.
+      const previousState =
+        previous === committedRef.current.entry
+          ? committedRef.current.state
+          : previous.state;
+
+      if (
+        previous.listener === listener &&
+        (previousState === state ||
+          (event === 'update' &&
+            Object.is(select(previousState), select(state))))
+      ) {
+        return previous;
       }
+
+      return { listener, state };
     },
-    [navigation, stateListener]
+    undefined,
+    () => ({ listener, state: initialState ?? getSnapshot() })
   );
 
-  const getSnapshot = navigation
-    ? navigation.getState
-    : stateListener?.getState;
+  const state =
+    // 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
+      ? getSnapshot()
+      : entry.state;
 
-  if (getSnapshot == null) {
-    throw new Error("Couldn't get the navigation state. This is not expected.");
-  }
+  React.useInsertionEffect(() => {
+    initialRef.current = false;
+    committedRef.current = { entry, state, select };
+  });
 
-  if (typeof selector !== 'function') {
-    throw new Error(
-      `A selector function must be provided (got ${typeof selector}).`
-    );
-  }
+  React.useLayoutEffect(() => {
+    const check = (event: NavigationStateEvent) => {
+      const { state, select } = committedRef.current;
 
-  const value = useSyncExternalStoreWithSelector(
-    subscribe,
-    getSnapshot,
-    getSnapshot,
-    // @ts-expect-error we can't infer the type here
-    selector
-  );
+      // 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);
+      }
+    };
+
+    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 value;
+  return select(state);
 }
 
 export function NavigationStateListenerProvider({
+  isSynced,
   state,
+  getState,
+  subscribe,
   children,
 }: {
+  isSynced: boolean;
   state: NavigationState<ParamListBase>;
+  getState: () => NavigationState<ParamListBase>;
+  subscribe: (callback: () => void) => () => void;
   children: React.ReactNode;
 }) {
-  const listeners = React.useRef<(() => void)[]>([]);
+  const [InitialStateContext] = React.useState(() =>
+    React.createContext(state)
+  );
 
-  const getState = useLatestCallback(() => state);
+  const [listeners] = React.useState(
+    () => new Set<(event: NavigationStateEvent) => void>()
+  );
 
-  const subscribe = useLatestCallback((callback: () => void) => {
-    listeners.current.push(callback);
+  React.useLayoutEffect(() => {
+    listeners.forEach((listener) => listener('commit'));
+  }, [listeners, state]);
 
-    return () => {
-      listeners.current = listeners.current.filter((cb) => cb !== callback);
-    };
-  });
+  const snapshotRef = React.useRef(state);
 
-  React.useEffect(() => {
-    listeners.current.forEach((callback) => callback());
+  React.useInsertionEffect(() => {
+    snapshotRef.current = state;
   }, [state]);
 
+  // Route config or nested params can produce new state during render.
+  // If the scheduled update hasn't synced that state to the store yet,
+  // We need to expose the rendered state so consumers match the navigator.
+  // We keep this `undefined` for other scenarios, so the context isn't recreated.
+  const nextState = isSynced ? undefined : state;
+
   const context = React.useMemo(
     () => ({
+      initialStateContext: InitialStateContext,
       getState,
-      subscribe,
+      getSnapshot: () => nextState ?? snapshotRef.current,
+      subscribe: (callback: (event: NavigationStateEvent) => void) => {
+        const unsubscribe = subscribe(() => callback('update'));
+
+        listeners.add(callback);
+
+        return () => {
+          listeners.delete(callback);
+          unsubscribe();
+        };
+      },
     }),
-    [getState, subscribe]
+    [InitialStateContext, getState, listeners, nextState, subscribe]
   );
 
   return (
     <NavigationStateListenerContext.Provider value={context}>
-      {children}
+      <InitialStateContext.Provider value={state}>
+        {children}
+      </InitialStateContext.Provider>
     </NavigationStateListenerContext.Provider>
   );
 }
 
-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 a bug in the navigator.\n\nIf you're using a custom navigator, make sure that the navigator content is wrapped by the 'render' function returned by 'useNavigationBuilder'."
+    );
+  }
+
+  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,
+  useNavigationBuilderContext,
 } 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,
+  } = useNavigationBuilderContext();
+
+  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
@@ -83,13 +95,23 @@ export function useOnAction({
         );
 
         // If a target is specified and set to current navigator, the action shouldn't bubble
-        // So instead of `null`, we use the state object for such cases to signal that action was handled
-        result =
-          result === null && action.target === state.key ? state : result;
+        // So we immediately return `false` to mark it as unhandled
+        if (result === null && action.target === state.key) {
+          return false;
+        }
 
-        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 +122,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) {
@@ -120,19 +166,44 @@ export function useOnAction({
         }
       }
 
+      const isSourceInCurrentNavigator =
+        action.source !== undefined &&
+        state.routes.some((r) => r.key === action.source);
+
       if (onActionParent !== undefined) {
         // Bubble action to the parent if the current navigator didn't handle it
-        if (onActionParent(action, visitedNavigators)) {
+        const parentAction =
+          isSourceInCurrentNavigator && key !== undefined
+            ? {
+                ...action,
+                // If the `source` belonged to the current navigator,
+                // rewrite the `source` to the parent screen's key when bubbling
+                // This will let parent handle it relative to the child that dispatched the action
+                source: key,
+              }
+            : action;
+
+        if (onActionParent(parentAction, visitedNavigators)) {
           return true;
         }
       }
 
       if (typeof action.target === 'string') {
         // If the action wasn't handled by current navigator or a parent navigator, let children handle it
+        const childAction = isSourceInCurrentNavigator
+          ? {
+              ...action,
+              // If the `source` belonged to the current navigator,
+              // remove it when targeting a child navigator
+              // So child navigators can handle it based on the focused screen
+              source: undefined,
+            }
+          : action;
+
         for (let i = actionListeners.length - 1; i >= 0; i--) {
           const listener = actionListeners[i];
 
-          if (listener(action, visitedNavigators)) {
+          if (listener?.(childAction, visitedNavigators)) {
             return true;
           }
         }
@@ -143,7 +214,9 @@ export function useOnAction({
     [
       actionListeners,
       beforeRemoveListeners,
+      consumedParams,
       emitter,
+      flushUpdates,
       getState,
       key,
       onActionParent,
@@ -151,6 +224,7 @@ export function useOnAction({
       onRouteFocusParent,
       router,
       setState,
+      tree,
     ]
   );
 
@@ -160,7 +234,7 @@ export function useOnAction({
     beforeRemoveListeners,
   });
 
-  React.useEffect(
+  React.useInsertionEffect(
     () => addListenerParent?.('action', onAction),
     [addListenerParent, onAction]
   );

package/src/useOnGetNavigation.tsx

@@ -0,0 +1,30 @@
+import type { ParamListBase } from '@react-navigation/routers';
+import * as React from 'react';
+
+import { useNavigationBuilderContext } from './NavigationBuilderContext';
+import { NavigationRouteContext } from './NavigationProvider';
+import type { NavigationHelpers } from './types';
+
+type Options = {
+  navigation: NavigationHelpers<ParamListBase>;
+};
+
+/**
+ * Hook which lets the container access the navigation object of the root navigator.
+ * It's used for the navigation object returned by `useNavigation` outside a screen.
+ */
+export function useOnGetNavigation({ navigation }: Options) {
+  const { addKeyedListener } = useNavigationBuilderContext();
+
+  const route = React.use(NavigationRouteContext);
+
+  React.useInsertionEffect(() => {
+    // We only register if this is the root navigator
+    // i.e. there is no parent route
+    if (route != null) {
+      return;
+    }
+
+    return addKeyedListener?.('getNavigation', 'root', () => navigation);
+  }, [addKeyedListener, navigation, route]);
+}

package/src/useOnGetState.tsx

@@ -4,7 +4,7 @@ import * as React from 'react';
 import { isArrayEqual } from './isArrayEqual';
 import {
   type GetStateListener,
-  NavigationBuilderContext,
+  useNavigationBuilderContext,
 } from './NavigationBuilderContext';
 import { NavigationRouteContext } from './NavigationProvider';
 
@@ -14,8 +14,10 @@ type Options = {
 };
 
 export function useOnGetState({ getState, getStateListeners }: Options) {
-  const { addKeyedListener } = React.useContext(NavigationBuilderContext);
-  const route = React.useContext(NavigationRouteContext);
+  const { addKeyedListener } = useNavigationBuilderContext();
+
+  const route = React.use(NavigationRouteContext);
+
   const key = route ? route.key : 'root';
 
   const getRehydratedState = React.useCallback(() => {
@@ -39,7 +41,9 @@ export function useOnGetState({ getState, getStateListeners }: Options) {
     return { ...state, routes };
   }, [getState, getStateListeners]);
 
-  React.useEffect(() => {
+  // Use insertion effect to preserve the listener under `<Activity mode="hidden">`
+  // So `getRootState` will still return state of nested navigators
+  React.useInsertionEffect(() => {
     return addKeyedListener?.('getState', key, getRehydratedState);
   }, [addKeyedListener, getRehydratedState, key]);
 }