@react-navigation/native 8.0.0-alpha.2 → 8.0.0-alpha.21

package/src/native/types.tsx

@@ -1,9 +1,8 @@
 import type { ColorValue } from 'react-native';
 
+import type { FONT_WEIGHTS } from './constants';
 import type { MaterialSymbolName } from './MaterialSymbolData';
 
-type MaterialSymbolVariant = 'outlined' | 'rounded' | 'sharp';
-
 export type MaterialSymbolOptions = {
   /**
    * The name of the Material Symbol to display.
@@ -12,23 +11,151 @@ export type MaterialSymbolOptions = {
   /**
    * The variant of the symbol.
    *
+   * Can be customized using `react-navigation` key in `package.json`:
+   *
+   * ```json
+   * "react-navigation": {
+   *   "material-symbol": {
+   *     "fonts": [
+   *       {
+   *         "variant": "rounded",
+   *         "weight": 300,
+   *       },
+   *     ]
+   *   }
+   * }
+   * ```
+   *
+   * Automatically set if a single variant is available.
+   *
    * @default 'outlined'
    */
-  variant?: MaterialSymbolVariant;
+  variant?: 'outlined' | 'rounded' | 'sharp' | undefined;
+  /**
+   * The weight of the symbol.
+   *
+   * Can be customized using `react-navigation` key in `package.json`:
+   *
+   * ```json
+   * "react-navigation": {
+   *   "material-symbol": {
+   *     "fonts": [
+   *       {
+   *         "variant": "rounded",
+   *         "weight": 300,
+   *       },
+   *     ]
+   *   }
+   * }
+   * ```
+   *
+   * Only numeric weights are supported in the configuration.
+   *
+   * Automatically set if a single weight is available.
+   *
+   * @default 400
+   */
+  weight?:
+    | 'thin'
+    | 'ultralight'
+    | 'light'
+    | 'regular'
+    | 'medium'
+    | 'semibold'
+    | 'bold'
+    | 100
+    | 200
+    | 300
+    | 400
+    | 500
+    | 600
+    | 700
+    | undefined;
   /**
    * The size of the symbol.
    *
    * @default 24
    */
-  size?: number;
+  size?: number | undefined;
   /**
    * The color of the symbol.
    *
    * @default 'black'
    */
-  color?: ColorValue;
+  color?: ColorValue | undefined;
 };
 
+export type SFSymbolScale = 'small' | 'medium' | 'large';
+
+export type SFSymbolMode =
+  | 'monochrome'
+  | 'hierarchical'
+  | 'palette'
+  | 'multicolor';
+
+export type SFSymbolAnimationEffect =
+  | 'bounce'
+  | 'pulse'
+  | 'appear'
+  | 'disappear'
+  | 'variableColor'
+  | 'breathe'
+  | 'wiggle'
+  | 'rotate';
+
+export type SFSymbolAnimationConfig = {
+  /**
+   * The animation effect to apply.
+   */
+  effect: SFSymbolAnimationEffect;
+  /**
+   * Whether the animation repeats continuously.
+   *
+   * @default false
+   */
+  repeating?: boolean | undefined;
+  /**
+   * Number of times to repeat the animation.
+   * Ignored if `repeating` is `true`.
+   */
+  repeatCount?: number | undefined;
+  /**
+   * Speed multiplier for the animation.
+   *
+   * @default 1
+   */
+  speed?: number | undefined;
+  /**
+   * Whether to animate the whole symbol at once or layer by layer.
+   *
+   * @default false
+   */
+  wholeSymbol?: boolean | undefined;
+  /**
+   * Direction of the animation.
+   * Applicable to `bounce` and `wiggle`.
+   */
+  direction?: 'up' | 'down' | undefined;
+  /**
+   * Whether the variable color effect reverses with each cycle.
+   * Only applicable to `variableColor`.
+   *
+   * @default false
+   */
+  reversing?: boolean | undefined;
+  /**
+   * Whether each layer remains changed until the end of the cycle.
+   * Only applicable to `variableColor`.
+   *
+   * @default false
+   */
+  cumulative?: boolean | undefined;
+};
+
+export type SFSymbolAnimation =
+  | SFSymbolAnimationEffect
+  | SFSymbolAnimationConfig;
+
 export type SFSymbolOptions = {
   /**
    * The name of the SF Symbol to display.
@@ -38,10 +165,58 @@ export type SFSymbolOptions = {
    * The size of the symbol.
    * @default 24
    */
-  size?: number;
+  size?: number | undefined;
   /**
    * The color of the symbol.
+   * Used as the tint color in monochrome mode, and as the fallback for
+   * `colors.primary` in hierarchical and palette modes.
+   *
    * @default 'black'
    */
-  color?: ColorValue;
+  color?: ColorValue | undefined;
+  /**
+   * The weight of the symbol.
+   *
+   * @default 'regular'
+   */
+  weight?:
+    | keyof typeof FONT_WEIGHTS
+    | (typeof FONT_WEIGHTS)[keyof typeof FONT_WEIGHTS]
+    | undefined;
+  /**
+   * The scale of the symbol relative to the font size.
+   *
+   * @default 'medium'
+   */
+  scale?: SFSymbolScale | undefined;
+  /**
+   * The rendering mode of the symbol.
+   * - `monochrome`: Single color tint (default).
+   * - `hierarchical`: Derived hierarchy from a single color.
+   * - `palette`: Explicit colors for each layer.
+   * - `multicolor`: Uses the symbol's built-in multicolor scheme.
+   *
+   * @default 'monochrome'
+   */
+  mode?: SFSymbolMode | undefined;
+  /**
+   * The colors for non-monochrome rendering modes.
+   * - `hierarchical`: uses `primary` as the base color.
+   * - `palette`: uses `primary`, `secondary`, and `tertiary` for each layer.
+   * - `multicolor`: ignored.
+   *
+   * Falls back to `color` for `primary` if not specified.
+   */
+  colors?:
+    | {
+        primary?: ColorValue | undefined;
+        secondary?: ColorValue | undefined;
+        tertiary?: ColorValue | undefined;
+      }
+    | undefined;
+  /**
+   * The animation effect to apply to the symbol.
+   * Requires iOS 17+. Ignored on earlier versions.
+   */
+  animation?: SFSymbolAnimation | undefined;
 };

package/src/theming/DarkTheme.tsx

@@ -6,10 +6,10 @@ export const DarkTheme = {
   dark: true,
   colors: {
     primary: 'rgb(10, 132, 255)',
-    background: 'rgb(1, 1, 1)',
-    card: 'rgb(18, 18, 18)',
-    text: 'rgb(229, 229, 231)',
-    border: 'rgb(39, 39, 41)',
+    background: 'rgb(0, 0, 0)',
+    card: 'rgb(28, 28, 30)',
+    text: 'rgb(255, 255, 255)',
+    border: 'rgb(56, 56, 58)',
     notification: 'rgb(255, 69, 58)',
   },
   fonts,

package/src/theming/{DefaultTheme.tsx → LightTheme.tsx}

@@ -2,14 +2,14 @@ import type { Theme } from '@react-navigation/core';
 
 import { fonts } from './fonts';
 
-export const DefaultTheme = {
+export const LightTheme = {
   dark: false,
   colors: {
     primary: 'rgb(0, 122, 255)',
-    background: 'rgb(242, 242, 242)',
+    background: 'rgb(242, 242, 247)',
     card: 'rgb(255, 255, 255)',
-    text: 'rgb(28, 28, 30)',
-    border: 'rgb(178, 178, 178)',
+    text: 'rgb(0, 0, 0)',
+    border: 'rgb(198, 198, 200)',
     notification: 'rgb(255, 59, 48)',
   },
   fonts,

package/src/theming/MaterialTheme.android.tsx

@@ -0,0 +1,30 @@
+import type { Theme } from '@react-navigation/core';
+import { PlatformColor } from 'react-native';
+
+import { fonts } from './fonts';
+
+export const MaterialLightTheme = {
+  dark: false,
+  colors: {
+    primary: PlatformColor('@android:color/system_primary_light'),
+    background: PlatformColor('@android:color/system_surface_container_light'),
+    card: PlatformColor('@android:color/system_background_light'),
+    text: PlatformColor('@android:color/system_on_surface_light'),
+    border: PlatformColor('@android:color/system_outline_variant_light'),
+    notification: PlatformColor('@android:color/system_error_light'),
+  },
+  fonts,
+} as const satisfies Theme;
+
+export const MaterialDarkTheme = {
+  dark: true,
+  colors: {
+    primary: PlatformColor('@android:color/system_primary_dark'),
+    background: PlatformColor('@android:color/system_surface_container_dark'),
+    card: PlatformColor('@android:color/system_background_dark'),
+    text: PlatformColor('@android:color/system_on_surface_dark'),
+    border: PlatformColor('@android:color/system_outline_variant_dark'),
+    notification: PlatformColor('@android:color/system_error_dark'),
+  },
+  fonts,
+} as const satisfies Theme;

package/src/theming/MaterialTheme.tsx

@@ -0,0 +1,19 @@
+import type { Theme } from '@react-navigation/core';
+
+import { fonts } from './fonts';
+
+export const MaterialLightTheme = {
+  dark: false,
+  get colors(): Theme['colors'] {
+    throw new Error('MaterialLightTheme is only supported on Android');
+  },
+  fonts,
+} as const satisfies Theme;
+
+export const MaterialDarkTheme = {
+  dark: true,
+  get colors(): Theme['colors'] {
+    throw new Error('MaterialDarkTheme is only supported on Android');
+  },
+  fonts,
+} as const satisfies Theme;

package/src/types.tsx

@@ -68,7 +68,7 @@ export type LinkingOptions<ParamList extends {}> = {
    *
    * Defaults to `true` when a linking config is specified.
    */
-  enabled?: boolean;
+  enabled?: boolean | undefined;
   /**
    * The prefixes to match to determine whether to handle a URL.
    *
@@ -96,7 +96,7 @@ export type LinkingOptions<ParamList extends {}> = {
    * }
    * ```
    */
-  prefixes?: LinkingPrefix[];
+  prefixes?: LinkingPrefix[] | undefined;
   /**
    * Optional function which takes an incoming URL returns a boolean
    * indicating whether React Navigation should handle it.
@@ -114,7 +114,7 @@ export type LinkingOptions<ParamList extends {}> = {
    * }
    * ```
    */
-  filter?: (url: string) => boolean;
+  filter?: ((url: string) => boolean) | undefined;
   /**
    * Config to fine-tune how to parse the path.
    *
@@ -128,23 +128,25 @@ export type LinkingOptions<ParamList extends {}> = {
    * }
    * ```
    */
-  config?: {
-    /**
-     * 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;
-  };
+  config?:
+    | {
+        /**
+         * 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 | undefined;
+        /**
+         * Path configuration for child screens.
+         */
+        screens: PathConfigMap<ParamList>;
+        /**
+         * Name of the initial route to use for the root navigator.
+         */
+        initialRouteName?: Extract<keyof ParamList, string> | undefined;
+      }
+    | undefined;
   /**
    * Custom function to get the initial URL used for linking.
    * Uses `Linking.getInitialURL()` by default.
@@ -158,11 +160,9 @@ export type LinkingOptions<ParamList extends {}> = {
    * }
    * ```
    */
-  getInitialURL?: () =>
-    | string
-    | null
-    | undefined
-    | Promise<string | null | undefined>;
+  getInitialURL?:
+    | (() => string | null | undefined | Promise<string | null | undefined>)
+    | undefined;
   /**
    * Custom function to get subscribe to URL updates.
    * Uses `Linking.addEventListener('url', callback)` by default.
@@ -184,30 +184,32 @@ export type LinkingOptions<ParamList extends {}> = {
    * }
    * ```
    */
-  subscribe?: (
-    listener: (url: string) => void
-  ) => undefined | void | (() => void);
+  subscribe?:
+    | ((listener: (url: string) => void) => undefined | void | (() => void))
+    | undefined;
   /**
    * Custom function to parse the URL to a valid navigation state (advanced).
    */
-  getStateFromPath?: typeof getStateFromPathDefault;
+  getStateFromPath?: typeof getStateFromPathDefault | undefined;
   /**
    * Custom function to convert the state object to a valid URL (advanced).
    * Only applicable on Web.
    */
-  getPathFromState?: typeof getPathFromStateDefault;
+  getPathFromState?: typeof getPathFromStateDefault | undefined;
   /**
    * Custom function to convert the state object to a valid action (advanced).
    */
-  getActionFromState?: typeof getActionFromStateDefault;
+  getActionFromState?: typeof getActionFromStateDefault | undefined;
 };
 
 export type DocumentTitleOptions = {
-  enabled?: boolean;
-  formatter?: (
-    options: Record<string, any> | undefined,
-    route: Route<string> | undefined
-  ) => string;
+  enabled?: boolean | undefined;
+  formatter?:
+    | ((
+        options: Record<string, any> | undefined,
+        route: Route<string> | undefined
+      ) => string)
+    | undefined;
 };
 
 export type Persistor = {

package/src/useBackButton.tsx

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

package/src/useDocumentTitle.tsx

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

package/src/useLinkBuilder.tsx

@@ -13,17 +13,23 @@ import { getStateFromHref } from './getStateFromHref';
 import { LinkingContext } from './LinkingContext';
 
 type MinimalState = {
-  routes: [{ name: string; params?: object; state?: MinimalState }];
+  routes: [
+    {
+      name: string;
+      params?: object | undefined;
+      state?: MinimalState | undefined;
+    },
+  ];
 };
 
 /**
  * Helper to build a href for a screen based on the linking options.
  */
 export function useBuildHref() {
-  const navigation = React.useContext(NavigationHelpersContext);
-  const route = React.useContext(NavigationRouteContext);
+  const navigation = React.use(NavigationHelpersContext);
+  const route = React.use(NavigationRouteContext);
 
-  const { options } = React.useContext(LinkingContext);
+  const { options } = React.use(LinkingContext);
 
   const focusedRouteState = useStateForPath();
 
@@ -103,7 +109,7 @@ export function useBuildHref() {
  * Helper to build a navigation action from a href based on the linking options.
  */
 export function useBuildAction() {
-  const { options } = React.useContext(LinkingContext);
+  const { options } = React.use(LinkingContext);
 
   const getActionFromStateHelper =
     options?.getActionFromState ?? getActionFromState;

package/src/useLinkProps.tsx

@@ -3,11 +3,8 @@ import {
   type NavigationAction,
   NavigationContainerRefContext,
   NavigationHelpersContext,
-  type NavigatorScreenParams,
-  type ParamListBase,
   type RootParamList,
 } from '@react-navigation/core';
-import type { NavigationState, PartialState } from '@react-navigation/routers';
 import * as React from 'react';
 import { type GestureResponderEvent, Platform } from 'react-native';
 
@@ -32,35 +29,6 @@ export type LinkProps<
       params?: undefined;
     };
 
-const getStateFromParams = (
-  params: NavigatorScreenParams<ParamListBase> | 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 this is fine 🔥
-          state: params.screen
-            ? getStateFromParams(
-                params.params as
-                  | NavigatorScreenParams<ParamListBase>
-                  | undefined
-              )
-            : undefined,
-        },
-      ],
-    };
-  }
-
-  return undefined;
-};
-
 /**
  * Hook to get props for an anchor tag so it can work with in page navigation.
  *
@@ -73,9 +41,9 @@ export function useLinkProps<
   const ParamList extends {} = RootParamList,
   const RouteName extends keyof ParamList = keyof ParamList,
 >({ screen, params, href, action }: LinkProps<ParamList, RouteName>) {
-  const root = React.useContext(NavigationContainerRefContext);
-  const navigation = React.useContext(NavigationHelpersContext);
-  const { options } = React.useContext(LinkingContext);
+  const root = React.use(NavigationContainerRefContext);
+  const navigation = React.use(NavigationHelpersContext);
+  const { options } = React.use(LinkingContext);
 
   const onPress = (
     e?: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
@@ -162,17 +130,16 @@ export function useLinkProps<
   return {
     href:
       href ??
-      (Platform.OS === 'web' && screen != null
+      (Platform.OS === 'web' && typeof screen === 'string'
         ? 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),
+                  params:
+                    typeof params === 'object' && params != null
+                      ? params
+                      : undefined,
                 },
               ],
             },

package/src/useLinkTo.tsx

@@ -9,7 +9,7 @@ import { useBuildAction } from './useLinkBuilder';
  * @returns function that receives the href to navigate to.
  */
 export function useLinkTo() {
-  const navigation = React.useContext(NavigationContainerRefContext);
+  const navigation = React.use(NavigationContainerRefContext);
   const buildAction = useBuildAction();
 
   const linkTo = React.useCallback(