@react-navigation/native 7.1.25 → 8.0.0-alpha.0

package/src/NavigationContainer.tsx

@@ -3,16 +3,16 @@ import {
   getActionFromState,
   getPathFromState,
   getStateFromPath,
+  type InitialState,
   type NavigationContainerProps,
   type NavigationContainerRef,
-  type NavigationState,
   type ParamListBase,
+  type RootParamList,
   ThemeProvider,
   validatePathConfig,
 } from '@react-navigation/core';
 import * as React from 'react';
-import { I18nManager } from 'react-native';
-import useLatestCallback from 'use-latest-callback';
+import { I18nManager, Platform } from 'react-native';
 
 import { LinkingContext } from './LinkingContext';
 import { LocaleDirContext } from './LocaleDirContext';
@@ -21,12 +21,12 @@ import type {
   DocumentTitleOptions,
   LinkingOptions,
   LocaleDirection,
+  Persistor,
 } from './types';
-import { UnhandledLinkingContext } from './UnhandledLinkingContext';
 import { useBackButton } from './useBackButton';
 import { useDocumentTitle } from './useDocumentTitle';
 import { useLinking } from './useLinking';
-import { useThenable } from './useThenable';
+import { type Thenable, useThenable } from './useThenable';
 
 declare global {
   var REACT_NAVIGATION_DEVTOOLS: WeakMap<
@@ -41,7 +41,9 @@ type Props<ParamList extends {}> = NavigationContainerProps & {
   /**
    * Initial state object for the navigation tree.
    *
-   * If this is provided, deep link or URLs won't be handled on the initial render.
+   * If this is provided:
+   * - Deep link or URLs won't be handled on the initial render.
+   * - Persisted state won't be restored.
    */
   initialState?: NavigationContainerProps['initialState'];
   /**
@@ -56,11 +58,36 @@ type Props<ParamList extends {}> = NavigationContainerProps & {
    */
   linking?: LinkingOptions<ParamList>;
   /**
-   * Fallback element to render until initial state is resolved from deep linking.
+   * Persistor object to persist and restore navigation state.
+   *
+   * State is not restored if a deep link is handled on the initial render
+   * Not supported on web when linking is enabled.
+   *
+   * Example:
+   *
+   * ```ts
+   * const persistor = {
+   *   async persist(state) {
+   *     await AsyncStorage.setItem('state-key-v1', JSON.stringify(state));
+   *   },
+   *   async restore() {
+   *     const state = await AsyncStorage.getItem('state-key-v1');
+   *
+   *     return state ? JSON.parse(state) : undefined;
+   *   },
+   * };
+   *
+   * <NavigationContainer persistor={persistor}>...</NavigationContainer>
+   * ```
+   */
+  persistor?: Persistor;
+  /**
+   * Fallback element to render until initial state is resolved.
+   * Used when deep link or persisted state is being restored asynchronously.
    *
    * Defaults to `null`.
    */
-  fallback?: React.ReactNode;
+  fallback?: React.ReactElement | null;
   /**
    * Options to configure the document title on Web.
    *
@@ -70,21 +97,22 @@ type Props<ParamList extends {}> = NavigationContainerProps & {
   documentTitle?: DocumentTitleOptions;
 };
 
+const RESTORE_STATE_ERROR =
+  'Failed to restore navigation state. The state will be initialized based on the navigation tree.';
+
 function NavigationContainerInner(
   {
     direction = I18nManager.getConstants().isRTL ? 'rtl' : 'ltr',
     theme = DefaultTheme,
     linking,
+    persistor,
     fallback = null,
     documentTitle,
-    onReady,
     onStateChange,
     ...rest
   }: Props<ParamListBase>,
   ref?: React.Ref<NavigationContainerRef<ParamListBase> | null>
 ) {
-  const isLinkingEnabled = linking ? linking.enabled !== false : false;
-
   if (linking?.config) {
     validatePathConfig(linking.config);
   }
@@ -95,82 +123,108 @@ function NavigationContainerInner(
   useBackButton(refContainer);
   useDocumentTitle(refContainer, documentTitle);
 
-  const [lastUnhandledLink, setLastUnhandledLink] = React.useState<
-    string | undefined
-  >();
-
-  const { getInitialState } = useLinking(
-    refContainer,
-    {
-      enabled: isLinkingEnabled,
-      prefixes: [],
-      ...linking,
-    },
-    setLastUnhandledLink
-  );
-
-  const linkingContext = React.useMemo(() => ({ options: linking }), [linking]);
+  const linkingConfig = React.useMemo(() => {
+    if (linking == null) {
+      return {
+        options: {
+          enabled: false,
+        },
+      };
+    }
 
-  const unhandledLinkingContext = React.useMemo(
-    () => ({ lastUnhandledLink, setLastUnhandledLink }),
-    [lastUnhandledLink, setLastUnhandledLink]
-  );
+    return {
+      options: {
+        ...linking,
+        enabled: linking.enabled !== false,
+        prefixes: linking.prefixes ?? ['*'],
+        getStateFromPath: linking?.getStateFromPath ?? getStateFromPath,
+        getPathFromState: linking?.getPathFromState ?? getPathFromState,
+        getActionFromState: linking?.getActionFromState ?? getActionFromState,
+      },
+    };
+  }, [linking]);
 
-  const onReadyForLinkingHandling = useLatestCallback(() => {
-    // If the screen path matches lastUnhandledLink, we do not track it
-    const path = refContainer.current?.getCurrentRoute()?.path;
-    setLastUnhandledLink((previousLastUnhandledLink) => {
-      if (previousLastUnhandledLink === path) {
-        return undefined;
-      }
-      return previousLastUnhandledLink;
-    });
-    onReady?.();
-  });
+  const { getInitialState } = useLinking(refContainer, linkingConfig.options);
 
-  const onStateChangeForLinkingHandling = useLatestCallback(
-    (state: Readonly<NavigationState> | undefined) => {
-      // If the screen path matches lastUnhandledLink, we do not track it
-      const path = refContainer.current?.getCurrentRoute()?.path;
-      setLastUnhandledLink((previousLastUnhandledLink) => {
-        if (previousLastUnhandledLink === path) {
-          return undefined;
-        }
-        return previousLastUnhandledLink;
-      });
-      onStateChange?.(state);
-    }
-  );
   // Add additional linking related info to the ref
   // This will be used by the devtools
   React.useEffect(() => {
     if (refContainer.current) {
       REACT_NAVIGATION_DEVTOOLS.set(refContainer.current, {
         get linking() {
-          return {
-            ...linking,
-            enabled: isLinkingEnabled,
-            prefixes: linking?.prefixes ?? [],
-            getStateFromPath: linking?.getStateFromPath ?? getStateFromPath,
-            getPathFromState: linking?.getPathFromState ?? getPathFromState,
-            getActionFromState:
-              linking?.getActionFromState ?? getActionFromState,
-          };
+          return linkingConfig.options;
         },
       });
     }
   });
 
-  const [isResolved, initialState] = useThenable(getInitialState);
+  const [isLinkStateResolved, initialStateFromLink] = useThenable(() => {
+    if (rest.initialState != null || !linkingConfig.options.enabled) {
+      return undefined;
+    }
+
+    return getInitialState();
+  });
+
+  const isPersistenceSupported =
+    Platform.OS === 'web' ? !linkingConfig.options.enabled : true;
+
+  const [isPersistedStateResolved, initialStateFromPersisted] = useThenable(
+    () => {
+      if (
+        isPersistenceSupported === false ||
+        rest.initialState != null ||
+        persistor == null
+      ) {
+        return undefined;
+      }
+
+      let restoredState;
+
+      try {
+        restoredState = persistor.restore();
+      } catch (e) {
+        console.error(RESTORE_STATE_ERROR, e);
+
+        return undefined;
+      }
+
+      if (restoredState == null) {
+        return undefined;
+      }
+
+      if ('then' in restoredState) {
+        return restoredState.then(
+          (state) => state,
+          (error) => {
+            console.error(RESTORE_STATE_ERROR, error);
+
+            return undefined;
+          }
+        );
+      }
+
+      const thenable: Thenable<InitialState | undefined> = {
+        then(onfulfilled) {
+          return Promise.resolve(
+            onfulfilled ? onfulfilled(restoredState) : restoredState
+          );
+        },
+      };
+
+      return thenable;
+    }
+  );
 
   // FIXME
   // @ts-expect-error not sure why this is not working
   React.useImperativeHandle(ref, () => refContainer.current);
 
-  const isLinkingReady =
-    rest.initialState != null || !isLinkingEnabled || isResolved;
+  const isStateReady =
+    rest.initialState != null ||
+    (isLinkStateResolved && isPersistedStateResolved);
 
-  if (!isLinkingReady) {
+  if (!isStateReady) {
     return (
       <LocaleDirContext.Provider value={direction}>
         <ThemeProvider value={theme}>{fallback}</ThemeProvider>
@@ -180,32 +234,35 @@ function NavigationContainerInner(
 
   return (
     <LocaleDirContext.Provider value={direction}>
-      <UnhandledLinkingContext.Provider value={unhandledLinkingContext}>
-        <LinkingContext.Provider value={linkingContext}>
-          <BaseNavigationContainer
-            {...rest}
-            theme={theme}
-            onReady={onReadyForLinkingHandling}
-            onStateChange={onStateChangeForLinkingHandling}
-            initialState={
-              rest.initialState == null ? initialState : rest.initialState
-            }
-            ref={refContainer}
-          />
-        </LinkingContext.Provider>
-      </UnhandledLinkingContext.Provider>
+      <LinkingContext.Provider value={linkingConfig}>
+        <BaseNavigationContainer
+          {...rest}
+          theme={theme}
+          initialState={
+            rest.initialState ??
+            initialStateFromLink ??
+            initialStateFromPersisted
+          }
+          onStateChange={(state) => {
+            onStateChange?.(state);
+            persistor?.persist(state);
+          }}
+          ref={refContainer}
+        />
+      </LinkingContext.Provider>
     </LocaleDirContext.Provider>
   );
 }
 
 /**
  * Container component that manages the navigation state.
+ *
  * This should be rendered at the root wrapping the whole app.
  */
 export const NavigationContainer = React.forwardRef(
   NavigationContainerInner
-) as <RootParamList extends {} = ReactNavigation.RootParamList>(
-  props: Props<RootParamList> & {
-    ref?: React.Ref<NavigationContainerRef<RootParamList>>;
+) as <ParamList extends {} = RootParamList>(
+  props: Props<ParamList> & {
+    ref?: React.Ref<NavigationContainerRef<ParamList>>;
   }
 ) => React.ReactElement;

package/src/__stubs__/createStackNavigator.tsx

@@ -12,7 +12,6 @@ import {
 const StackNavigator = (
   props: DefaultNavigatorOptions<
     ParamListBase,
-    string | undefined,
     StackNavigationState<ParamListBase>,
     {},
     {},
@@ -35,7 +34,6 @@ export function createStackNavigator<
   ParamList extends ParamListBase,
 >(): TypedNavigator<{
   ParamList: ParamList;
-  NavigatorID: string | undefined;
   State: StackNavigationState<ParamList>;
   ScreenOptions: {};
   EventMap: {};

package/src/extractPathFromURL.tsx

@@ -1,27 +1,37 @@
 import escapeStringRegexp from 'escape-string-regexp';
 
-export function extractPathFromURL(prefixes: string[], url: string) {
+import type { LinkingPrefix } from './types';
+
+export function extractPathFromURL(prefixes: LinkingPrefix[], url: string) {
   for (const prefix of prefixes) {
-    const protocol = prefix.match(/^[^:]+:/)?.[0] ?? '';
-    const host = prefix
-      .replace(new RegExp(`^${escapeStringRegexp(protocol)}`), '')
-      .replace(/\/+/g, '/') // Replace multiple slash (//) with single ones
-      .replace(/^\//, ''); // Remove extra leading slash
-
-    const prefixRegex = new RegExp(
-      `^${escapeStringRegexp(protocol)}(/)*${host
-        .split('.')
-        .map((it) => (it === '*' ? '[^/]+' : escapeStringRegexp(it)))
-        .join('\\.')}`
-    );
+    let prefixRegex;
+
+    if (prefix === '*') {
+      prefixRegex = /^(((https?:\/\/)[^/]+)|([^/]+:(\/\/)?))/;
+    } else {
+      const protocol = prefix.match(/^[^:]+:/)?.[0] ?? '';
+      const host = prefix
+        .replace(new RegExp(`^${escapeStringRegexp(protocol)}`), '')
+        .replace(/\/+/g, '/') // Replace multiple slash (//) with single ones
+        .replace(/^\//, ''); // Remove extra leading slash
+
+      prefixRegex = new RegExp(
+        `^${escapeStringRegexp(protocol)}(/)*${host
+          .split('.')
+          .map((it) => (it === '*' ? '[^/]+' : escapeStringRegexp(it)))
+          .join('\\.')}`
+      );
+    }
 
     const [originAndPath, ...searchParams] = url.split('?');
-    const normalizedURL = originAndPath
-      .replace(/\/+/g, '/')
-      .concat(searchParams.length ? `?${searchParams.join('?')}` : '');
 
-    if (prefixRegex.test(normalizedURL)) {
-      return normalizedURL.replace(prefixRegex, '');
+    if (prefixRegex.test(originAndPath)) {
+      const result = originAndPath
+        .replace(prefixRegex, '')
+        .replace(/\/+/g, '/')
+        .concat(searchParams.length ? `?${searchParams.join('?')}` : '');
+
+      return result.startsWith('/') ? result : `/${result}`;
     }
   }
 

package/src/getStateFromHref.tsx

@@ -0,0 +1,46 @@
+import { getStateFromPath, type ParamListBase } from '@react-navigation/core';
+
+import { extractPathFromURL } from './extractPathFromURL';
+import type { LinkingOptions } from './types';
+
+export function getStateFromHref(
+  href: string,
+  options: LinkingOptions<ParamListBase> | undefined
+): ReturnType<typeof getStateFromPath> {
+  const {
+    prefixes,
+    filter,
+    config,
+    getStateFromPath: getStateFromPathHelper = getStateFromPath,
+  } = options || {};
+
+  let path;
+
+  if (href.startsWith('/')) {
+    path = href;
+  } else if (href) {
+    if (filter && !filter(href)) {
+      throw new Error(
+        `Failed to parse href '${href}'. It doesn't match the filter specified in linking config.`
+      );
+    }
+
+    if (prefixes == null || prefixes.length === 0) {
+      throw new Error(
+        `Failed to parse href '${href}'. It doesn't start with '/' and no prefixes are defined in linking config.`
+      );
+    }
+
+    path = extractPathFromURL(prefixes, href);
+  }
+
+  if (path == null) {
+    throw new Error(
+      `Got invalid href '${href}'. It must start with '/' or match one of the prefixes: ${options?.prefixes?.map((prefix) => `'${prefix}'`).join(', ')}.`
+    );
+  }
+
+  const state = getStateFromPathHelper(path, config);
+
+  return state;
+}

package/src/index.tsx

@@ -7,7 +7,6 @@ export { ServerContainer } from './ServerContainer';
 export { DarkTheme } from './theming/DarkTheme';
 export { DefaultTheme } from './theming/DefaultTheme';
 export * from './types';
-export { UnhandledLinkingContext as UNSTABLE_UnhandledLinkingContext } from './UnhandledLinkingContext';
 export { useLinkBuilder } from './useLinkBuilder';
 export { type LinkProps, useLinkProps } from './useLinkProps';
 export { useLinkTo } from './useLinkTo';

package/src/theming/DarkTheme.tsx

@@ -1,7 +1,8 @@
-import type { Theme } from '../types';
+import type { Theme } from '@react-navigation/core';
+
 import { fonts } from './fonts';
 
-export const DarkTheme: Theme = {
+export const DarkTheme = {
   dark: true,
   colors: {
     primary: 'rgb(10, 132, 255)',
@@ -12,4 +13,4 @@ export const DarkTheme: Theme = {
     notification: 'rgb(255, 69, 58)',
   },
   fonts,
-};
+} as const satisfies Theme;

package/src/theming/DefaultTheme.tsx

@@ -1,15 +1,16 @@
-import type { Theme } from '../types';
+import type { Theme } from '@react-navigation/core';
+
 import { fonts } from './fonts';
 
-export const DefaultTheme: Theme = {
+export const DefaultTheme = {
   dark: false,
   colors: {
     primary: 'rgb(0, 122, 255)',
     background: 'rgb(242, 242, 242)',
     card: 'rgb(255, 255, 255)',
     text: 'rgb(28, 28, 30)',
-    border: 'rgb(216, 216, 216)',
+    border: 'rgb(178, 178, 178)',
     notification: 'rgb(255, 59, 48)',
   },
   fonts,
-};
+} as const satisfies Theme;

package/src/theming/fonts.tsx

@@ -1,7 +1,6 @@
+import type { Theme } from '@react-navigation/core';
 import { Platform } from 'react-native';
 
-import type { Theme } from '../types';
-
 const WEB_FONT_STACK =
   'system-ui, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"';
 

package/src/types.tsx

@@ -2,16 +2,23 @@ import type {
   getActionFromState as getActionFromStateDefault,
   getPathFromState as getPathFromStateDefault,
   getStateFromPath as getStateFromPathDefault,
+  InitialState,
+  NavigationState,
   PathConfigMap,
   Route,
 } from '@react-navigation/core';
+import type { ColorValue as ReactNativeColorValue } from 'react-native';
 
-declare global {
-  // eslint-disable-next-line @typescript-eslint/no-namespace
-  namespace ReactNavigation {
-    interface Theme extends NativeTheme {}
-  }
-}
+type ColorValue =
+  | `#${string}`
+  | `rgb(${string})`
+  | `rgba(${string})`
+  | `hsl(${string})`
+  | `hsla(${string})`
+  | `hwb(${string})`
+  | `hwba(${string})`
+  | `var(--${string})`
+  | ReactNativeColorValue;
 
 type FontStyle = {
   fontFamily: string;
@@ -32,12 +39,12 @@ type FontStyle = {
 interface NativeTheme {
   dark: boolean;
   colors: {
-    primary: string;
-    background: string;
-    card: string;
-    text: string;
-    border: string;
-    notification: string;
+    primary: ColorValue;
+    background: ColorValue;
+    card: ColorValue;
+    text: ColorValue;
+    border: ColorValue;
+    notification: ColorValue;
   };
   fonts: {
     regular: FontStyle;
@@ -47,19 +54,34 @@ interface NativeTheme {
   };
 }
 
-export type Theme = NativeTheme;
+declare module '@react-navigation/core' {
+  interface Theme extends NativeTheme {}
+}
 
 export type LocaleDirection = 'ltr' | 'rtl';
 
+export type LinkingPrefix = '*' | (string & {});
+
 export type LinkingOptions<ParamList extends {}> = {
   /**
    * Whether deep link handling should be enabled.
-   * Defaults to true.
+   *
+   * Defaults to `true` when a linking config is specified.
    */
   enabled?: boolean;
   /**
-   * The prefixes are stripped from the URL before parsing them.
-   * Usually they are the `scheme` + `host` (e.g. `myapp://chat?user=jane`)
+   * The prefixes to match to determine whether to handle a URL.
+   *
+   * Supported prefix formats:
+   * - `${scheme}://` - App-specific scheme, e.g. `myapp://`
+   * - `${protocol}://${host}` - Universal links or app links, e.g. `https://example.com`, `https://subdomain.example.com`
+   * - `${protocol}://*.${domain}` - Any subdomain of given domain, e.g. `https://*.example.com`
+   * - `${protocol}://${host}/${path}` - Subpath of given host, e.g. `https://example.com/app`
+   * - `*` - Any domain or subdomain with `http://` and `https://` as well as any app-specific scheme
+   *
+   * The prefix will be stripped from the URL before it's parsed.
+   *
+   * Defaults to `[*]`.
    *
    * This is not supported on Web.
    *
@@ -67,14 +89,14 @@ export type LinkingOptions<ParamList extends {}> = {
    * ```js
    * {
    *    prefixes: [
-   *      "myapp://", // App-specific scheme
-   *      "https://example.com", // Prefix for universal links
-   *      "https://*.example.com" // Prefix which matches any subdomain
+   *      "myapp://",
+   *      "https://example.com",
+   *      "https://*.example.com"
    *    ]
    * }
    * ```
    */
-  prefixes: string[];
+  prefixes?: LinkingPrefix[];
   /**
    * Optional function which takes an incoming URL returns a boolean
    * indicating whether React Navigation should handle it.
@@ -153,9 +175,11 @@ export type LinkingOptions<ParamList extends {}> = {
    *    subscribe: (listener) => {
    *      const onReceiveURL = ({ url }) => listener(url);
    *
-   *      Linking.addEventListener('url', onReceiveURL);
+   *      const subscription = Linking.addEventListener('url', onReceiveURL);
    *
-   *      return () => Linking.removeEventListener('url', onReceiveURL);
+   *      return () => {
+   *        subscription.remove();
+   *      };
    *   }
    * }
    * ```
@@ -186,6 +210,20 @@ export type DocumentTitleOptions = {
   ) => string;
 };
 
+export type Persistor = {
+  /**
+   * Callback to persist the navigation state.
+   */
+  persist(state: NavigationState | undefined): void;
+  /**
+   * Callback to restore the navigation state.
+   * Should return the restored state or a Promise which resolves to the restored state.
+   *
+   * If a Promise is returned, providing a `fallback` component is recommended.
+   */
+  restore(): PromiseLike<InitialState | undefined> | InitialState | undefined;
+};
+
 export type ServerContainerRef = {
   getCurrentOptions(): Record<string, any> | undefined;
 };