@amazon-devices/react-navigation__native 7.0.1759135970 → 8.0.9000000000

package/src/createStaticNavigation.tsx

@@ -0,0 +1,109 @@
+import {
+  createComponentForStaticNavigation,
+  createPathConfigForStaticNavigation,
+  type NavigationContainerRef,
+  type ParamListBase,
+  type StaticNavigation,
+} from '@amazon-devices/react-navigation__core';
+import * as React from 'react';
+
+import { NavigationContainer } from './NavigationContainer';
+import type { LinkingOptions } from './types';
+
+type Props = Omit<
+  React.ComponentProps<typeof NavigationContainer>,
+  'linking' | 'children'
+> & {
+  /**
+   * Options for deep linking.
+   */
+  linking?: Omit<LinkingOptions<ParamListBase>, 'config' | 'enabled'> & {
+    /**
+     * Whether deep link handling should be enabled.
+     * Defaults to `true` if any `linking` options are specified, `false` otherwise.
+     *
+     * When 'auto' is specified, all leaf screens will get a autogenerated path.
+     * The generated path will be a kebab-case version of the screen name.
+     * This can be overridden for specific screens by specifying `linking` for the screen.
+     */
+    enabled?: 'auto' | true | false;
+    /**
+     * Additional configuration
+     */
+    config?: Omit<
+      NonNullable<LinkingOptions<ParamListBase>['config']>,
+      'screens'
+    >;
+  };
+};
+
+/**
+ * Create a navigation component from a static navigation config.
+ * The returned component is a wrapper around `NavigationContainer`.
+ *
+ * @param tree Static navigation config.
+ * @returns Navigation component to use in your app.
+ */
+export function createStaticNavigation(tree: StaticNavigation<any, any, any>) {
+  const Component = createComponentForStaticNavigation(tree, 'RootNavigator');
+
+  function Navigation(
+    { linking, ...rest }: Props,
+    ref: React.Ref<NavigationContainerRef<ParamListBase>>
+  ) {
+    const linkingConfig = React.useMemo(() => {
+      const screens = createPathConfigForStaticNavigation(
+        tree,
+        { initialRouteName: linking?.config?.initialRouteName },
+        linking?.enabled === 'auto'
+      );
+
+      if (!screens) return;
+
+      return {
+        path: linking?.config?.path,
+        initialRouteName: linking?.config?.initialRouteName,
+        screens,
+      };
+    }, [
+      linking?.enabled,
+      linking?.config?.path,
+      linking?.config?.initialRouteName,
+    ]);
+
+    const memoizedLinking = React.useMemo(() => {
+      if (!linking) {
+        return undefined;
+      }
+
+      const enabled =
+        typeof linking.enabled === 'boolean'
+          ? linking.enabled
+          : linkingConfig?.screens != null;
+
+      return {
+        ...linking,
+        enabled,
+        config: linkingConfig,
+      };
+    }, [linking, linkingConfig]);
+
+    if (linking?.enabled === true && linkingConfig?.screens == null) {
+      throw new Error(
+        'Linking is enabled but no linking configuration was found for the screens.\n\n' +
+          'To solve this:\n' +
+          "- Specify a 'linking' property for the screens you want to link to.\n" +
+          "- Or set 'linking.enabled' to 'auto' to generate paths automatically.\n\n" +
+          'See usage guide: https://reactnavigation.org/docs/static-configuration#linking'
+      );
+    }
+
+    return (
+      <NavigationContainer {...rest} ref={ref} linking={memoizedLinking}>
+        <Component />
+      </NavigationContainer>
+    );
+  }
+
+  return React.forwardRef(Navigation);
+}

package/src/extractPathFromURL.tsx

@@ -1,6 +1,6 @@
 import escapeStringRegexp from 'escape-string-regexp';
 
-export default function extractPathFromURL(prefixes: string[], url: string) {
+export function extractPathFromURL(prefixes: string[], url: string) {
   for (const prefix of prefixes) {
     const protocol = prefix.match(/^[^:]+:/)?.[0] ?? '';
     const host = prefix
@@ -15,10 +15,10 @@ export default function extractPathFromURL(prefixes: string[], url: string) {
         .join('\\.')}`
     );
 
-    const [originAndPath, searchParams] = url.split('?');
+    const [originAndPath, ...searchParams] = url.split('?');
     const normalizedURL = originAndPath
       .replace(/\/+/g, '/')
-      .concat(searchParams ? `?${searchParams}` : '');
+      .concat(searchParams.length ? `?${searchParams.join('?')}` : '');
 
     if (prefixRegex.test(normalizedURL)) {
       return normalizedURL.replace(prefixRegex, '');

package/src/index.tsx

@@ -1,14 +1,17 @@
-export { default as Link } from './Link';
-export { default as LinkingContext } from './LinkingContext';
-export { default as NavigationContainer } from './NavigationContainer';
-export { default as ServerContainer } from './ServerContainer';
-export { default as DarkTheme } from './theming/DarkTheme';
-export { default as DefaultTheme } from './theming/DefaultTheme';
-export { default as ThemeProvider } from './theming/ThemeProvider';
-export { default as useTheme } from './theming/useTheme';
+export { createStaticNavigation } from './createStaticNavigation';
+export { Link } from './Link';
+export { LinkingContext } from './LinkingContext';
+export { LocaleDirContext } from './LocaleDirContext';
+export { NavigationContainer } from './NavigationContainer';
+export { ServerContainer } from './ServerContainer';
+export { DarkTheme } from './theming/DarkTheme';
+export { DefaultTheme } from './theming/DefaultTheme';
 export * from './types';
-export { default as useLinkBuilder } from './useLinkBuilder';
-export { default as useLinkProps } from './useLinkProps';
-export { default as useLinkTo } from './useLinkTo';
-export { default as useScrollToTop } from './useScrollToTop';
+export { UnhandledLinkingContext as UNSTABLE_UnhandledLinkingContext } from './UnhandledLinkingContext';
+export { useLinkBuilder } from './useLinkBuilder';
+export { type LinkProps, useLinkProps } from './useLinkProps';
+export { useLinkTo } from './useLinkTo';
+export { useLocale } from './useLocale';
+export { useRoutePath } from './useRoutePath';
+export { useScrollToTop } from './useScrollToTop';
 export * from '@amazon-devices/react-navigation__core';

package/src/theming/DarkTheme.tsx

@@ -1,6 +1,7 @@
 import type { Theme } from '../types';
+import { fonts } from './fonts';
 
-const DarkTheme: Theme = {
+export const DarkTheme: Theme = {
   dark: true,
   colors: {
     primary: 'rgb(10, 132, 255)',
@@ -10,6 +11,5 @@ const DarkTheme: Theme = {
     border: 'rgb(39, 39, 41)',
     notification: 'rgb(255, 69, 58)',
   },
+  fonts,
 };
-
-export default DarkTheme;

package/src/theming/DefaultTheme.tsx

@@ -1,6 +1,7 @@
 import type { Theme } from '../types';
+import { fonts } from './fonts';
 
-const DefaultTheme: Theme = {
+export const DefaultTheme: Theme = {
   dark: false,
   colors: {
     primary: 'rgb(0, 122, 255)',
@@ -10,6 +11,5 @@ const DefaultTheme: Theme = {
     border: 'rgb(216, 216, 216)',
     notification: 'rgb(255, 59, 48)',
   },
+  fonts,
 };
-
-export default DefaultTheme;

package/src/theming/fonts.tsx

@@ -0,0 +1,63 @@
+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"';
+
+export const fonts = Platform.select({
+  web: {
+    regular: {
+      fontFamily: WEB_FONT_STACK,
+      fontWeight: '400',
+    },
+    medium: {
+      fontFamily: WEB_FONT_STACK,
+      fontWeight: '500',
+    },
+    bold: {
+      fontFamily: WEB_FONT_STACK,
+      fontWeight: '600',
+    },
+    heavy: {
+      fontFamily: WEB_FONT_STACK,
+      fontWeight: '700',
+    },
+  },
+  ios: {
+    regular: {
+      fontFamily: 'System',
+      fontWeight: '400',
+    },
+    medium: {
+      fontFamily: 'System',
+      fontWeight: '500',
+    },
+    bold: {
+      fontFamily: 'System',
+      fontWeight: '600',
+    },
+    heavy: {
+      fontFamily: 'System',
+      fontWeight: '700',
+    },
+  },
+  default: {
+    regular: {
+      fontFamily: 'sans-serif',
+      fontWeight: 'normal',
+    },
+    medium: {
+      fontFamily: 'sans-serif-medium',
+      fontWeight: 'normal',
+    },
+    bold: {
+      fontFamily: 'sans-serif',
+      fontWeight: '600',
+    },
+    heavy: {
+      fontFamily: 'sans-serif',
+      fontWeight: '700',
+    },
+  },
+} as const satisfies Record<string, Theme['fonts']>);

package/src/types.tsx

@@ -6,7 +6,30 @@ import type {
   Route,
 } from '@amazon-devices/react-navigation__core';
 
-export type Theme = {
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace ReactNavigation {
+    interface Theme extends NativeTheme {}
+  }
+}
+
+type FontStyle = {
+  fontFamily: string;
+  fontWeight:
+    | 'normal'
+    | 'bold'
+    | '100'
+    | '200'
+    | '300'
+    | '400'
+    | '500'
+    | '600'
+    | '700'
+    | '800'
+    | '900';
+};
+
+interface NativeTheme {
   dark: boolean;
   colors: {
     primary: string;
@@ -16,7 +39,17 @@ export type Theme = {
     border: string;
     notification: string;
   };
-};
+  fonts: {
+    regular: FontStyle;
+    medium: FontStyle;
+    bold: FontStyle;
+    heavy: FontStyle;
+  };
+}
+
+export type Theme = NativeTheme;
+
+export type LocaleDirection = 'ltr' | 'rtl';
 
 export type LinkingOptions<ParamList extends {}> = {
   /**
@@ -74,8 +107,21 @@ export type LinkingOptions<ParamList extends {}> = {
    * ```
    */
   config?: {
-    initialRouteName?: keyof ParamList;
+    /**
+     * Path string to match against for the whole navigation tree.
+     * It's not possible to specify params here since this doesn't belong to a screen.
+     * This is useful when the whole app is under a specific path.
+     * e.g. all of the screens are under `/admin` in `https://example.com/admin`
+     */
+    path?: string;
+    /**
+     * Path configuration for child screens.
+     */
     screens: PathConfigMap<ParamList>;
+    /**
+     * Name of the initial route to use for the root navigator.
+     */
+    initialRouteName?: keyof ParamList;
   };
   /**
    * Custom function to get the initial URL used for linking.

package/src/useBackButton.native.tsx

@@ -5,8 +5,8 @@ import type {
 import * as React from 'react';
 import { BackHandler } from 'react-native';
 
-export default function useBackButton(
-  ref: React.RefObject<NavigationContainerRef<ParamListBase>>
+export function useBackButton(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase> | null>
 ) {
   React.useEffect(() => {
     const subscription = BackHandler.addEventListener(

package/src/useBackButton.tsx

@@ -3,8 +3,8 @@ import type {
   ParamListBase,
 } from '@amazon-devices/react-navigation__core';
 
-export default function useBackButton(
-  _: React.RefObject<NavigationContainerRef<ParamListBase>>
+export function useBackButton(
+  _: React.RefObject<NavigationContainerRef<ParamListBase> | null>
 ) {
   // No-op
   // BackHandler is not available on web

package/src/useDocumentTitle.native.tsx

@@ -1,3 +1,3 @@
-export default function useDocumentTitle() {
-  // Noop for React Native
+export function useDocumentTitle() {
+  // Noop for native platforms
 }

package/src/useDocumentTitle.tsx

@@ -9,8 +9,8 @@ import type { DocumentTitleOptions } from './types';
 /**
  * Set the document title for the active screen
  */
-export default function useDocumentTitle(
-  ref: React.RefObject<NavigationContainerRef<ParamListBase>>,
+export function useDocumentTitle(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase> | null>,
   {
     enabled = true,
     formatter = (options, route) => options?.title ?? route?.name,

package/src/useLinkBuilder.tsx

@@ -1,82 +1,127 @@
 import {
+  CommonActions,
+  findFocusedRoute,
+  getActionFromState,
   getPathFromState,
-  NavigationHelpers,
+  getStateFromPath,
   NavigationHelpersContext,
-  NavigationProp,
-  ParamListBase,
+  NavigationRouteContext,
+  useStateForPath,
 } from '@amazon-devices/react-navigation__core';
 import * as React from 'react';
 
-import LinkingContext from './LinkingContext';
-
-type NavigationObject =
-  | NavigationHelpers<ParamListBase>
-  | NavigationProp<ParamListBase>;
+import { LinkingContext } from './LinkingContext';
 
 type MinimalState = {
-  index: number;
-  routes: { name: string; params?: object; state?: MinimalState }[];
-};
-
-const getRootStateForNavigate = (
-  navigation: NavigationObject,
-  state: MinimalState
-): MinimalState => {
-  const parent = navigation.getParent();
-
-  if (parent) {
-    const parentState = parent.getState();
-
-    return getRootStateForNavigate(parent, {
-      index: 0,
-      routes: [
-        {
-          ...parentState.routes[parentState.index],
-          state: state,
-        },
-      ],
-    });
-  }
-
-  return state;
+  routes: [{ name: string; params?: object; state?: MinimalState }];
 };
 
 /**
- * Build destination link for a navigate action.
- * Useful for showing anchor tags on the web for buttons that perform navigation.
+ * Helpers to build href or action based on the linking options.
+ *
+ * @returns `buildHref` to build an `href` for screen and `buildAction` to build an action from an `href`.
  */
-export default function useLinkBuilder() {
+export function useLinkBuilder() {
   const navigation = React.useContext(NavigationHelpersContext);
-  const linking = React.useContext(LinkingContext);
+  const route = React.useContext(NavigationRouteContext);
 
-  const buildLink = React.useCallback(
-    (name: string, params?: object) => {
-      const { options } = linking;
+  const { options } = React.useContext(LinkingContext);
+
+  const focusedRouteState = useStateForPath();
 
+  const getPathFromStateHelper = options?.getPathFromState ?? getPathFromState;
+  const getStateFromPathHelper = options?.getStateFromPath ?? getStateFromPath;
+  const getActionFromStateHelper =
+    options?.getActionFromState ?? getActionFromState;
+
+  const buildHref = React.useCallback(
+    (name: string, params?: object) => {
       if (options?.enabled === false) {
         return undefined;
       }
 
-      const state = navigation
-        ? getRootStateForNavigate(navigation, {
-            index: 0,
-            routes: [{ name, params }],
-          })
-        : // If we couldn't find a navigation object in context, we're at root
-          // So we'll construct a basic state object to use
-          {
-            index: 0,
-            routes: [{ name, params }],
+      // Check that we're inside:
+      // - navigator's context
+      // - route context of the navigator (could be a screen, tab, etc.)
+      // - route matches the state for path (from the screen's context)
+      // This ensures that we're inside a screen
+      const isScreen =
+        navigation && route?.key && focusedRouteState
+          ? route.key === findFocusedRoute(focusedRouteState)?.key &&
+            navigation.getState().routes.some((r) => r.key === route.key)
+          : false;
+
+      const stateForRoute: MinimalState = {
+        routes: [{ name, params }],
+      };
+
+      const constructState = (
+        state: MinimalState | undefined
+      ): MinimalState => {
+        if (state) {
+          const route = state.routes[0];
+
+          // If we're inside a screen and at the innermost route
+          // We need to replace the state with the provided one
+          // This assumes that we're navigating to a sibling route
+          if (isScreen && !route.state) {
+            return stateForRoute;
+          }
+
+          // Otherwise, dive into the nested state of the route
+          return {
+            routes: [
+              {
+                ...route,
+                state: constructState(route.state),
+              },
+            ],
           };
+        }
+
+        // Once there is no more nested state, we're at the innermost route
+        // We can add a state based on provided parameters
+        // This assumes that we're navigating to a child of this route
+        // In this case, the helper is used in a navigator for its routes
+        return stateForRoute;
+      };
 
-      const path = options?.getPathFromState
-        ? options.getPathFromState(state, options?.config)
-        : getPathFromState(state, options?.config);
+      const state = constructState(focusedRouteState);
+      const path = getPathFromStateHelper(state, options?.config);
 
       return path;
     },
-    [linking, navigation]
+    [
+      options?.enabled,
+      options?.config,
+      route?.key,
+      navigation,
+      focusedRouteState,
+      getPathFromStateHelper,
+    ]
+  );
+
+  const buildAction = React.useCallback(
+    (href: string) => {
+      if (!href.startsWith('/')) {
+        throw new Error(`The href must start with '/' (${href}).`);
+      }
+
+      const state = getStateFromPathHelper(href, options?.config);
+
+      if (state) {
+        const action = getActionFromStateHelper(state, options?.config);
+
+        return action ?? CommonActions.reset(state);
+      } else {
+        throw new Error('Failed to parse the href to a navigation state.');
+      }
+    },
+    [options?.config, getStateFromPathHelper, getActionFromStateHelper]
   );
 
-  return buildLink;
+  return {
+    buildHref,
+    buildAction,
+  };
 }