@react-navigation/native 8.0.0-alpha.27 → 8.0.0-alpha.29

package/src/native/types.tsx

@@ -85,76 +85,280 @@ export type MaterialSymbolOptions = {
   color?: ColorValue | undefined;
 };
 
-export type SFSymbolScale = 'small' | 'medium' | 'large';
+type SFSymbolScale = 'small' | 'medium' | 'large';
 
-export type SFSymbolMode =
+type SFSymbolRenderingMode =
   | 'monochrome'
   | 'hierarchical'
   | 'palette'
   | 'multicolor';
 
-export type SFSymbolAnimationEffect =
+export type SFSymbolEffectName =
   | 'bounce'
   | 'pulse'
   | 'appear'
   | 'disappear'
   | 'variableColor'
+  | 'scale'
   | 'breathe'
   | 'wiggle'
-  | 'rotate';
+  | 'rotate'
+  | 'drawOn'
+  | 'drawOff';
 
-export type SFSymbolAnimationConfig = {
+export type SFSymbolContentTransitionEffect = 'automatic' | 'replace';
+
+export type SFSymbolEffectRepeat =
+  | 'continuous'
+  | 'nonRepeating'
+  | {
+      /**
+       * Number of times to repeat the effect.
+       */
+      count?: number | undefined;
+      /**
+       * Delay in seconds between repeated effect cycles.
+       */
+      delay?: number | undefined;
+    };
+
+export type SFSymbolEffectScope = 'byLayer' | 'wholeSymbol' | 'individually';
+
+export type SFSymbolEffectDirection =
+  | 'up'
+  | 'down'
+  | 'left'
+  | 'right'
+  | 'forward'
+  | 'backward'
+  | 'clockwise'
+  | 'counterClockwise';
+
+export type SFSymbolBreatheVariant = 'plain' | 'pulse';
+
+export type SFSymbolDrawDirection = 'reversed' | 'nonReversed';
+
+export type SFSymbolInactiveLayers = 'hide' | 'dim';
+
+type SFSymbolEffectBaseConfig = {
   /**
-   * The animation effect to apply.
+   * Speed multiplier for the effect.
+   *
+   * @default 1
+   */
+  speed?: number | undefined;
+  /**
+   * Repeat behavior for the effect. Use an object for periodic repeats.
    */
-  effect: SFSymbolAnimationEffect;
+  repeat?: SFSymbolEffectRepeat | undefined;
+};
+
+type SFSymbolScopedEffectConfig = SFSymbolEffectBaseConfig & {
   /**
-   * Whether the animation repeats continuously.
+   * Whether to animate the whole symbol at once or by layer.
    *
-   * @default false
+   * @default 'byLayer'
+   */
+  scope?: Extract<SFSymbolEffectScope, 'byLayer' | 'wholeSymbol'> | undefined;
+};
+
+type SFSymbolDirectionalEffectName = 'bounce' | 'appear' | 'disappear';
+
+type SFSymbolDirectionalEffectConfig = SFSymbolScopedEffectConfig & {
+  /**
+   * The symbol effect to apply.
+   */
+  type: SFSymbolDirectionalEffectName;
+  /**
+   * The direction the symbol moves during the effect.
+   */
+  direction?: 'up' | 'down' | undefined;
+};
+
+type SFSymbolScaleEffectConfig = SFSymbolScopedEffectConfig & {
+  /**
+   * The symbol effect to apply.
+   */
+  type: 'scale';
+  /**
+   * Whether the symbol scales up or down.
+   */
+  direction?: 'up' | 'down' | undefined;
+};
+
+type SFSymbolBasicScopedEffectConfig = SFSymbolScopedEffectConfig & {
+  /**
+   * The symbol effect to apply.
+   */
+  type: 'pulse';
+};
+
+type SFSymbolBreatheEffectConfig = SFSymbolScopedEffectConfig & {
+  /**
+   * The symbol effect to apply.
+   */
+  type: 'breathe';
+  /**
+   * The breathe effect variant.
+   */
+  variant?: SFSymbolBreatheVariant | undefined;
+};
+
+type SFSymbolWiggleEffectConfig = SFSymbolScopedEffectConfig & {
+  /**
+   * The symbol effect to apply.
+   */
+  type: 'wiggle';
+  /**
+   * The direction the symbol wiggles toward.
+   */
+  direction?: SFSymbolEffectDirection | undefined;
+  /**
+   * A custom wiggle angle in degrees. Overrides `direction` when set.
+   */
+  angle?: number | undefined;
+};
+
+type SFSymbolRotateEffectConfig = SFSymbolScopedEffectConfig & {
+  /**
+   * The symbol effect to apply.
    */
-  repeating?: boolean | undefined;
+  type: 'rotate';
   /**
-   * Number of times to repeat the animation.
-   * Ignored if `repeating` is `true`.
+   * Which way the symbol rotates.
    */
-  repeatCount?: number | undefined;
+  direction?: 'clockwise' | 'counterClockwise' | undefined;
+};
+
+type SFSymbolDrawEffectConfig = SFSymbolEffectBaseConfig & {
   /**
-   * Speed multiplier for the animation.
+   * The symbol effect to apply.
+   */
+  type: 'drawOn';
+  /**
+   * Whether to animate the whole symbol at once, by layer, or individually.
    *
-   * @default 1
+   * @default 'byLayer'
    */
-  speed?: number | undefined;
+  scope?: SFSymbolEffectScope | undefined;
+};
+
+type SFSymbolDrawOffEffectConfig = SFSymbolEffectBaseConfig & {
+  /**
+   * The symbol effect to apply.
+   */
+  type: 'drawOff';
   /**
-   * Whether to animate the whole symbol at once or layer by layer.
+   * Whether to animate the whole symbol at once, by layer, or individually.
    *
-   * @default false
+   * @default 'byLayer'
    */
-  wholeSymbol?: boolean | undefined;
+  scope?: SFSymbolEffectScope | undefined;
   /**
-   * Direction of the animation.
-   * Applicable to `bounce` and `wiggle`.
+   * Whether the draw-off animation follows the symbol's authored draw
+   * order or plays it in reverse.
+   * - `nonReversed`: follows the symbol's draw order.
+   * - `reversed`: plays it in reverse.
    */
-  direction?: 'up' | 'down' | undefined;
+  drawDirection?: SFSymbolDrawDirection | undefined;
+};
+
+type SFSymbolVariableColorEffectConfig = SFSymbolEffectBaseConfig & {
+  /**
+   * The symbol effect to apply.
+   */
+  type: 'variableColor';
   /**
    * 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`.
+   * Whether layers light up cumulatively and stay active through the
+   * cycle, rather than one at a time.
    *
    * @default false
    */
   cumulative?: boolean | undefined;
+  /**
+   * How layers that aren't currently active are displayed.
+   * - `hide`: inactive layers are invisible.
+   * - `dim`: inactive layers stay visible but faded.
+   *
+   * Defaults to the symbol's standard appearance when unset.
+   */
+  inactiveLayers?: SFSymbolInactiveLayers | undefined;
 };
 
-export type SFSymbolAnimation =
-  | SFSymbolAnimationEffect
-  | SFSymbolAnimationConfig;
+type SFSymbolEffectConfig =
+  | SFSymbolDirectionalEffectConfig
+  | SFSymbolScaleEffectConfig
+  | SFSymbolBasicScopedEffectConfig
+  | SFSymbolBreatheEffectConfig
+  | SFSymbolWiggleEffectConfig
+  | SFSymbolRotateEffectConfig
+  | SFSymbolDrawEffectConfig
+  | SFSymbolDrawOffEffectConfig
+  | SFSymbolVariableColorEffectConfig;
+
+export type SFSymbolContentTransitionScope = 'byLayer' | 'wholeSymbol';
+
+export type SFSymbolReplaceTransitionVariant = 'downUp' | 'upUp' | 'offUp';
+
+type SFSymbolContentTransitionBaseConfig = {
+  /**
+   * Speed multiplier for the transition.
+   *
+   * @default 1
+   */
+  speed?: number | undefined;
+};
+
+type SFSymbolContentTransitionConfig =
+  | (SFSymbolContentTransitionBaseConfig & {
+      /**
+       * The transition effect to apply when the symbol `name` or `variableValue` changes.
+       */
+      type: 'automatic';
+    })
+  | (SFSymbolContentTransitionBaseConfig & {
+      /**
+       * The transition effect to apply when the symbol `name` or `variableValue` changes.
+       */
+      type: 'replace';
+      /**
+       * The direction the outgoing and incoming symbols move.
+       * - `downUp`: the old symbol slides down, the new one comes up.
+       * - `upUp`: both the old and new symbols move up.
+       * - `offUp`: the old symbol fades in place, the new one comes up.
+       */
+      variant?: SFSymbolReplaceTransitionVariant | undefined;
+      /**
+       * Whether to transition the whole symbol at once or by layer.
+       *
+       * @default 'byLayer'
+       */
+      scope?: SFSymbolContentTransitionScope | undefined;
+      /**
+       * Whether to prefer Magic Replace when possible.
+       *
+       * Falls back to regular Replace on iOS 17.
+       *
+       * @default false
+       */
+      magic?: boolean | undefined;
+    });
+
+type SFSymbolEffect = SFSymbolEffectName | SFSymbolEffectConfig;
+
+type SFSymbolContentTransition =
+  | SFSymbolContentTransitionEffect
+  | SFSymbolContentTransitionConfig;
+
+type SFSymbolVariableValueMode = 'automatic' | 'color' | 'draw';
+
+type SFSymbolColorRenderingMode = 'automatic' | 'flat' | 'gradient';
 
 export type SFSymbolOptions = {
   /**
@@ -163,6 +367,7 @@ export type SFSymbolOptions = {
   name: import('sf-symbols-typescript').SFSymbol;
   /**
    * The size of the symbol.
+   *
    * @default 24
    */
   size?: number | undefined;
@@ -184,11 +389,33 @@ export type SFSymbolOptions = {
     | (typeof FONT_WEIGHTS)[keyof typeof FONT_WEIGHTS]
     | undefined;
   /**
-   * The scale of the symbol relative to the font size.
+   * The symbol's scale variant (`small`, `medium`, or `large`).
    *
    * @default 'medium'
    */
   scale?: SFSymbolScale | undefined;
+  /**
+   * The value used to customize variable symbols.
+   * Must be between `0` and `1`.
+   *
+   * Variable symbols (e.g. `wifi`, `speaker.wave.3`) have layers that
+   * activate progressively to represent a magnitude. This controls how
+   * many are shown: `0` renders the fewest, `1` the full symbol.
+   *
+   * Has no effect on symbols that aren't variable.
+   */
+  variableValue?: number | undefined;
+  /**
+   * How the partial state from `variableValue` is rendered.
+   * - `automatic`: the system chooses based on the symbol.
+   * - `color`: fades inactive layers using opacity.
+   * - `draw`: partially draws layers instead of fading them.
+   *
+   * Requires iOS 26+. Ignored on earlier versions.
+   *
+   * @default 'automatic'
+   */
+  variableValueMode?: SFSymbolVariableValueMode | undefined;
   /**
    * The rendering mode of the symbol.
    * - `monochrome`: Single color tint (default).
@@ -198,7 +425,7 @@ export type SFSymbolOptions = {
    *
    * @default 'monochrome'
    */
-  mode?: SFSymbolMode | undefined;
+  renderingMode?: SFSymbolRenderingMode | undefined;
   /**
    * The colors for non-monochrome rendering modes.
    * - `hierarchical`: uses `primary` as the base color.
@@ -215,8 +442,27 @@ export type SFSymbolOptions = {
       }
     | undefined;
   /**
-   * The animation effect to apply to the symbol.
+   * How color is applied across the symbol's layers.
+   * - `automatic`: the system chooses based on the symbol.
+   * - `flat`: a solid color per layer.
+   * - `gradient`: a gradient derived from each layer's color.
+   *
+   * Requires iOS 26+. Ignored on earlier versions.
+   *
+   * @default 'automatic'
+   */
+  colorRenderingMode?: SFSymbolColorRenderingMode | undefined;
+  /**
+   * The effect to apply to the symbol.
+   *
+   * Requires iOS 17+. Effects introduced in later iOS versions are ignored
+   * on earlier versions.
+   */
+  effect?: SFSymbolEffect | undefined;
+  /**
+   * The content transition to apply when the symbol `name` or `variableValue` changes.
+   *
    * Requires iOS 17+. Ignored on earlier versions.
    */
-  animation?: SFSymbolAnimation | undefined;
+  contentTransition?: SFSymbolContentTransition | undefined;
 };

package/src/useLinkBuilder.tsx

@@ -3,6 +3,7 @@ import {
   findFocusedRoute,
   getActionFromState,
   getPathFromState,
+  NavigationContainerRefContext,
   NavigationHelpersContext,
   NavigationRouteContext,
   useStateForPath,
@@ -109,6 +110,7 @@ export function useBuildHref() {
  * Helper to build a navigation action from a href based on the linking options.
  */
 export function useBuildAction() {
+  const navigation = React.use(NavigationContainerRefContext);
   const { options } = React.use(LinkingContext);
 
   const getActionFromStateHelper =
@@ -116,7 +118,7 @@ export function useBuildAction() {
 
   const buildAction = React.useCallback(
     (href: string) => {
-      const state = getStateFromHref(href, options);
+      const state = getStateFromHref(href, options, navigation?.getRootState());
 
       if (state) {
         const action = getActionFromStateHelper(state, options?.config);
@@ -128,7 +130,7 @@ export function useBuildAction() {
         );
       }
     },
-    [options, getActionFromStateHelper]
+    [navigation, options, getActionFromStateHelper]
   );
 
   return buildAction;

package/src/useLinking.native.tsx

@@ -2,6 +2,7 @@ import {
   getActionFromState as getActionFromStateDefault,
   getStateFromPath as getStateFromPathDefault,
   type NavigationContainerRef,
+  type NavigationState,
   type ParamListBase,
   useNavigationIndependentTree,
 } from '@react-navigation/core';
@@ -115,18 +116,22 @@ export function useLinking<ParamList extends ParamListBase>(
   });
 
   const getStateFromURL = React.useCallback(
-    (url: string | null | undefined) => {
+    (url: string | null | undefined, previous: NavigationState | undefined) => {
       if (!url) {
         return undefined;
       }
 
       try {
-        return getStateFromHref(url, {
-          prefixes: prefixesRef.current,
-          filter: filterRef.current,
-          config: configRef.current,
-          getStateFromPath: getStateFromPathRef.current,
-        });
+        return getStateFromHref(
+          url,
+          {
+            prefixes: prefixesRef.current,
+            filter: filterRef.current,
+            config: configRef.current,
+            getStateFromPath: getStateFromPathRef.current,
+          },
+          previous
+        );
       } catch (e) {
         return undefined;
       }
@@ -143,14 +148,14 @@ export function useLinking<ParamList extends ParamListBase>(
       if (url != null) {
         if (typeof url !== 'string') {
           return url.then((url) => {
-            const state = getStateFromURL(url);
+            const state = getStateFromURL(url, undefined);
 
             return state;
           });
         }
       }
 
-      state = getStateFromURL(url);
+      state = getStateFromURL(url, undefined);
     }
 
     const thenable: Thenable<ResultState | undefined> = {
@@ -169,7 +174,9 @@ export function useLinking<ParamList extends ParamListBase>(
       }
 
       const navigation = ref.current;
-      const state = navigation ? getStateFromURL(url) : undefined;
+      const state = navigation
+        ? getStateFromURL(url, navigation.getRootState())
+        : undefined;
 
       if (navigation) {
         REACT_NAVIGATION_DEVTOOLS.get(navigation)?.listeners.forEach(

package/src/useLinking.tsx

@@ -56,6 +56,10 @@ const findMatchingState = <T extends NavigationState>(
   const aRoute = a.routes[a.index];
   const bRoute = b.routes[b.index];
 
+  if (aRoute == null || bRoute == null) {
+    return [a, b];
+  }
+
   const aChildState = aRoute.state as T | undefined;
   const bChildState = bRoute.state as T | undefined;
 
@@ -88,6 +92,11 @@ const isPoppingLastEntry = (
 ): boolean => {
   const currentRoute = current.routes[current.index];
   const recordRoute = record.routes[record.index];
+
+  if (currentRoute == null || recordRoute == null) {
+    return false;
+  }
+
   const currentRouteHistory = currentRoute.history;
   const recordRouteHistory = recordRoute.history ?? [];
 
@@ -106,7 +115,11 @@ const isPoppingLastEntry = (
   const recordRoutes = getRoutesUntilIndex(record);
 
   if (currentRoutes.length === recordRoutes.length + 1) {
-    return recordRoutes.every((route, i) => route.key === currentRoutes[i].key);
+    return recordRoutes.every((route, i) => {
+      const currentRoute = currentRoutes[i];
+
+      return currentRoute != null && route.key === currentRoute.key;
+    });
   }
 
   return false;
@@ -302,7 +315,11 @@ export function useLinking<ParamList extends ParamListBase>(
       let state: ResultState | undefined;
 
       try {
-        state = getStateFromPathRef.current(path, configRef.current);
+        state = getStateFromPathRef.current(
+          path,
+          configRef.current,
+          navigation.getRootState()
+        );
       } catch (e) {
         console.error(e);
 

package/src/useMemoArray.tsx

@@ -0,0 +1,41 @@
+import * as React from 'react';
+
+export function useMemoArray<T>(
+  entries: [item: T, deps: readonly unknown[]][]
+): T[] {
+  const previousRef = React.useRef<
+    | {
+        entries: { item: T; deps: readonly unknown[] }[];
+        items: T[];
+      }
+    | undefined
+  >(undefined);
+
+  const previous = previousRef.current;
+  const next = entries.map(([item, deps], index) => {
+    const previousEntry = previous?.entries[index];
+    const depsEqual =
+      previousEntry &&
+      previousEntry.deps.length === deps.length &&
+      previousEntry.deps.every((it, index) => Object.is(it, deps[index]));
+
+    return depsEqual ? previousEntry : { item, deps };
+  });
+
+  if (
+    previous &&
+    previous.entries.length === next.length &&
+    next.every((entry, index) => entry === previous.entries[index])
+  ) {
+    return previous.items;
+  }
+
+  const items = next.map((entry) => entry.item);
+
+  previousRef.current = {
+    entries: next,
+    items,
+  };
+
+  return items;
+}

package/src/useScrollToTop.tsx

@@ -91,9 +91,10 @@ export function useScrollToTop(ref: React.RefObject<ScrollableWrapper>) {
 
           // In a nested stack navigator, tab press resets the stack to first screen
           // So we should scroll to top only when we are on first screen
+          const firstRoute = navigation.getState().routes[0];
           const isFirst =
             tabNavigations.includes(navigation) ||
-            navigation.getState().routes[0].key === route.key;
+            firstRoute?.key === route.key;
 
           // Run the operation in the next frame so we're sure all listeners have been run
           // This is necessary to know if preventDefault() has been called