@amazon-devices/react-navigation__native 2.0.1758683737

package/src/useLinking.native.tsx

@@ -0,0 +1,215 @@
+import {
+  getActionFromState as getActionFromStateDefault,
+  getStateFromPath as getStateFromPathDefault,
+  NavigationContainerRef,
+  ParamListBase,
+} from '@amazon-devices/react-navigation__core';
+import * as React from 'react';
+import { Linking, Platform } from 'react-native';
+
+import extractPathFromURL from './extractPathFromURL';
+import type { LinkingOptions } from './types';
+
+type ResultState = ReturnType<typeof getStateFromPathDefault>;
+
+type Options = LinkingOptions<ParamListBase> & {
+  independent?: boolean;
+};
+
+let linkingHandlers: Symbol[] = [];
+
+export default function useLinking(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase>>,
+  {
+    independent,
+    enabled = true,
+    prefixes,
+    filter,
+    config,
+    getInitialURL = () =>
+      Promise.race([
+        Linking.getInitialURL(),
+        new Promise<undefined>((resolve) =>
+          // Timeout in 150ms if `getInitialState` doesn't resolve
+          // Workaround for https://github.com/facebook/react-native/issues/25675
+          setTimeout(resolve, 150)
+        ),
+      ]),
+    subscribe = (listener) => {
+      const callback = ({ url }: { url: string }) => listener(url);
+
+      const subscription = Linking.addEventListener('url', callback) as
+        | { remove(): void }
+        | undefined;
+
+      // Storing this in a local variable stops Jest from complaining about import after teardown
+      // @ts-expect-error: removeEventListener is not present in newer RN versions
+      const removeEventListener = Linking.removeEventListener?.bind(Linking);
+
+      return () => {
+        // https://github.com/facebook/react-native/commit/6d1aca806cee86ad76de771ed3a1cc62982ebcd7
+        if (subscription?.remove) {
+          subscription.remove();
+        } else {
+          removeEventListener?.('url', callback);
+        }
+      };
+    },
+    getStateFromPath = getStateFromPathDefault,
+    getActionFromState = getActionFromStateDefault,
+  }: Options
+) {
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'production') {
+      return undefined;
+    }
+
+    if (independent) {
+      return undefined;
+    }
+
+    if (enabled !== false && linkingHandlers.length) {
+      console.error(
+        [
+          'Looks like you have configured linking in multiple places. This is likely an error since deep links should only be handled in one place to avoid conflicts. Make sure that:',
+          "- You don't have multiple NavigationContainers in the app each with 'linking' enabled",
+          '- Only a single instance of the root component is rendered',
+          Platform.OS === 'android'
+            ? "- You have set 'android:launchMode=singleTask' in the '<activity />' section of the 'AndroidManifest.xml' file to avoid launching multiple instances"
+            : '',
+        ]
+          .join('\n')
+          .trim()
+      );
+    }
+
+    const handler = Symbol();
+
+    if (enabled !== false) {
+      linkingHandlers.push(handler);
+    }
+
+    return () => {
+      const index = linkingHandlers.indexOf(handler);
+
+      if (index > -1) {
+        linkingHandlers.splice(index, 1);
+      }
+    };
+  }, [enabled, independent]);
+
+  // We store these options in ref to avoid re-creating getInitialState and re-subscribing listeners
+  // This lets user avoid wrapping the items in `React.useCallback` or `React.useMemo`
+  // Not re-creating `getInitialState` is important coz it makes it easier for the user to use in an effect
+  const enabledRef = React.useRef(enabled);
+  const prefixesRef = React.useRef(prefixes);
+  const filterRef = React.useRef(filter);
+  const configRef = React.useRef(config);
+  const getInitialURLRef = React.useRef(getInitialURL);
+  const getStateFromPathRef = React.useRef(getStateFromPath);
+  const getActionFromStateRef = React.useRef(getActionFromState);
+
+  React.useEffect(() => {
+    enabledRef.current = enabled;
+    prefixesRef.current = prefixes;
+    filterRef.current = filter;
+    configRef.current = config;
+    getInitialURLRef.current = getInitialURL;
+    getStateFromPathRef.current = getStateFromPath;
+    getActionFromStateRef.current = getActionFromState;
+  });
+
+  const getStateFromURL = React.useCallback(
+    (url: string | null | undefined) => {
+      if (!url || (filterRef.current && !filterRef.current(url))) {
+        return undefined;
+      }
+
+      const path = extractPathFromURL(prefixesRef.current, url);
+
+      return path !== undefined
+        ? getStateFromPathRef.current(path, configRef.current)
+        : undefined;
+    },
+    []
+  );
+
+  const getInitialState = React.useCallback(() => {
+    let state: ResultState | undefined;
+
+    if (enabledRef.current) {
+      const url = getInitialURLRef.current();
+
+      if (url != null && typeof url !== 'string') {
+        return url.then((url) => {
+          const state = getStateFromURL(url);
+
+          return state;
+        });
+      }
+
+      state = getStateFromURL(url);
+    }
+
+    const thenable = {
+      then(onfulfilled?: (state: ResultState | undefined) => void) {
+        return Promise.resolve(onfulfilled ? onfulfilled(state) : state);
+      },
+      catch() {
+        return thenable;
+      },
+    };
+
+    return thenable as PromiseLike<ResultState | undefined>;
+  }, [getStateFromURL]);
+
+  React.useEffect(() => {
+    const listener = (url: string) => {
+      if (!enabled) {
+        return;
+      }
+
+      const navigation = ref.current;
+      const state = navigation ? getStateFromURL(url) : undefined;
+
+      if (navigation && state) {
+        // Make sure that the routes in the state exist in the root navigator
+        // Otherwise there's an error in the linking configuration
+        const rootState = navigation.getRootState();
+
+        if (state.routes.some((r) => !rootState?.routeNames.includes(r.name))) {
+          console.warn(
+            "The navigation state parsed from the URL contains routes not present in the root navigator. This usually means that the linking configuration doesn't match the navigation structure. See https://reactnavigation.org/docs/configuring-links for more details on how to specify a linking configuration."
+          );
+          return;
+        }
+
+        const action = getActionFromStateRef.current(state, configRef.current);
+
+        if (action !== undefined) {
+          try {
+            navigation.dispatch(action);
+          } catch (e) {
+            // Ignore any errors from deep linking.
+            // This could happen in case of malformed links, navigation object not being initialized etc.
+            console.warn(
+              `An error occurred when trying to handle the link '${url}': ${
+                typeof e === 'object' && e != null && 'message' in e
+                  ? e.message
+                  : e
+              }`
+            );
+          }
+        } else {
+          navigation.resetRoot(state);
+        }
+      }
+    };
+
+    return subscribe(listener);
+  }, [enabled, getStateFromURL, ref, subscribe]);
+
+  return {
+    getInitialState,
+  };
+}

package/src/useLinking.tsx

@@ -0,0 +1,395 @@
+import {
+  findFocusedRoute,
+  getActionFromState as getActionFromStateDefault,
+  getPathFromState as getPathFromStateDefault,
+  getStateFromPath as getStateFromPathDefault,
+  NavigationContainerRef,
+  NavigationState,
+  ParamListBase,
+} from '@amazon-devices/react-navigation__core';
+import isEqual from 'fast-deep-equal';
+import * as React from 'react';
+
+import createMemoryHistory from './createMemoryHistory';
+import ServerContext from './ServerContext';
+import type { LinkingOptions } from './types';
+
+type ResultState = ReturnType<typeof getStateFromPathDefault>;
+
+/**
+ * Find the matching navigation state that changed between 2 navigation states
+ * e.g.: a -> b -> c -> d and a -> b -> c -> e -> f, if history in b changed, b is the matching state
+ */
+const findMatchingState = <T extends NavigationState>(
+  a: T | undefined,
+  b: T | undefined
+): [T | undefined, T | undefined] => {
+  if (a === undefined || b === undefined || a.key !== b.key) {
+    return [undefined, undefined];
+  }
+
+  // Tab and drawer will have `history` property, but stack will have history in `routes`
+  const aHistoryLength = a.history ? a.history.length : a.routes.length;
+  const bHistoryLength = b.history ? b.history.length : b.routes.length;
+
+  const aRoute = a.routes[a.index];
+  const bRoute = b.routes[b.index];
+
+  const aChildState = aRoute.state as T | undefined;
+  const bChildState = bRoute.state as T | undefined;
+
+  // Stop here if this is the state object that changed:
+  // - history length is different
+  // - focused routes are different
+  // - one of them doesn't have child state
+  // - child state keys are different
+  if (
+    aHistoryLength !== bHistoryLength ||
+    aRoute.key !== bRoute.key ||
+    aChildState === undefined ||
+    bChildState === undefined ||
+    aChildState.key !== bChildState.key
+  ) {
+    return [a, b];
+  }
+
+  return findMatchingState(aChildState, bChildState);
+};
+
+/**
+ * Run async function in series as it's called.
+ */
+export const series = (cb: () => Promise<void>) => {
+  let queue = Promise.resolve();
+  const callback = () => {
+    queue = queue.then(cb);
+  };
+  return callback;
+};
+
+let linkingHandlers: Symbol[] = [];
+
+type Options = LinkingOptions<ParamListBase> & {
+  independent?: boolean;
+};
+
+export default function useLinking(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase>>,
+  {
+    independent,
+    enabled = true,
+    config,
+    getStateFromPath = getStateFromPathDefault,
+    getPathFromState = getPathFromStateDefault,
+    getActionFromState = getActionFromStateDefault,
+  }: Options
+) {
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'production') {
+      return undefined;
+    }
+
+    if (independent) {
+      return undefined;
+    }
+
+    if (enabled !== false && linkingHandlers.length) {
+      console.error(
+        [
+          'Looks like you have configured linking in multiple places. This is likely an error since deep links should only be handled in one place to avoid conflicts. Make sure that:',
+          "- You don't have multiple NavigationContainers in the app each with 'linking' enabled",
+          '- Only a single instance of the root component is rendered',
+        ]
+          .join('\n')
+          .trim()
+      );
+    }
+
+    const handler = Symbol();
+
+    if (enabled !== false) {
+      linkingHandlers.push(handler);
+    }
+
+    return () => {
+      const index = linkingHandlers.indexOf(handler);
+
+      if (index > -1) {
+        linkingHandlers.splice(index, 1);
+      }
+    };
+  }, [enabled, independent]);
+
+  const [history] = React.useState(createMemoryHistory);
+
+  // We store these options in ref to avoid re-creating getInitialState and re-subscribing listeners
+  // This lets user avoid wrapping the items in `React.useCallback` or `React.useMemo`
+  // Not re-creating `getInitialState` is important coz it makes it easier for the user to use in an effect
+  const enabledRef = React.useRef(enabled);
+  const configRef = React.useRef(config);
+  const getStateFromPathRef = React.useRef(getStateFromPath);
+  const getPathFromStateRef = React.useRef(getPathFromState);
+  const getActionFromStateRef = React.useRef(getActionFromState);
+
+  React.useEffect(() => {
+    enabledRef.current = enabled;
+    configRef.current = config;
+    getStateFromPathRef.current = getStateFromPath;
+    getPathFromStateRef.current = getPathFromState;
+    getActionFromStateRef.current = getActionFromState;
+  });
+
+  const server = React.useContext(ServerContext);
+
+  const getInitialState = React.useCallback(() => {
+    let value: ResultState | undefined;
+
+    if (enabledRef.current) {
+      const location =
+        server?.location ??
+        (typeof window !== 'undefined' ? window.location : undefined);
+
+      const path = location ? location.pathname + location.search : undefined;
+
+      if (path) {
+        value = getStateFromPathRef.current(path, configRef.current);
+      }
+    }
+
+    const thenable = {
+      then(onfulfilled?: (state: ResultState | undefined) => void) {
+        return Promise.resolve(onfulfilled ? onfulfilled(value) : value);
+      },
+      catch() {
+        return thenable;
+      },
+    };
+
+    return thenable as PromiseLike<ResultState | undefined>;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const previousIndexRef = React.useRef<number | undefined>(undefined);
+  const previousStateRef = React.useRef<NavigationState | undefined>(undefined);
+  const pendingPopStatePathRef = React.useRef<string | undefined>(undefined);
+
+  React.useEffect(() => {
+    previousIndexRef.current = history.index;
+
+    return history.listen(() => {
+      const navigation = ref.current;
+
+      if (!navigation || !enabled) {
+        return;
+      }
+
+      const path = location.pathname + location.search;
+      const index = history.index;
+
+      const previousIndex = previousIndexRef.current ?? 0;
+
+      previousIndexRef.current = index;
+      pendingPopStatePathRef.current = path;
+
+      // When browser back/forward is clicked, we first need to check if state object for this index exists
+      // If it does we'll reset to that state object
+      // Otherwise, we'll handle it like a regular deep link
+      const record = history.get(index);
+
+      if (record?.path === path && record?.state) {
+        navigation.resetRoot(record.state);
+        return;
+      }
+
+      const state = getStateFromPathRef.current(path, configRef.current);
+
+      // We should only dispatch an action when going forward
+      // Otherwise the action will likely add items to history, which would mess things up
+      if (state) {
+        // Make sure that the routes in the state exist in the root navigator
+        // Otherwise there's an error in the linking configuration
+        const rootState = navigation.getRootState();
+
+        if (state.routes.some((r) => !rootState?.routeNames.includes(r.name))) {
+          console.warn(
+            "The navigation state parsed from the URL contains routes not present in the root navigator. This usually means that the linking configuration doesn't match the navigation structure. See https://reactnavigation.org/docs/configuring-links for more details on how to specify a linking configuration."
+          );
+          return;
+        }
+
+        if (index > previousIndex) {
+          const action = getActionFromStateRef.current(
+            state,
+            configRef.current
+          );
+
+          if (action !== undefined) {
+            try {
+              navigation.dispatch(action);
+            } catch (e) {
+              // Ignore any errors from deep linking.
+              // This could happen in case of malformed links, navigation object not being initialized etc.
+              console.warn(
+                `An error occurred when trying to handle the link '${path}': ${
+                  typeof e === 'object' && e != null && 'message' in e
+                    ? e.message
+                    : e
+                }`
+              );
+            }
+          } else {
+            navigation.resetRoot(state);
+          }
+        } else {
+          navigation.resetRoot(state);
+        }
+      } else {
+        // if current path didn't return any state, we should revert to initial state
+        navigation.resetRoot(state);
+      }
+    });
+  }, [enabled, history, ref]);
+
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const getPathForRoute = (
+      route: ReturnType<typeof findFocusedRoute>,
+      state: NavigationState
+    ): string => {
+      // If the `route` object contains a `path`, use that path as long as `route.name` and `params` still match
+      // This makes sure that we preserve the original URL for wildcard routes
+      if (route?.path) {
+        const stateForPath = getStateFromPathRef.current(
+          route.path,
+          configRef.current
+        );
+
+        if (stateForPath) {
+          const focusedRoute = findFocusedRoute(stateForPath);
+
+          if (
+            focusedRoute &&
+            focusedRoute.name === route.name &&
+            isEqual(focusedRoute.params, route.params)
+          ) {
+            return route.path;
+          }
+        }
+      }
+
+      return getPathFromStateRef.current(state, configRef.current);
+    };
+
+    if (ref.current) {
+      // We need to record the current metadata on the first render if they aren't set
+      // This will allow the initial state to be in the history entry
+      const state = ref.current.getRootState();
+
+      if (state) {
+        const route = findFocusedRoute(state);
+        const path = getPathForRoute(route, state);
+
+        if (previousStateRef.current === undefined) {
+          previousStateRef.current = state;
+        }
+
+        history.replace({ path, state });
+      }
+    }
+
+    const onStateChange = async () => {
+      const navigation = ref.current;
+
+      if (!navigation || !enabled) {
+        return;
+      }
+
+      const previousState = previousStateRef.current;
+      const state = navigation.getRootState();
+
+      // root state may not available, for example when root navigators switch inside the container
+      if (!state) {
+        return;
+      }
+
+      const pendingPath = pendingPopStatePathRef.current;
+      const route = findFocusedRoute(state);
+      const path = getPathForRoute(route, state);
+
+      previousStateRef.current = state;
+      pendingPopStatePathRef.current = undefined;
+
+      // To detect the kind of state change, we need to:
+      // - Find the common focused navigation state in previous and current state
+      // - If only the route keys changed, compare history/routes.length to check if we go back/forward/replace
+      // - If no common focused navigation state found, it's a replace
+      const [previousFocusedState, focusedState] = findMatchingState(
+        previousState,
+        state
+      );
+
+      if (
+        previousFocusedState &&
+        focusedState &&
+        // We should only handle push/pop if path changed from what was in last `popstate`
+        // Otherwise it's likely a change triggered by `popstate`
+        path !== pendingPath
+      ) {
+        const historyDelta =
+          (focusedState.history
+            ? focusedState.history.length
+            : focusedState.routes.length) -
+          (previousFocusedState.history
+            ? previousFocusedState.history.length
+            : previousFocusedState.routes.length);
+
+        if (historyDelta > 0) {
+          // If history length is increased, we should pushState
+          // Note that path might not actually change here, for example, drawer open should pushState
+          history.push({ path, state });
+        } else if (historyDelta < 0) {
+          // If history length is decreased, i.e. entries were removed, we want to go back
+
+          const nextIndex = history.backIndex({ path });
+          const currentIndex = history.index;
+
+          try {
+            if (nextIndex !== -1 && nextIndex < currentIndex) {
+              // An existing entry for this path exists and it's less than current index, go back to that
+              await history.go(nextIndex - currentIndex);
+            } else {
+              // We couldn't find an existing entry to go back to, so we'll go back by the delta
+              // This won't be correct if multiple routes were pushed in one go before
+              // Usually this shouldn't happen and this is a fallback for that
+              await history.go(historyDelta);
+            }
+
+            // Store the updated state as well as fix the path if incorrect
+            history.replace({ path, state });
+          } catch (e) {
+            // The navigation was interrupted
+          }
+        } else {
+          // If history length is unchanged, we want to replaceState
+          history.replace({ path, state });
+        }
+      } else {
+        // If no common navigation state was found, assume it's a replace
+        // This would happen if the user did a reset/conditionally changed navigators
+        history.replace({ path, state });
+      }
+    };
+
+    // We debounce onStateChange coz we don't want multiple state changes to be handled at one time
+    // This could happen since `history.go(n)` is asynchronous
+    // If `pushState` or `replaceState` were called before `history.go(n)` completes, it'll mess stuff up
+    return ref.current?.addListener('state', series(onStateChange));
+  }, [enabled, history, ref]);
+
+  return {
+    getInitialState,
+  };
+}