@amazon-devices/react-navigation__native 2.0.1758683737

package/src/theming/ThemeProvider.tsx

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+import type { Theme } from '../types';
+import ThemeContext from './ThemeContext';
+
+type Props = {
+  value: Theme;
+  children: React.ReactNode;
+};
+
+export default function ThemeProvider({ value, children }: Props) {
+  return (
+    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+  );
+}

package/src/theming/useTheme.tsx

@@ -0,0 +1,9 @@
+import * as React from 'react';
+
+import ThemeContext from './ThemeContext';
+
+export default function useTheme() {
+  const theme = React.useContext(ThemeContext);
+
+  return theme;
+}

package/src/types.tsx

@@ -0,0 +1,145 @@
+import type {
+  getActionFromState as getActionFromStateDefault,
+  getPathFromState as getPathFromStateDefault,
+  getStateFromPath as getStateFromPathDefault,
+  PathConfigMap,
+  Route,
+} from '@amazon-devices/react-navigation__core';
+
+export type Theme = {
+  dark: boolean;
+  colors: {
+    primary: string;
+    background: string;
+    card: string;
+    text: string;
+    border: string;
+    notification: string;
+  };
+};
+
+export type LinkingOptions<ParamList extends {}> = {
+  /**
+   * Whether deep link handling should be enabled.
+   * Defaults to true.
+   */
+  enabled?: boolean;
+  /**
+   * The prefixes are stripped from the URL before parsing them.
+   * Usually they are the `scheme` + `host` (e.g. `myapp://chat?user=jane`)
+   *
+   * This is not supported on Web.
+   *
+   * @example
+   * ```js
+   * {
+   *    prefixes: [
+   *      "myapp://", // App-specific scheme
+   *      "https://example.com", // Prefix for universal links
+   *      "https://*.example.com" // Prefix which matches any subdomain
+   *    ]
+   * }
+   * ```
+   */
+  prefixes: string[];
+  /**
+   * Optional function which takes an incoming URL returns a boolean
+   * indicating whether React Navigation should handle it.
+   *
+   * This can be used to disable deep linking for specific URLs.
+   * e.g. URLs used for authentication, and not for deep linking to screens.
+   *
+   * This is not supported on Web.
+   *
+   * @example
+   * ```js
+   * {
+   *   // Filter out URLs used by expo-auth-session
+   *   filter: (url) => !url.includes('+expo-auth-session')
+   * }
+   * ```
+   */
+  filter?: (url: string) => boolean;
+  /**
+   * Config to fine-tune how to parse the path.
+   *
+   * @example
+   * ```js
+   * {
+   *   Chat: {
+   *     path: 'chat/:author/:id',
+   *     parse: { id: Number }
+   *   }
+   * }
+   * ```
+   */
+  config?: {
+    initialRouteName?: keyof ParamList;
+    screens: PathConfigMap<ParamList>;
+  };
+  /**
+   * Custom function to get the initial URL used for linking.
+   * Uses `Linking.getInitialURL()` by default.
+   *
+   * This is not supported on Web.
+   *
+   * @example
+   * ```js
+   * {
+   *    getInitialURL () => Linking.getInitialURL(),
+   * }
+   * ```
+   */
+  getInitialURL?: () =>
+    | string
+    | null
+    | undefined
+    | Promise<string | null | undefined>;
+  /**
+   * Custom function to get subscribe to URL updates.
+   * Uses `Linking.addEventListener('url', callback)` by default.
+   *
+   * This is not supported on Web.
+   *
+   * @example
+   * ```js
+   * {
+   *    subscribe: (listener) => {
+   *      const onReceiveURL = ({ url }) => listener(url);
+   *
+   *      Linking.addEventListener('url', onReceiveURL);
+   *
+   *      return () => Linking.removeEventListener('url', onReceiveURL);
+   *   }
+   * }
+   * ```
+   */
+  subscribe?: (
+    listener: (url: string) => void
+  ) => undefined | void | (() => void);
+  /**
+   * Custom function to parse the URL to a valid navigation state (advanced).
+   */
+  getStateFromPath?: typeof getStateFromPathDefault;
+  /**
+   * Custom function to convert the state object to a valid URL (advanced).
+   * Only applicable on Web.
+   */
+  getPathFromState?: typeof getPathFromStateDefault;
+  /**
+   * Custom function to convert the state object to a valid action (advanced).
+   */
+  getActionFromState?: typeof getActionFromStateDefault;
+};
+
+export type DocumentTitleOptions = {
+  enabled?: boolean;
+  formatter?: (
+    options: Record<string, any> | undefined,
+    route: Route<string> | undefined
+  ) => string;
+};
+
+export type ServerContainerRef = {
+  getCurrentOptions(): Record<string, any> | undefined;
+};

package/src/useBackButton.native.tsx

@@ -0,0 +1,33 @@
+import type {
+  NavigationContainerRef,
+  ParamListBase,
+} from '@amazon-devices/react-navigation__core';
+import * as React from 'react';
+import { BackHandler } from 'react-native';
+
+export default function useBackButton(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase>>
+) {
+  React.useEffect(() => {
+    const subscription = BackHandler.addEventListener(
+      'hardwareBackPress',
+      () => {
+        const navigation = ref.current;
+
+        if (navigation == null) {
+          return false;
+        }
+
+        if (navigation.canGoBack()) {
+          navigation.goBack();
+
+          return true;
+        }
+
+        return false;
+      }
+    );
+
+    return () => subscription.remove();
+  }, [ref]);
+}

package/src/useBackButton.tsx

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

package/src/useDocumentTitle.native.tsx

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

package/src/useDocumentTitle.tsx

@@ -0,0 +1,41 @@
+import type {
+  NavigationContainerRef,
+  ParamListBase,
+} from '@amazon-devices/react-navigation__core';
+import * as React from 'react';
+
+import type { DocumentTitleOptions } from './types';
+
+/**
+ * Set the document title for the active screen
+ */
+export default function useDocumentTitle(
+  ref: React.RefObject<NavigationContainerRef<ParamListBase>>,
+  {
+    enabled = true,
+    formatter = (options, route) => options?.title ?? route?.name,
+  }: DocumentTitleOptions = {}
+) {
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const navigation = ref.current;
+
+    if (navigation) {
+      const title = formatter(
+        navigation.getCurrentOptions(),
+        navigation.getCurrentRoute()
+      );
+
+      document.title = title;
+    }
+
+    return navigation?.addListener('options', (e) => {
+      const title = formatter(e.data.options, navigation?.getCurrentRoute());
+
+      document.title = title;
+    });
+  });
+}

package/src/useLinkBuilder.tsx

@@ -0,0 +1,82 @@
+import {
+  getPathFromState,
+  NavigationHelpers,
+  NavigationHelpersContext,
+  NavigationProp,
+  ParamListBase,
+} from '@amazon-devices/react-navigation__core';
+import * as React from 'react';
+
+import LinkingContext from './LinkingContext';
+
+type NavigationObject =
+  | NavigationHelpers<ParamListBase>
+  | NavigationProp<ParamListBase>;
+
+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;
+};
+
+/**
+ * Build destination link for a navigate action.
+ * Useful for showing anchor tags on the web for buttons that perform navigation.
+ */
+export default function useLinkBuilder() {
+  const navigation = React.useContext(NavigationHelpersContext);
+  const linking = React.useContext(LinkingContext);
+
+  const buildLink = React.useCallback(
+    (name: string, params?: object) => {
+      const { options } = linking;
+
+      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 }],
+          };
+
+      const path = options?.getPathFromState
+        ? options.getPathFromState(state, options?.config)
+        : getPathFromState(state, options?.config);
+
+      return path;
+    },
+    [linking, navigation]
+  );
+
+  return buildLink;
+}

package/src/useLinkProps.tsx

@@ -0,0 +1,126 @@
+import {
+  getPathFromState,
+  NavigationAction,
+  NavigationContainerRefContext,
+  NavigationHelpersContext,
+  NavigatorScreenParams,
+  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 LinkingContext from './LinkingContext';
+import useLinkTo, { To } from './useLinkTo';
+
+type Props<ParamList extends ReactNavigation.RootParamList> = {
+  to: To<ParamList>;
+  action?: NavigationAction;
+};
+
+const getStateFromParams = (
+  params: NavigatorScreenParams<ParamListBase, NavigationState> | undefined
+): PartialState<NavigationState> | NavigationState | undefined => {
+  if (params?.state) {
+    return params.state;
+  }
+
+  if (params?.screen) {
+    return {
+      routes: [
+        {
+          name: params.screen,
+          params: params.params,
+          // @ts-expect-error
+          state: params.screen
+            ? getStateFromParams(
+                params.params as
+                  | NavigatorScreenParams<ParamListBase, NavigationState>
+                  | undefined
+              )
+            : undefined,
+        },
+      ],
+    };
+  }
+
+  return undefined;
+};
+
+/**
+ * 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.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>) {
+  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
+  ) => {
+    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();
+      shouldHandle = true;
+    }
+
+    if (shouldHandle) {
+      if (action) {
+        if (navigation) {
+          navigation.dispatch(action);
+        } else if (root) {
+          root.dispatch(action);
+        } else {
+          throw new Error(
+            "Couldn't find a navigation object. Is your component inside NavigationContainer?"
+          );
+        }
+      } else {
+        linkTo(to);
+      }
+    }
+  };
+
+  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,
+    onPress,
+  };
+}

package/src/useLinkTo.tsx

@@ -0,0 +1,71 @@
+import {
+  getActionFromState,
+  getStateFromPath,
+  NavigationContainerRefContext,
+} from '@amazon-devices/react-navigation__core';
+import * as React from 'react';
+
+import LinkingContext from './LinkingContext';
+
+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
+>() {
+  const navigation = React.useContext(NavigationContainerRefContext);
+  const linking = React.useContext(LinkingContext);
+
+  const linkTo = React.useCallback(
+    (to: To<ParamList>) => {
+      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);
+
+      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.');
+      }
+    },
+    [linking, navigation]
+  );
+
+  return linkTo;
+}