@amazon-devices/react-navigation__native 7.0.1759135970 → 8.0.9000000000

package/src/useLinkProps.tsx

@@ -1,25 +1,38 @@
 import {
   getPathFromState,
-  NavigationAction,
+  type NavigationAction,
   NavigationContainerRefContext,
   NavigationHelpersContext,
-  NavigatorScreenParams,
-  ParamListBase,
+  type NavigatorScreenParams,
+  type ParamListBase,
 } from '@amazon-devices/react-navigation__core';
 import type { NavigationState, PartialState } from '@amazon-devices/react-navigation__routers';
 import * as React from 'react';
-import { GestureResponderEvent, Platform } from 'react-native';
+import { type GestureResponderEvent, Platform } from 'react-native';
 
-import LinkingContext from './LinkingContext';
-import useLinkTo, { To } from './useLinkTo';
+import { LinkingContext } from './LinkingContext';
 
-type Props<ParamList extends ReactNavigation.RootParamList> = {
-  to: To<ParamList>;
-  action?: NavigationAction;
-};
+export type LinkProps<
+  ParamList extends ReactNavigation.RootParamList,
+  RouteName extends keyof ParamList = keyof ParamList,
+> =
+  | ({
+      href?: string;
+      action?: NavigationAction;
+    } & {
+      [Screen in keyof ParamList]: undefined extends ParamList[Screen]
+        ? { screen: Screen; params?: ParamList[Screen] }
+        : { screen: Screen; params: ParamList[Screen] };
+    }[RouteName])
+  | {
+      href?: string;
+      action: NavigationAction;
+      screen?: undefined;
+      params?: undefined;
+    };
 
 const getStateFromParams = (
-  params: NavigatorScreenParams<ParamListBase, NavigationState> | undefined
+  params: NavigatorScreenParams<ParamListBase> | undefined
 ): PartialState<NavigationState> | NavigationState | undefined => {
   if (params?.state) {
     return params.state;
@@ -31,11 +44,11 @@ const getStateFromParams = (
         {
           name: params.screen,
           params: params.params,
-          // @ts-expect-error
+          // @ts-expect-error this is fine 🔥
           state: params.screen
             ? getStateFromParams(
                 params.params as
-                  | NavigatorScreenParams<ParamListBase, NavigationState>
+                  | NavigatorScreenParams<ParamListBase>
                   | undefined
               )
             : undefined,
@@ -50,16 +63,20 @@ const getStateFromParams = (
 /**
  * Hook to get props for an anchor tag so it can work with in page navigation.
  *
- * @param props.to Absolute path to screen (e.g. `/feeds/hot`).
+ * @param props.screen Name of the screen to navigate to (e.g. `'Feeds'`).
+ * @param props.params Params to pass to the screen to navigate to (e.g. `{ sort: 'hot' }`).
+ * @param props.href Optional absolute path to use for the href (e.g. `/feeds/hot`).
  * @param props.action Optional action to use for in-page navigation. By default, the path is parsed to an action based on linking config.
  */
-export default function useLinkProps<
-  ParamList extends ReactNavigation.RootParamList
->({ to, action }: Props<ParamList>) {
+export function useLinkProps<ParamList extends ReactNavigation.RootParamList>({
+  screen,
+  params,
+  href,
+  action,
+}: LinkProps<ParamList>) {
   const root = React.useContext(NavigationContainerRefContext);
   const navigation = React.useContext(NavigationHelpersContext);
   const { options } = React.useContext(LinkingContext);
-  const linkTo = useLinkTo<ParamList>();
 
   const onPress = (
     e?: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
@@ -67,18 +84,30 @@ export default function useLinkProps<
     let shouldHandle = false;
 
     if (Platform.OS !== 'web' || !e) {
-      shouldHandle = e ? !e.defaultPrevented : true;
-    } else if (
-      !e.defaultPrevented && // onPress prevented default
-      // @ts-expect-error: these properties exist on web, but not in React Native
-      !(e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) && // ignore clicks with modifier keys
-      // @ts-expect-error: these properties exist on web, but not in React Native
-      (e.button == null || e.button === 0) && // ignore everything but left clicks
-      // @ts-expect-error: these properties exist on web, but not in React Native
-      [undefined, null, '', 'self'].includes(e.currentTarget?.target) // let browser handle "target=_blank" etc.
-    ) {
-      e.preventDefault();
+      e?.preventDefault?.();
       shouldHandle = true;
+    } else {
+      // ignore clicks with modifier keys
+      const hasModifierKey =
+        ('metaKey' in e && e.metaKey) ||
+        ('altKey' in e && e.altKey) ||
+        ('ctrlKey' in e && e.ctrlKey) ||
+        ('shiftKey' in e && e.shiftKey);
+
+      // only handle left clicks
+      const isLeftClick =
+        'button' in e ? e.button == null || e.button === 0 : true;
+
+      // let browser handle "target=_blank" etc.
+      const isSelfTarget =
+        e.currentTarget && 'target' in e.currentTarget
+          ? [undefined, null, '', 'self'].includes(e.currentTarget.target)
+          : true;
+
+      if (!hasModifierKey && isLeftClick && isSelfTarget) {
+        e.preventDefault?.();
+        shouldHandle = true;
+      }
     }
 
     if (shouldHandle) {
@@ -93,34 +122,35 @@ export default function useLinkProps<
           );
         }
       } else {
-        linkTo(to);
+        // @ts-expect-error This is already type-checked by the prop types
+        navigation?.navigate(screen, params);
       }
     }
   };
 
   const getPathFromStateHelper = options?.getPathFromState ?? getPathFromState;
 
-  const href =
-    typeof to === 'string'
-      ? to
-      : getPathFromStateHelper(
-          {
-            routes: [
-              {
-                name: to.screen,
-                // @ts-expect-error
-                params: to.params,
-                // @ts-expect-error
-                state: getStateFromParams(to.params),
-              },
-            ],
-          },
-          options?.config
-        );
-
   return {
-    href,
-    accessibilityRole: 'link' as const,
+    href:
+      href ??
+      (Platform.OS === 'web' && screen != null
+        ? getPathFromStateHelper(
+            {
+              routes: [
+                {
+                  // @ts-expect-error this is fine 🔥
+                  name: screen,
+                  // @ts-expect-error this is fine 🔥
+                  params: params,
+                  // @ts-expect-error this is fine 🔥
+                  state: getStateFromParams(params),
+                },
+              ],
+            },
+            options?.config
+          )
+        : undefined),
+    role: 'link' as const,
     onPress,
   };
 }

package/src/useLinkTo.tsx

@@ -1,70 +1,30 @@
-import {
-  getActionFromState,
-  getStateFromPath,
-  NavigationContainerRefContext,
-} from '@amazon-devices/react-navigation__core';
+import { NavigationContainerRefContext } from '@amazon-devices/react-navigation__core';
 import * as React from 'react';
 
-import LinkingContext from './LinkingContext';
+import { useLinkBuilder } from './useLinkBuilder';
 
-export type To<
-  ParamList extends ReactNavigation.RootParamList = ReactNavigation.RootParamList,
-  RouteName extends keyof ParamList = keyof ParamList
-> =
-  | string
-  | (undefined extends ParamList[RouteName]
-      ? {
-          screen: Extract<RouteName, string>;
-          params?: ParamList[RouteName];
-        }
-      : {
-          screen: Extract<RouteName, string>;
-          params: ParamList[RouteName];
-        });
-
-export default function useLinkTo<
-  ParamList extends ReactNavigation.RootParamList
->() {
+/**
+ * Helper to navigate to a screen using a href based on the linking options.
+ *
+ * @returns function that receives the href to navigate to.
+ */
+export function useLinkTo() {
   const navigation = React.useContext(NavigationContainerRefContext);
-  const linking = React.useContext(LinkingContext);
+  const { buildAction } = useLinkBuilder();
 
   const linkTo = React.useCallback(
-    (to: To<ParamList>) => {
+    (href: string) => {
       if (navigation === undefined) {
         throw new Error(
           "Couldn't find a navigation object. Is your component inside NavigationContainer?"
         );
       }
 
-      if (typeof to !== 'string') {
-        // @ts-expect-error: This is fine
-        navigation.navigate(to.screen, to.params);
-        return;
-      }
-
-      if (!to.startsWith('/')) {
-        throw new Error(`The path must start with '/' (${to}).`);
-      }
-
-      const { options } = linking;
-
-      const state = options?.getStateFromPath
-        ? options.getStateFromPath(to, options.config)
-        : getStateFromPath(to, options?.config);
+      const action = buildAction(href);
 
-      if (state) {
-        const action = getActionFromState(state, options?.config);
-
-        if (action !== undefined) {
-          navigation.dispatch(action);
-        } else {
-          navigation.reset(state);
-        }
-      } else {
-        throw new Error('Failed to parse the path to a navigation state.');
-      }
+      navigation.dispatch(action);
     },
-    [linking, navigation]
+    [buildAction, navigation]
   );
 
   return linkTo;

package/src/useLinking.native.tsx

@@ -1,27 +1,25 @@
 import {
   getActionFromState as getActionFromStateDefault,
   getStateFromPath as getStateFromPathDefault,
-  NavigationContainerRef,
-  ParamListBase,
+  type NavigationContainerRef,
+  type ParamListBase,
+  useNavigationIndependentTree,
 } from '@amazon-devices/react-navigation__core';
 import * as React from 'react';
 import { Linking, Platform } from 'react-native';
 
-import extractPathFromURL from './extractPathFromURL';
+import { extractPathFromURL } from './extractPathFromURL';
 import type { LinkingOptions } from './types';
 
 type ResultState = ReturnType<typeof getStateFromPathDefault>;
 
-type Options = LinkingOptions<ParamListBase> & {
-  independent?: boolean;
-};
+type Options = LinkingOptions<ParamListBase>;
 
-let linkingHandlers: Symbol[] = [];
+const linkingHandlers: symbol[] = [];
 
-export default function useLinking(
-  ref: React.RefObject<NavigationContainerRef<ParamListBase>>,
+export function useLinking(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase> | null>,
   {
-    independent,
     enabled = true,
     prefixes,
     filter,
@@ -29,11 +27,11 @@ export default function useLinking(
     getInitialURL = () =>
       Promise.race([
         Linking.getInitialURL(),
-        new Promise<undefined>((resolve) =>
+        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)
-        ),
+          setTimeout(resolve, 150);
+        }),
       ]),
     subscribe = (listener) => {
       const callback = ({ url }: { url: string }) => listener(url);
@@ -57,8 +55,11 @@ export default function useLinking(
     },
     getStateFromPath = getStateFromPathDefault,
     getActionFromState = getActionFromStateDefault,
-  }: Options
+  }: Options,
+  onUnhandledLinking: (lastUnhandledLining: string | undefined) => void
 ) {
+  const independent = useNavigationIndependentTree();
+
   React.useEffect(() => {
     if (process.env.NODE_ENV === 'production') {
       return undefined;
@@ -140,12 +141,21 @@ export default function useLinking(
     if (enabledRef.current) {
       const url = getInitialURLRef.current();
 
-      if (url != null && typeof url !== 'string') {
-        return url.then((url) => {
-          const state = getStateFromURL(url);
+      if (url != null) {
+        if (typeof url !== 'string') {
+          return url.then((url) => {
+            const state = getStateFromURL(url);
+
+            if (typeof url === 'string') {
+              // If the link were handled, it gets cleared in NavigationContainer
+              onUnhandledLinking(extractPathFromURL(prefixes, url));
+            }
 
-          return state;
-        });
+            return state;
+          });
+        } else {
+          onUnhandledLinking(extractPathFromURL(prefixes, url));
+        }
       }
 
       state = getStateFromURL(url);
@@ -161,7 +171,7 @@ export default function useLinking(
     };
 
     return thenable as PromiseLike<ResultState | undefined>;
-  }, [getStateFromURL]);
+  }, [getStateFromURL, onUnhandledLinking, prefixes]);
 
   React.useEffect(() => {
     const listener = (url: string) => {
@@ -173,16 +183,8 @@ export default function useLinking(
       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;
-        }
+        // If the link were handled, it gets cleared in NavigationContainer
+        onUnhandledLinking(extractPathFromURL(prefixes, url));
 
         const action = getActionFromStateRef.current(state, configRef.current);
 
@@ -207,7 +209,7 @@ export default function useLinking(
     };
 
     return subscribe(listener);
-  }, [enabled, getStateFromURL, ref, subscribe]);
+  }, [enabled, getStateFromURL, onUnhandledLinking, prefixes, ref, subscribe]);
 
   return {
     getInitialState,

package/src/useLinking.tsx

@@ -3,15 +3,16 @@ import {
   getActionFromState as getActionFromStateDefault,
   getPathFromState as getPathFromStateDefault,
   getStateFromPath as getStateFromPathDefault,
-  NavigationContainerRef,
-  NavigationState,
-  ParamListBase,
+  type NavigationContainerRef,
+  type NavigationState,
+  type ParamListBase,
+  useNavigationIndependentTree,
 } 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 { createMemoryHistory } from './createMemoryHistory';
+import { ServerContext } from './ServerContext';
 import type { LinkingOptions } from './types';
 
 type ResultState = ReturnType<typeof getStateFromPathDefault>;
@@ -62,28 +63,29 @@ const findMatchingState = <T extends NavigationState>(
 export const series = (cb: () => Promise<void>) => {
   let queue = Promise.resolve();
   const callback = () => {
+    // eslint-disable-next-line promise/no-callback-in-promise
     queue = queue.then(cb);
   };
   return callback;
 };
 
-let linkingHandlers: Symbol[] = [];
+const linkingHandlers: symbol[] = [];
 
-type Options = LinkingOptions<ParamListBase> & {
-  independent?: boolean;
-};
+type Options = LinkingOptions<ParamListBase>;
 
-export default function useLinking(
-  ref: React.RefObject<NavigationContainerRef<ParamListBase>>,
+export function useLinking(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase> | null>,
   {
-    independent,
     enabled = true,
     config,
     getStateFromPath = getStateFromPathDefault,
     getPathFromState = getPathFromStateDefault,
     getActionFromState = getActionFromStateDefault,
-  }: Options
+  }: Options,
+  onUnhandledLinking: (lastUnhandledLining: string | undefined) => void
 ) {
+  const independent = useNavigationIndependentTree();
+
   React.useEffect(() => {
     if (process.env.NODE_ENV === 'production') {
       return undefined;
@@ -139,6 +141,17 @@ export default function useLinking(
     getActionFromStateRef.current = getActionFromState;
   });
 
+  const validateRoutesNotExistInRootState = React.useCallback(
+    (state: ResultState) => {
+      const navigation = ref.current;
+      const rootState = navigation?.getRootState();
+      // Make sure that the routes in the state exist in the root navigator
+      // Otherwise there's an error in the linking configuration
+      return state?.routes.some((r) => !rootState?.routeNames.includes(r.name));
+    },
+    [ref]
+  );
+
   const server = React.useContext(ServerContext);
 
   const getInitialState = React.useCallback(() => {
@@ -154,6 +167,9 @@ export default function useLinking(
       if (path) {
         value = getStateFromPathRef.current(path, configRef.current);
       }
+
+      // If the link were handled, it gets cleared in NavigationContainer
+      onUnhandledLinking(path);
     }
 
     const thenable = {
@@ -183,6 +199,8 @@ export default function useLinking(
         return;
       }
 
+      const { location } = window;
+
       const path = location.pathname + location.search;
       const index = history.index;
 
@@ -206,14 +224,11 @@ export default function useLinking(
       // 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) {
+        // If the link were handled, it gets cleared in NavigationContainer
+        onUnhandledLinking(path);
         // 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."
-          );
+        if (validateRoutesNotExistInRootState(state)) {
           return;
         }
 
@@ -248,7 +263,13 @@ export default function useLinking(
         navigation.resetRoot(state);
       }
     });
-  }, [enabled, history, ref]);
+  }, [
+    enabled,
+    history,
+    onUnhandledLinking,
+    ref,
+    validateRoutesNotExistInRootState,
+  ]);
 
   React.useEffect(() => {
     if (!enabled) {
@@ -259,6 +280,8 @@ export default function useLinking(
       route: ReturnType<typeof findFocusedRoute>,
       state: NavigationState
     ): string => {
+      let path;
+
       // 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) {
@@ -275,12 +298,31 @@ export default function useLinking(
             focusedRoute.name === route.name &&
             isEqual(focusedRoute.params, route.params)
           ) {
-            return route.path;
+            path = route.path;
           }
         }
       }
 
-      return getPathFromStateRef.current(state, configRef.current);
+      if (path == null) {
+        path = getPathFromStateRef.current(state, configRef.current);
+      }
+
+      const previousRoute = previousStateRef.current
+        ? findFocusedRoute(previousStateRef.current)
+        : undefined;
+
+      // Preserve the hash if the route didn't change
+      if (
+        previousRoute &&
+        route &&
+        'key' in previousRoute &&
+        'key' in route &&
+        previousRoute.key === route.key
+      ) {
+        path = path + location.hash;
+      }
+
+      return path;
     };
 
     if (ref.current) {
@@ -357,7 +399,12 @@ export default function useLinking(
           const currentIndex = history.index;
 
           try {
-            if (nextIndex !== -1 && nextIndex < currentIndex) {
+            if (
+              nextIndex !== -1 &&
+              nextIndex < currentIndex &&
+              // We should only go back if the entry exists and it's less than current index
+              history.get(nextIndex)
+            ) {
               // An existing entry for this path exists and it's less than current index, go back to that
               await history.go(nextIndex - currentIndex);
             } else {

package/src/useLocale.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+import { LocaleDirContext } from './LocaleDirContext';
+
+/**
+ * Hook to access the text direction specified in the `NavigationContainer`.
+ */
+export function useLocale() {
+  const direction = React.useContext(LocaleDirContext);
+
+  if (direction === undefined) {
+    throw new Error(
+      "Couldn't determine the text direction. Is your component inside NavigationContainer?"
+    );
+  }
+
+  return { direction };
+}

package/src/useRoutePath.tsx

@@ -0,0 +1,34 @@
+import { getPathFromState, useStateForPath } from '@amazon-devices/react-navigation__core';
+import * as React from 'react';
+
+import { LinkingContext } from './LinkingContext';
+
+/**
+ * Hook to get the path for the current route based on linking options.
+ *
+ * @returns Path for the current route.
+ */
+export function useRoutePath() {
+  const { options } = React.useContext(LinkingContext);
+  const state = useStateForPath();
+
+  if (state === undefined) {
+    throw new Error(
+      "Couldn't find a state for the route object. Is your component inside a screen in a navigator?"
+    );
+  }
+
+  const getPathFromStateHelper = options?.getPathFromState ?? getPathFromState;
+
+  const path = React.useMemo(() => {
+    if (options?.enabled === false) {
+      return undefined;
+    }
+
+    const path = getPathFromStateHelper(state, options?.config);
+
+    return path;
+  }, [options?.enabled, options?.config, state, getPathFromStateHelper]);
+
+  return path;
+}