@react-navigation/core 6.0.2

package/src/useNavigationCache.tsx

@@ -0,0 +1,159 @@
+import {
+  CommonActions,
+  NavigationAction,
+  NavigationState,
+  ParamListBase,
+  Router,
+} from '@react-navigation/routers';
+import * as React from 'react';
+
+import NavigationBuilderContext from './NavigationBuilderContext';
+import type { NavigationHelpers, NavigationProp } from './types';
+import type { NavigationEventEmitter } from './useEventEmitter';
+
+type Options<
+  State extends NavigationState,
+  EventMap extends Record<string, any>
+> = {
+  state: State;
+  getState: () => State;
+  navigation: NavigationHelpers<ParamListBase> &
+    Partial<NavigationProp<ParamListBase, string, any, any, any>>;
+  setOptions: (
+    cb: (options: Record<string, object>) => Record<string, object>
+  ) => void;
+  router: Router<State, NavigationAction>;
+  emitter: NavigationEventEmitter<EventMap>;
+};
+
+type NavigationCache<
+  State extends NavigationState,
+  ScreenOptions extends {},
+  EventMap extends Record<string, any>
+> = Record<
+  string,
+  NavigationProp<ParamListBase, string, State, ScreenOptions, EventMap>
+>;
+
+/**
+ * Hook to cache navigation objects for each screen in the navigator.
+ * It's important to cache them to make sure navigation objects don't change between renders.
+ * This lets us apply optimizations like `React.memo` to minimize re-rendering screens.
+ */
+export default function useNavigationCache<
+  State extends NavigationState,
+  ScreenOptions extends {},
+  EventMap extends Record<string, any>
+>({
+  state,
+  getState,
+  navigation,
+  setOptions,
+  router,
+  emitter,
+}: Options<State, EventMap>) {
+  const { stackRef } = React.useContext(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
+  // In reality, these deps will rarely change, if ever
+  const cache = React.useMemo(
+    () => ({ current: {} as NavigationCache<State, ScreenOptions, EventMap> }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [getState, navigation, setOptions, router, emitter]
+  );
+
+  const actions = {
+    ...router.actionCreators,
+    ...CommonActions,
+  };
+
+  cache.current = state.routes.reduce<
+    NavigationCache<State, ScreenOptions, EventMap>
+  >((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 {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { emit, ...rest } = navigation;
+
+      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;
+
+        try {
+          if (
+            process.env.NODE_ENV !== 'production' &&
+            stackRef &&
+            !stackRef.current
+          ) {
+            // Capture the stack trace for devtools
+            stackRef.current = new Error().stack;
+            isStackSet = true;
+          }
+
+          callback();
+        } finally {
+          if (isStackSet && stackRef) {
+            stackRef.current = undefined;
+          }
+        }
+      };
+
+      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))
+            );
+
+          return acc;
+        },
+        {}
+      );
+
+      acc[route.key] = {
+        ...rest,
+        ...helpers,
+        // FIXME: too much work to fix the types for now
+        ...(emitter.create(route.key) as any),
+        dispatch: (thunk: Thunk) => withStack(() => dispatch(thunk)),
+        setOptions: (options: object) =>
+          setOptions((o) => ({
+            ...o,
+            [route.key]: { ...o[route.key], ...options },
+          })),
+        isFocused: () => {
+          const state = getState();
+
+          if (state.routes[state.index].key !== route.key) {
+            return false;
+          }
+
+          // If the current screen is focused, we also need to check if parent navigator is focused
+          // This makes sure that we return the focus state in the whole tree, not just this navigator
+          return navigation ? navigation.isFocused() : true;
+        },
+      };
+    }
+
+    return acc;
+  }, {});
+
+  return cache.current;
+}

package/src/useNavigationContainerRef.tsx

@@ -0,0 +1,17 @@
+import * as React from 'react';
+
+import createNavigationContainerRef from './createNavigationContainerRef';
+import type { NavigationContainerRefWithCurrent } from './types';
+
+export default function useNavigationContainerRef<
+  ParamList extends {} = ReactNavigation.RootParamList
+>(): NavigationContainerRefWithCurrent<ParamList> {
+  const navigation =
+    React.useRef<NavigationContainerRefWithCurrent<ParamList> | null>(null);
+
+  if (navigation.current == null) {
+    navigation.current = createNavigationContainerRef<ParamList>();
+  }
+
+  return navigation.current;
+}

package/src/useNavigationHelpers.tsx

@@ -0,0 +1,98 @@
+import {
+  CommonActions,
+  NavigationAction,
+  NavigationState,
+  ParamListBase,
+  Router,
+} from '@react-navigation/routers';
+import * as React from 'react';
+
+import NavigationContext from './NavigationContext';
+import { NavigationHelpers, NavigationProp, PrivateValueStore } from './types';
+import UnhandledActionContext from './UnhandledActionContext';
+import type { NavigationEventEmitter } from './useEventEmitter';
+
+// This is to make TypeScript compiler happy
+// eslint-disable-next-line babel/no-unused-expressions
+PrivateValueStore;
+
+type Options<State extends NavigationState, Action extends NavigationAction> = {
+  onAction: (action: NavigationAction) => boolean;
+  getState: () => State;
+  emitter: NavigationEventEmitter<any>;
+  router: Router<State, Action>;
+};
+
+/**
+ * Navigation object with helper methods to be used by a navigator.
+ * This object includes methods for common actions as well as methods the parent screen's navigation object.
+ */
+export default function useNavigationHelpers<
+  State extends NavigationState,
+  ActionHelpers extends Record<string, () => void>,
+  Action extends NavigationAction,
+  EventMap extends Record<string, any>
+>({ onAction, getState, emitter, router }: Options<State, Action>) {
+  const onUnhandledAction = React.useContext(UnhandledActionContext);
+  const parentNavigationHelpers = React.useContext(NavigationContext);
+
+  return React.useMemo(() => {
+    const dispatch = (op: Action | ((state: State) => Action)) => {
+      const action = typeof op === 'function' ? op(getState()) : op;
+
+      const handled = onAction(action);
+
+      if (!handled) {
+        onUnhandledAction?.(action);
+      }
+    };
+
+    const actions = {
+      ...router.actionCreators,
+      ...CommonActions,
+    };
+
+    const helpers = Object.keys(actions).reduce<Record<string, () => void>>(
+      (acc, name) => {
+        // @ts-expect-error: name is a valid key, but TypeScript is dumb
+        acc[name] = (...args: any) => dispatch(actions[name](...args));
+        return acc;
+      },
+      {}
+    );
+
+    return {
+      ...parentNavigationHelpers,
+      ...helpers,
+      dispatch,
+      emit: emitter.emit,
+      isFocused: parentNavigationHelpers
+        ? parentNavigationHelpers.isFocused
+        : () => true,
+      canGoBack: () => {
+        const state = getState();
+
+        return (
+          router.getStateForAction(state, CommonActions.goBack() as Action, {
+            routeNames: state.routeNames,
+            routeParamList: {},
+            routeGetIdList: {},
+          }) !== null ||
+          parentNavigationHelpers?.canGoBack() ||
+          false
+        );
+      },
+      getParent: () => parentNavigationHelpers as any,
+      getState,
+    } as NavigationHelpers<ParamListBase, EventMap> &
+      (NavigationProp<ParamListBase, string, any, any, any> | undefined) &
+      ActionHelpers;
+  }, [
+    emitter.emit,
+    getState,
+    onAction,
+    onUnhandledAction,
+    parentNavigationHelpers,
+    router,
+  ]);
+}

package/src/useNavigationState.tsx

@@ -0,0 +1,41 @@
+import type { NavigationState, ParamListBase } from '@react-navigation/routers';
+import * as React from 'react';
+
+import type { NavigationProp } from './types';
+import useNavigation from './useNavigation';
+
+type Selector<ParamList extends ParamListBase, T> = (
+  state: NavigationState<ParamList>
+) => T;
+
+/**
+ * Hook to get a value from the current navigation state using a selector.
+ *
+ * @param selector Selector function to get a value from the state.
+ */
+export default function useNavigationState<ParamList extends ParamListBase, T>(
+  selector: Selector<ParamList, T>
+): T {
+  const navigation = useNavigation<NavigationProp<ParamList>>();
+
+  // We don't care about the state value, we run the selector again at the end
+  // The state is only to make sure that there's a re-render when we have a new value
+  const [, setResult] = React.useState(() => selector(navigation.getState()));
+
+  // We store the selector in a ref to avoid re-subscribing listeners every render
+  const selectorRef = React.useRef(selector);
+
+  React.useEffect(() => {
+    selectorRef.current = selector;
+  });
+
+  React.useEffect(() => {
+    const unsubscribe = navigation.addListener('state', (e) => {
+      setResult(selectorRef.current(e.data.state));
+    });
+
+    return unsubscribe;
+  }, [navigation]);
+
+  return selector(navigation.getState());
+}

package/src/useOnAction.tsx

@@ -0,0 +1,166 @@
+import type {
+  NavigationAction,
+  NavigationState,
+  PartialState,
+  Router,
+  RouterConfigOptions,
+} from '@react-navigation/routers';
+import * as React from 'react';
+
+import NavigationBuilderContext, {
+  ChildActionListener,
+  ChildBeforeRemoveListener,
+} from './NavigationBuilderContext';
+import type { EventMapCore } from './types';
+import type { NavigationEventEmitter } from './useEventEmitter';
+import useOnPreventRemove, { shouldPreventRemove } from './useOnPreventRemove';
+
+type Options = {
+  router: Router<NavigationState, NavigationAction>;
+  key?: string;
+  getState: () => NavigationState;
+  setState: (state: NavigationState | PartialState<NavigationState>) => void;
+  actionListeners: ChildActionListener[];
+  beforeRemoveListeners: Record<string, ChildBeforeRemoveListener | undefined>;
+  routerConfigOptions: RouterConfigOptions;
+  emitter: NavigationEventEmitter<EventMapCore<any>>;
+};
+
+/**
+ * Hook to handle actions for a navigator, including state updates and bubbling.
+ *
+ * Bubbling an action is achieved in 2 ways:
+ * 1. To bubble action to parent, we expose the action handler in context and then access the parent context
+ * 2. To bubble action to child, child adds event listeners subscribing to actions from parent
+ *
+ * When the action handler handles as action, it returns `true`, otherwise `false`.
+ */
+export default function useOnAction({
+  router,
+  getState,
+  setState,
+  key,
+  actionListeners,
+  beforeRemoveListeners,
+  routerConfigOptions,
+  emitter,
+}: Options) {
+  const {
+    onAction: onActionParent,
+    onRouteFocus: onRouteFocusParent,
+    addListener: addListenerParent,
+    onDispatchAction,
+  } = React.useContext(NavigationBuilderContext);
+
+  const routerConfigOptionsRef =
+    React.useRef<RouterConfigOptions>(routerConfigOptions);
+
+  React.useEffect(() => {
+    routerConfigOptionsRef.current = routerConfigOptions;
+  });
+
+  const onAction = React.useCallback(
+    (
+      action: NavigationAction,
+      visitedNavigators: Set<string> = new Set<string>()
+    ) => {
+      const state = getState();
+
+      // Since actions can bubble both up and down, they could come to the same navigator again
+      // We keep track of navigators which have already tried to handle the action and return if it's already visited
+      if (visitedNavigators.has(state.key)) {
+        return false;
+      }
+
+      visitedNavigators.add(state.key);
+
+      if (typeof action.target !== 'string' || action.target === state.key) {
+        let result = router.getStateForAction(
+          state,
+          action,
+          routerConfigOptionsRef.current
+        );
+
+        // 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;
+
+        if (result !== null) {
+          onDispatchAction(action, state === result);
+
+          if (state !== result) {
+            const isPrevented = shouldPreventRemove(
+              emitter,
+              beforeRemoveListeners,
+              state.routes,
+              result.routes,
+              action
+            );
+
+            if (isPrevented) {
+              return true;
+            }
+
+            setState(result);
+          }
+
+          if (onRouteFocusParent !== undefined) {
+            // Some actions such as `NAVIGATE` also want to bring the navigated route to focus in the whole tree
+            // This means we need to focus all of the parent navigators of this navigator as well
+            const shouldFocus = router.shouldActionChangeFocus(action);
+
+            if (shouldFocus && key !== undefined) {
+              onRouteFocusParent(key);
+            }
+          }
+
+          return true;
+        }
+      }
+
+      if (onActionParent !== undefined) {
+        // Bubble action to the parent if the current navigator didn't handle it
+        if (onActionParent(action, visitedNavigators)) {
+          return true;
+        }
+      }
+
+      // If the action wasn't handled by current navigator or a parent navigator, let children handle it
+      for (let i = actionListeners.length - 1; i >= 0; i--) {
+        const listener = actionListeners[i];
+
+        if (listener(action, visitedNavigators)) {
+          return true;
+        }
+      }
+
+      return false;
+    },
+    [
+      actionListeners,
+      beforeRemoveListeners,
+      emitter,
+      getState,
+      key,
+      onActionParent,
+      onDispatchAction,
+      onRouteFocusParent,
+      router,
+      setState,
+    ]
+  );
+
+  useOnPreventRemove({
+    getState,
+    emitter,
+    beforeRemoveListeners,
+  });
+
+  React.useEffect(
+    () => addListenerParent?.('action', onAction),
+    [addListenerParent, onAction]
+  );
+
+  return onAction;
+}

package/src/useOnGetState.tsx

@@ -0,0 +1,47 @@
+import type { NavigationState } from '@react-navigation/routers';
+import * as React from 'react';
+
+import isArrayEqual from './isArrayEqual';
+import NavigationBuilderContext, {
+  GetStateListener,
+} from './NavigationBuilderContext';
+import NavigationRouteContext from './NavigationRouteContext';
+
+type Options = {
+  getState: () => NavigationState;
+  getStateListeners: Record<string, GetStateListener | undefined>;
+};
+
+export default function useOnGetState({
+  getState,
+  getStateListeners,
+}: Options) {
+  const { addKeyedListener } = React.useContext(NavigationBuilderContext);
+  const route = React.useContext(NavigationRouteContext);
+  const key = route ? route.key : 'root';
+
+  const getRehydratedState = React.useCallback(() => {
+    const state = getState();
+
+    // Avoid returning new route objects if we don't need to
+    const routes = state.routes.map((route) => {
+      const childState = getStateListeners[route.key]?.();
+
+      if (route.state === childState) {
+        return route;
+      }
+
+      return { ...route, state: childState };
+    });
+
+    if (isArrayEqual(state.routes, routes)) {
+      return state;
+    }
+
+    return { ...state, routes };
+  }, [getState, getStateListeners]);
+
+  React.useEffect(() => {
+    return addKeyedListener?.('getState', key, getRehydratedState);
+  }, [addKeyedListener, getRehydratedState, key]);
+}

package/src/useOnPreventRemove.tsx

@@ -0,0 +1,99 @@
+import type {
+  NavigationAction,
+  NavigationState,
+} from '@react-navigation/routers';
+import * as React from 'react';
+
+import NavigationBuilderContext, {
+  ChildBeforeRemoveListener,
+} from './NavigationBuilderContext';
+import NavigationRouteContext from './NavigationRouteContext';
+import type { EventMapCore } from './types';
+import type { NavigationEventEmitter } from './useEventEmitter';
+
+type Options = {
+  getState: () => NavigationState;
+  emitter: NavigationEventEmitter<EventMapCore<any>>;
+  beforeRemoveListeners: Record<string, ChildBeforeRemoveListener | undefined>;
+};
+
+const VISITED_ROUTE_KEYS = Symbol('VISITED_ROUTE_KEYS');
+
+export const shouldPreventRemove = (
+  emitter: NavigationEventEmitter<EventMapCore<any>>,
+  beforeRemoveListeners: Record<string, ChildBeforeRemoveListener | undefined>,
+  currentRoutes: { key: string }[],
+  nextRoutes: { key?: string | undefined }[],
+  action: NavigationAction
+) => {
+  const nextRouteKeys = nextRoutes.map((route) => route.key);
+
+  // Call these in reverse order so last screens handle the event first
+  const removedRoutes = currentRoutes
+    .filter((route) => !nextRouteKeys.includes(route.key))
+    .reverse();
+
+  const visitedRouteKeys: Set<string> =
+    // @ts-expect-error: add this property to mark that we've already emitted this action
+    action[VISITED_ROUTE_KEYS] ?? new Set<string>();
+
+  const beforeRemoveAction = {
+    ...action,
+    [VISITED_ROUTE_KEYS]: visitedRouteKeys,
+  };
+
+  for (const route of removedRoutes) {
+    if (visitedRouteKeys.has(route.key)) {
+      // Skip if we've already emitted this action for this screen
+      continue;
+    }
+
+    // First, we need to check if any child screens want to prevent it
+    const isPrevented = beforeRemoveListeners[route.key]?.(beforeRemoveAction);
+
+    if (isPrevented) {
+      return true;
+    }
+
+    visitedRouteKeys.add(route.key);
+
+    const event = emitter.emit({
+      type: 'beforeRemove',
+      target: route.key,
+      data: { action: beforeRemoveAction },
+      canPreventDefault: true,
+    });
+
+    if (event.defaultPrevented) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+export default function useOnPreventRemove({
+  getState,
+  emitter,
+  beforeRemoveListeners,
+}: Options) {
+  const { addKeyedListener } = React.useContext(NavigationBuilderContext);
+  const route = React.useContext(NavigationRouteContext);
+  const routeKey = route?.key;
+
+  React.useEffect(() => {
+    if (routeKey) {
+      return addKeyedListener?.('beforeRemove', routeKey, (action) => {
+        const state = getState();
+
+        return shouldPreventRemove(
+          emitter,
+          beforeRemoveListeners,
+          state.routes,
+          [],
+          action
+        );
+      });
+    }
+  }, [addKeyedListener, beforeRemoveListeners, emitter, getState, routeKey]);
+}

package/src/useOnRouteFocus.tsx

@@ -0,0 +1,47 @@
+import type {
+  NavigationAction,
+  NavigationState,
+  Router,
+} from '@react-navigation/routers';
+import * as React from 'react';
+
+import NavigationBuilderContext from './NavigationBuilderContext';
+
+type Options<Action extends NavigationAction> = {
+  router: Router<NavigationState, Action>;
+  getState: () => NavigationState;
+  setState: (state: NavigationState) => void;
+  key?: string;
+};
+
+/**
+ * Hook to handle focus actions for a route.
+ * Focus action needs to be treated specially, coz when a nested route is focused,
+ * the parent navigators also needs to be focused.
+ */
+export default function useOnRouteFocus<Action extends NavigationAction>({
+  router,
+  getState,
+  key: sourceRouteKey,
+  setState,
+}: Options<Action>) {
+  const { onRouteFocus: onRouteFocusParent } = React.useContext(
+    NavigationBuilderContext
+  );
+
+  return React.useCallback(
+    (key: string) => {
+      const state = getState();
+      const result = router.getStateForRouteFocus(state, key);
+
+      if (result !== state) {
+        setState(result);
+      }
+
+      if (onRouteFocusParent !== undefined && sourceRouteKey !== undefined) {
+        onRouteFocusParent(sourceRouteKey);
+      }
+    },
+    [getState, onRouteFocusParent, router, setState, sourceRouteKey]
+  );
+}