@react-navigation/core 8.0.0-alpha.24 → 8.0.0-alpha.26

package/src/useNavigationCache.tsx

@@ -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,
@@ -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,12 +37,29 @@ export function useNavigationHelpers<
   onAction,
   onUnhandledAction,
   getState,
+  state,
   emitter,
   router,
-  stateRef,
 }: Options<State, Action>) {
   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)) => {
       const action = typeof op === 'function' ? op(getState()) : op;
@@ -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/useNavigationState.tsx

@@ -1,22 +1,14 @@
 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 NavigationStateListener = {
   getState: () => NavigationState<ParamListBase>;
   subscribe: (callback: () => void) => () => void;
 };
 
-type UseNavigationForName = (name: string) => NavigationProp<ParamListBase>;
-
 type NavigationStateForNested<
   Navigator,
   RouteName extends keyof NavigationListForNested<Navigator>,
@@ -47,81 +39,83 @@ 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
-    // Cast to a non-generic signature to skip overload resolution - otherwise TS
-    // eagerly expands `NavigationListForNested<RootNavigator>` at this call site.
-    navigation = (useNavigation as UseNavigationForName)(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 (stateListener == null) {
+  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 (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."
-        );
-      }
-    },
-    [navigation, stateListener]
-  );
+  const { getState, subscribe } = listener;
 
-  const getSnapshot = navigation
-    ? navigation.getState
-    : stateListener?.getState;
+  const [, forceUpdate] = React.useReducer((count: number) => count + 1, 0);
 
-  if (getSnapshot == null) {
-    throw new Error("Couldn't get the navigation state. This is not expected.");
-  }
+  const selected = select(getState());
 
-  if (typeof selector !== 'function') {
-    throw new Error(
-      `A selector function must be provided (got ${typeof selector}).`
-    );
-  }
+  const selectionRef = React.useRef({ select, selected });
 
-  const value = useSyncExternalStoreWithSelector(
-    subscribe,
-    getSnapshot,
-    getSnapshot,
-    // @ts-expect-error we can't infer the type here
-    selector
-  );
+  React.useLayoutEffect(() => {
+    selectionRef.current = { select, selected };
+  });
+
+  React.useEffect(() => {
+    const checkForUpdates = () => {
+      const selection = selectionRef.current;
 
-  return value;
+      if (!Object.is(selection.selected, selection.select(getState()))) {
+        forceUpdate();
+      }
+    };
+
+    const unsubscribe = subscribe(checkForUpdates);
+
+    // The state may have changed between the render and the subscription
+    checkForUpdates();
+
+    return unsubscribe;
+  }, [getState, subscribe]);
+
+  return selected;
 }
 
 export function NavigationStateListenerProvider({
   state,
+  getState,
   children,
 }: {
   state: NavigationState<ParamListBase>;
+  getState: () => NavigationState<ParamListBase>;
   children: React.ReactNode;
 }) {
   const listeners = React.useRef<(() => void)[]>([]);
-  const stateRef = React.useRef(state);
-
-  const getState = useLatestCallback(() => stateRef.current);
 
   const subscribe = useLatestCallback((callback: () => void) => {
     listeners.current.push(callback);
@@ -131,8 +125,8 @@ export function NavigationStateListenerProvider({
     };
   });
 
+  // Notify subscribers once the new state has committed
   React.useLayoutEffect(() => {
-    stateRef.current = state;
     listeners.current.forEach((callback) => callback());
   }, [state]);
 
@@ -151,6 +145,42 @@ export function NavigationStateListenerProvider({
   );
 }
 
+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>
+  );
+}
+
 const NavigationStateListenerContext = React.createContext<
   NavigationStateListener | undefined
 >(undefined);
+
+export const NamedNavigationStateListenerListContext = React.createContext<
+  Record<string, NavigationStateListener> | undefined
+>(undefined);

package/src/useOnAction.tsx

@@ -1,17 +1,22 @@
 import type {
   NavigationAction,
+  NavigationRoute,
   NavigationState,
+  ParamListBase,
+  PartialRoute,
   PartialState,
   Router,
   RouterConfigOptions,
 } from '@react-navigation/routers';
 import * as React from 'react';
 
+import { getLoaderForState } 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';
@@ -27,6 +32,40 @@ type Options<State extends NavigationState> = {
   emitter: NavigationEventEmitter<EventMapCore<any>>;
 };
 
+type MaybePartialRoute =
+  | NavigationRoute<ParamListBase, string>
+  | PartialRoute<NavigationRoute<ParamListBase, string>>;
+
+const didFocusedRouteChange = (
+  currentState: NavigationState | PartialState<NavigationState>,
+  nextState: NavigationState | PartialState<NavigationState>
+) => {
+  let currentFocusedRoute: MaybePartialRoute | undefined =
+    currentState.routes[currentState.index ?? 0];
+
+  let nextFocusedRoute: MaybePartialRoute | undefined =
+    nextState.routes[nextState.index ?? 0];
+
+  let changed = currentFocusedRoute?.key !== nextFocusedRoute?.key;
+
+  while (
+    !changed &&
+    currentFocusedRoute?.state != null &&
+    nextFocusedRoute?.state != null &&
+    currentFocusedRoute.state !== nextFocusedRoute.state
+  ) {
+    currentFocusedRoute =
+      currentFocusedRoute.state.routes[currentFocusedRoute.state.index ?? 0];
+
+    nextFocusedRoute =
+      nextFocusedRoute.state.routes[nextFocusedRoute.state.index ?? 0];
+
+    changed = currentFocusedRoute?.key !== nextFocusedRoute?.key;
+  }
+
+  return changed;
+};
+
 /**
  * Hook to handle actions for a navigator, including state updates and bubbling.
  *
@@ -53,10 +92,12 @@ export function useOnAction<State extends NavigationState>({
     onDispatchAction,
   } = React.use(NavigationBuilderContext);
 
+  const tree = React.use(StaticTreeContext);
+
   const routerConfigOptionsRef =
     React.useRef<RouterConfigOptions>(routerConfigOptions);
 
-  React.useEffect(() => {
+  React.useInsertionEffect(() => {
     routerConfigOptionsRef.current = routerConfigOptions;
   });
 
@@ -105,6 +146,12 @@ export function useOnAction<State extends NavigationState>({
 
             onDispatchAction(action, false);
 
+            if (tree && didFocusedRouteChange(state, result)) {
+              const loader = getLoaderForState(tree, result);
+
+              loader?.();
+            }
+
             setState(result);
           } else {
             onDispatchAction(action, true);
@@ -155,6 +202,7 @@ export function useOnAction<State extends NavigationState>({
       onRouteFocusParent,
       router,
       setState,
+      tree,
     ]
   );
 

package/src/useOptionsGetters.tsx

@@ -31,8 +31,11 @@ export function useOptionsGetters({ key, options, navigation }: Options) {
     }
   }, [navigation, onOptionsChange]);
 
-  React.useEffect(() => {
+  React.useInsertionEffect(() => {
     optionsRef.current = options;
+  }, [options]);
+
+  React.useEffect(() => {
     optionsChangeListener();
 
     return navigation?.addListener('focus', optionsChangeListener);

package/src/usePreventRemove.tsx

@@ -23,15 +23,24 @@ export function usePreventRemove(
   const navigation = useNavigation();
   const { key: routeKey } = useRoute();
 
-  const { setPreventRemove } = usePreventRemoveContext();
+  const { setPreventRemove, notifyPreventRemove } = usePreventRemoveContext();
 
-  React.useEffect(() => {
+  React.useInsertionEffect(() => {
     setPreventRemove(id, routeKey, preventRemove);
+
     return () => {
       setPreventRemove(id, routeKey, false);
     };
   }, [setPreventRemove, id, routeKey, preventRemove]);
 
+  React.useEffect(() => {
+    notifyPreventRemove();
+
+    return () => {
+      notifyPreventRemove();
+    };
+  }, [id, routeKey, preventRemove, notifyPreventRemove]);
+
   const beforeRemoveListener = useLatestCallback<
     EventListenerCallback<EventMapCore<any>, 'beforeRemove'>
   >((e) => {

package/src/useRouteCache.tsx

@@ -4,8 +4,6 @@ import * as React from 'react';
 import { isRecordEqual } from './isRecordEqual';
 import type { RouteProp } from './types';
 
-type RouteCache = Map<string, RouteProp<ParamListBase>>;
-
 /**
  * Utilities such as `getFocusedRouteNameFromRoute` need to access state.
  * So we need a way to suppress the warning for those use cases.
@@ -21,9 +19,12 @@ export function useRouteCache<State extends NavigationState>(
   routes: State['routes']
 ) {
   // Cache object which holds route objects for each screen
-  const cache = React.useMemo(() => ({ current: new Map() as RouteCache }), []);
+  const cache = React.useMemo(
+    () => ({ current: new Map<string, RouteProp<ParamListBase>>() }),
+    []
+  );
 
-  cache.current = routes.reduce((acc, route) => {
+  const next = routes.reduce((acc, route) => {
     const previous = cache.current.get(route.key);
     const { state, ...routeWithoutState } = route;
 
@@ -53,16 +54,23 @@ export function useRouteCache<State extends NavigationState>(
       }
     }
 
-    Object.defineProperty(proxy, CHILD_STATE, {
-      enumerable: false,
-      configurable: true,
-      value: state,
-    });
+    // @ts-expect-error: this isn't in type definitions coz we want this private
+    if (proxy[CHILD_STATE] !== state) {
+      Object.defineProperty(proxy, CHILD_STATE, {
+        enumerable: false,
+        configurable: true,
+        value: state,
+      });
+    }
 
     acc.set(route.key, proxy);
 
     return acc;
-  }, new Map() as RouteCache);
+  }, new Map<string, RouteProp<ParamListBase>>());
+
+  React.useInsertionEffect(() => {
+    cache.current = next;
+  });
 
-  return Array.from(cache.current.values());
+  return Array.from(next.values());
 }

package/src/useScheduleUpdate.tsx

@@ -4,17 +4,18 @@ import { NavigationBuilderContext } from './NavigationBuilderContext';
 
 /**
  * When screen config changes, we want to update the navigator in the same update phase.
- * However, navigation state is in the root component and React won't let us update it from a child.
- * This is a workaround for that, the scheduled update is stored in the ref without actually calling setState.
- * It lets all subsequent updates access the latest state so it stays correct.
- * Then we call setState during after the component updates.
+ * However, navigation state is in the root component and React won't let us update it from a child during render.
+ * The render could also be interrupted in concurrent mode, so we need to update after commit.
+ * So we queue the update in an insertion effect and flush it in a layout effect.
+ * Insertion effects run before layout effects, so every navigator in the tree has queued its update before we flush.
+ * This lets nested updates be applied from the root down without clobbering each other.
  */
 export function useScheduleUpdate(callback: () => void) {
   const { scheduleUpdate, flushUpdates } = React.use(NavigationBuilderContext);
 
-  // FIXME: This is potentially unsafe
-  // However, since we are using sync store, it might be fine
-  scheduleUpdate(callback);
+  React.useInsertionEffect(() => {
+    scheduleUpdate(callback);
+  });
 
   React.useLayoutEffect(flushUpdates);
 }

package/src/useSyncState.tsx

@@ -100,7 +100,11 @@ export function useSyncState<T>(getInitialState: () => T) {
 
     if (pendingUpdates.length !== 0) {
       store.batchUpdates(() => {
-        // Flush all the pending updates
+        // Updates are queued child-first as insertion effects run bottom-up.
+        // The root navigator replaces the whole state while nested navigators merge into it.
+        // So we apply them root-first to avoid the root clobbering nested updates.
+        pendingUpdates.reverse();
+
         for (const update of pendingUpdates) {
           update();
         }

package/src/utilities.tsx

@@ -15,6 +15,17 @@ export type KeysOf<T> = T extends {} ? keyof T : never;
  */
 export type KeyOf<T extends {}> = Extract<keyof T, string>;
 
+/**
+ * TS only checks object literals for excess properties when they are not generic.
+ * When an object is captured as a generic type, unknown keys are not caught.
+ * This builds a type from the provided object where any key not in the allowed type has the type `never`.
+ * Checking the provided object against this type then produces an error for each unknown key.
+ */
+export type NoExcessObject<Provided, Allowed> = Record<
+  Exclude<keyof Provided, keyof Allowed>,
+  never
+>;
+
 /**
  * We get a union type when using keyof, but we want an intersection instead.
  * https://stackoverflow.com/a/50375286/1665026
@@ -37,6 +48,23 @@ export type RequiredKeys<T extends object> = {
   [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
 }[keyof T];
 
+type OptionalKeys<T extends object> = Exclude<keyof T, RequiredKeys<T>>;
+
+/**
+ * Remove `| undefined` from the object type,
+ * and adjust the optionality of the keys based on the original type.
+ */
+export type NotUndefinedObject<
+  T extends object | undefined,
+  O extends object = NotUndefined<T>,
+> = undefined extends T
+  ? {
+      [K in RequiredKeys<O>]: O[K];
+    } & {
+      [K in OptionalKeys<O>]?: O[K] | undefined;
+    }
+  : T;
+
 export type UndefinedIfAllOptional<T> = T extends object
   ? RequiredKeys<T> extends never
     ? T | undefined

package/src/validatePathConfig.tsx

@@ -43,6 +43,7 @@ export function validatePathConfig(config: unknown, root = true) {
   }
 
   const pathConfig = config as Record<string, unknown>;
+
   let validationErrors: string[] | undefined;
 
   for (const key in pathConfig) {