@react-navigation/elements 3.0.0-alpha.4 → 3.0.0-alpha.41

package/lib/typescript/src/useFrameSize.d.ts

@@ -12,6 +12,6 @@ type FrameSizeProviderProps = {
         onLayout: (event: LayoutChangeEvent) => void;
     }) => React.ReactNode;
 };
-export declare function FrameSizeProvider({ initialFrame, render, }: FrameSizeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function FrameSizeProvider({ initialFrame, render, }: FrameSizeProviderProps): React.JSX.Element;
 export {};
 //# sourceMappingURL=useFrameSize.d.ts.map

package/lib/typescript/src/useFrameSize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFrameSize.d.ts","sourceRoot":"","sources":["../../../src/useFrameSize.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,iBAAiB,EAAY,IAAI,EAAE,MAAM,cAAc,CAAC;AAItE,KAAK,KAAK,GAAG;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAgBF,wBAAgB,YAAY,CAAC,CAAC,EAC5B,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,EAC7B,QAAQ,CAAC,EAAE,OAAO,GACjB,CAAC,CAeH;AAED,KAAK,sBAAsB,GAAG;IAC5B,YAAY,EAAE,KAAK,CAAC;IACpB,MAAM,EAAE,CAAC,KAAK,EAAE;QACd,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;KAC9C,KAAK,KAAK,CAAC,SAAS,CAAC;CACvB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,EACZ,MAAM,GACP,EAAE,sBAAsB,2CA4GxB"}
+{"version":3,"file":"useFrameSize.d.ts","sourceRoot":"","sources":["../../../src/useFrameSize.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,iBAAiB,EAAY,IAAI,EAAE,MAAM,cAAc,CAAC;AAMtE,KAAK,KAAK,GAAG;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAiBF,wBAAgB,YAAY,CAAC,CAAC,EAC5B,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,EAC7B,QAAQ,CAAC,EAAE,OAAO,GACjB,CAAC,CAeH;AAED,KAAK,sBAAsB,GAAG;IAC5B,YAAY,EAAE,KAAK,CAAC;IACpB,MAAM,EAAE,CAAC,KAAK,EAAE;QACd,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;KAC9C,KAAK,KAAK,CAAC,SAAS,CAAC;CACvB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,EACZ,MAAM,GACP,EAAE,sBAAsB,qBA4GxB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@react-navigation/elements",
   "description": "UI Components for React Navigation",
-  "version": "3.0.0-alpha.4",
+  "version": "3.0.0-alpha.41",
   "keywords": [
     "react-native",
     "react-navigation",
@@ -22,12 +22,12 @@
   "types": "./lib/typescript/src/index.d.ts",
   "exports": {
     ".": {
-      "source": "./src/index.tsx",
+      "@react-navigation/source": "./src/index.tsx",
       "types": "./lib/typescript/src/index.d.ts",
       "default": "./lib/module/index.js"
     },
     "./internal": {
-      "source": "./src/internal.tsx",
+      "@react-navigation/source": "./src/internal.tsx",
       "types": "./lib/typescript/src/internal.d.ts",
       "default": "./lib/module/internal.js"
     },
@@ -47,32 +47,33 @@
     "clean": "del lib"
   },
   "dependencies": {
-    "color": "^4.2.3",
-    "use-latest-callback": "^0.3.2",
-    "use-sync-external-store": "^1.5.0"
+    "sf-symbols-typescript": "^2.2.0",
+    "use-latest-callback": "^0.3.4",
+    "use-sync-external-store": "^1.6.0"
   },
   "devDependencies": {
-    "@callstack/liquid-glass": "^0.6.0",
-    "@jest/globals": "^30.0.0",
-    "@react-navigation/native": "^8.0.0-alpha.4",
-    "@testing-library/react-native": "^13.2.1",
-    "@types/react": "~19.1.10",
+    "@callstack/liquid-glass": "^0.8.0",
+    "@jest/globals": "^29.7.0",
+    "@react-navigation/native": "^8.0.0-alpha.37",
+    "@testing-library/react-native": "^14.0.0",
+    "@types/react": "~19.2.17",
     "@types/use-sync-external-store": "^1.5.0",
-    "del-cli": "^6.0.0",
-    "react": "19.1.0",
-    "react-native": "0.81.4",
-    "react-native-builder-bob": "^0.40.12",
-    "react-native-screens": "^4.20.0",
-    "react-test-renderer": "19.1.0",
-    "typescript": "^5.9.2"
+    "del-cli": "^7.0.0",
+    "react": "19.2.3",
+    "react-native": "0.85.3",
+    "react-native-builder-bob": "^0.43.0",
+    "react-native-safe-area-context": "~5.7.0",
+    "react-native-screens": "^4.26.2",
+    "test-renderer": "1.2.0",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@callstack/liquid-glass": ">= 0.6.0",
-    "@react-navigation/native": "^8.0.0-alpha.4",
-    "react": ">= 19.0.0",
+    "@react-navigation/native": "^8.0.0-alpha.37",
+    "react": ">= 19.2.0",
     "react-native": "*",
     "react-native-safe-area-context": ">= 5.5.0",
-    "react-native-screens": ">= 4.19.0"
+    "react-native-screens": ">= 4.25.0"
   },
   "react-native-builder-bob": {
     "source": "src",
@@ -92,5 +93,5 @@
       ]
     ]
   },
-  "gitHead": "cd1c673cd6b8f43b992b76e8ed6cf6c5c85bdd6c"
+  "gitHead": "b0135879fbe4aa4a657798845483b7e78c307778"
 }

package/src/ActivityView.native.tsx

@@ -0,0 +1,90 @@
+import { Activity, useEffect, useState } from 'react';
+import {
+  type HostComponent,
+  NativeComponentRegistry,
+  type ViewProps,
+} from 'react-native';
+
+// eslint-disable-next-line import-x/extensions
+import type { Props } from './ActivityView.tsx';
+import { Container } from './Container';
+
+export function ActivityView({
+  mode,
+  visible,
+  delay = 500,
+  style,
+  children,
+}: Props) {
+  const [delayedMode, setDelayedMode] = useState(mode);
+
+  useEffect(() => {
+    if (!delay) {
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      setDelayedMode(mode);
+    }, delay);
+
+    return () => clearTimeout(timer);
+  }, [delay, mode]);
+
+  const display = visible ? 'flex' : 'none';
+  const activityMode =
+    mode !== 'paused' || (delay && delayedMode !== 'paused')
+      ? 'visible'
+      : 'hidden';
+
+  return (
+    <Activity mode={activityMode}>
+      <ActivityContentView style={{ display: 'contents' }}>
+        <Container
+          inert={mode !== 'normal'}
+          style={{
+            ...style,
+            /**
+             * The visibility of the nested view is controlled by `Activity`
+             * It'll be overridden to `display: 'none'` when `mode="hidden"` regardless of what we set
+             * So we set the visibility on another view instead
+             */
+            display,
+          }}
+        >
+          {children}
+        </Container>
+      </ActivityContentView>
+    </Activity>
+  );
+}
+
+const STYLE: Record<string, true | { process?: (arg1: any) => any }> = {
+  display: {
+    /**
+     * React `Activity` sets `display: 'none'` when `mode="hidden"` to unmount effects
+     * But we want to keep the content visible, so we switch it to `display: 'contents'`
+     */
+    process: () => 'contents',
+  },
+};
+
+const VIEW_CONFIG = {
+  uiViewClassName: 'RCTView',
+  validAttributes: {
+    style: STYLE,
+  },
+};
+
+type ActivityContentViewProps = Omit<ViewProps, 'style'> & {
+  style?:
+    | {
+        display?: 'contents' | undefined;
+      }
+    | undefined;
+};
+
+const ActivityContentView: HostComponent<ActivityContentViewProps> =
+  NativeComponentRegistry.get<ActivityContentViewProps>(
+    'ReactNavigationActivityContentView',
+    () => VIEW_CONFIG
+  );

package/src/ActivityView.tsx

@@ -0,0 +1,129 @@
+import { Activity, useCallback, useEffect, useState } from 'react';
+import { Platform, View, type ViewStyle } from 'react-native';
+
+import { Container } from './Container';
+
+export type Props = {
+  /**
+   * Mode of the activity view
+   * - `normal`: The view renders normally
+   * - `inert`: Content is not interactive
+   * - `paused`: Effects are unmounted and content is not interactive
+   */
+  mode: 'normal' | 'inert' | 'paused';
+  /**
+   * Whether the content is visible or not
+   */
+  visible: boolean;
+  /**
+   * Delay before pausing effects.
+   * So pending animations have time to finish.
+   *
+   * Defaults to 500ms.
+   */
+  delay?: number | undefined;
+  /**
+   * The style for the container view
+   */
+  style?: Omit<React.CSSProperties & ViewStyle, 'display'> | undefined;
+  /**
+   * The content of the activity view
+   */
+  children: React.ReactNode;
+};
+
+export function ActivityView({
+  mode,
+  visible,
+  delay = 500,
+  style,
+  children,
+}: Props) {
+  const [delayedMode, setDelayedMode] = useState(mode);
+
+  useEffect(() => {
+    if (!delay) {
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      setDelayedMode(mode);
+    }, delay);
+
+    return () => clearTimeout(timer);
+  }, [delay, mode]);
+
+  const display = visible ? 'flex' : 'none';
+  const activityMode =
+    mode !== 'paused' || (delay && delayedMode !== 'paused')
+      ? 'visible'
+      : 'hidden';
+
+  /**
+   * Activity has 2 modes, visible and hidden - hidden unmounts effects
+   * But what we want is to unmount effects, without hiding content
+   * So we use hidden mode, but unset display: none to make content visible
+   */
+  const onRef = useCallback(
+    (node: HTMLDivElement | View | null) => {
+      if (Platform.OS !== 'web' || !(node && node instanceof HTMLElement)) {
+        return;
+      }
+
+      const observers: MutationObserver[] = [];
+
+      const observe = () => {
+        // Remove previous observers
+        observers.forEach((o) => o.disconnect());
+        observers.length = 0;
+
+        const children = node.childNodes;
+
+        // When the style attribute for children is updated by React
+        // We observe it and update display to make content visible
+        children.forEach((child) => {
+          if (child instanceof HTMLElement) {
+            child.style.display = display;
+
+            const o = new MutationObserver(() => {
+              child.style.display = display;
+            });
+
+            o.observe(child, {
+              attributes: true,
+              attributeFilter: ['style'],
+            });
+
+            observers.push(o);
+          }
+        });
+      };
+
+      observe();
+
+      // React removes refs when `Activity` is hidden
+      // So we render outside of the `Activity` and observer child list
+      const observer = new MutationObserver(observe);
+
+      observer.observe(node, {
+        childList: true,
+      });
+
+      return () => {
+        observer.disconnect();
+        observers.forEach((o) => o.disconnect());
+      };
+    },
+    [display]
+  );
+
+  return (
+    <Container ref={onRef} style={{ display: 'contents' }}>
+      <Activity mode={activityMode}>
+        <Container inert={mode !== 'normal'} style={{ ...style, display }}>
+          {children}
+        </Container>
+      </Activity>
+    </Container>
+  );
+}

package/src/Badge.tsx

@@ -11,7 +11,7 @@ import {
 
 import { Color } from './Color';
 
-type Props = TextProps & {
+type Props = Omit<TextProps, 'style'> & {
   /**
    * Whether the badge is visible
    */
@@ -19,15 +19,15 @@ type Props = TextProps & {
   /**
    * Content of the `Badge`.
    */
-  children?: string | number;
+  children?: string | number | undefined;
   /**
    * Size of the `Badge`.
    */
-  size?: number;
+  size?: number | undefined;
   /**
    * Style object for the tab bar container.
    */
-  style?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
+  style?: Animated.WithAnimatedValue<StyleProp<TextStyle>> | undefined;
 };
 
 const useNativeDriver = Platform.OS !== 'web';
@@ -49,17 +49,19 @@ export function Badge({
       return;
     }
 
-    Animated.timing(opacity, {
+    const animation = Animated.timing(opacity, {
       toValue: visible ? 1 : 0,
       duration: 150,
       useNativeDriver,
-    }).start(({ finished }) => {
+    });
+
+    animation.start(({ finished }) => {
       if (finished && !visible) {
         setRendered(false);
       }
     });
 
-    return () => opacity.stopAnimation();
+    return () => animation.stop();
   }, [opacity, rendered, visible]);
 
   if (!rendered) {
@@ -73,7 +75,7 @@ export function Badge({
   // @ts-expect-error: backgroundColor definitely exists
   const { backgroundColor = colors.notification, ...restStyle } =
     StyleSheet.flatten(style) || {};
-  const textColor = Color(backgroundColor)?.isLight() ? 'black' : 'white';
+  const textColor = Color.foreground(backgroundColor);
 
   const borderRadius = size / 2;
   const fontSize = Math.floor((size * 3) / 4);

package/src/BlurEffectBackground.tsx

@@ -31,7 +31,8 @@ export function BlurEffectBackground({
   children,
   ...rest
 }: Props) {
-  let containerStyle, blurStyle, blurBackground, colorBackground;
+  let blurStyle: (ViewStyle & React.CSSProperties) | undefined;
+  let containerStyle, blurBackground, colorBackground;
 
   if (Platform.OS === 'web' && blurEffect && blurEffect !== 'none') {
     const blurBackgroundColor = getBlurBackgroundColor(blurEffect);
@@ -40,9 +41,8 @@ export function BlurEffectBackground({
       const backdropFilter = `saturate(180%) blur(30px)`;
 
       blurStyle = {
-        // @ts-expect-error backdropFilter is web-only
         backdropFilter,
-        webkitBackdropFilter: backdropFilter,
+        WebkitBackdropFilter: backdropFilter,
       };
 
       blurBackground = (

package/src/Button.tsx

@@ -1,71 +1,156 @@
 import {
   type LinkProps,
+  type ParamListBase,
   type RootParamList,
   useLinkProps,
   useTheme,
 } from '@react-navigation/native';
 import * as React from 'react';
-import { type ColorValue, Platform, StyleSheet } from 'react-native';
+import {
+  ActivityIndicator,
+  type ColorValue,
+  Platform,
+  StyleSheet,
+  View,
+} from 'react-native';
 
 import { Color } from './Color';
+import { PlatformIcon } from './PlatformIcon';
 import {
   PlatformPressable,
   type Props as PlatformPressableProps,
 } from './PlatformPressable';
 import { Text } from './Text';
+import type { Icon } from './types';
 
 type ButtonBaseProps = Omit<PlatformPressableProps, 'children'> & {
-  variant?: 'plain' | 'tinted' | 'filled';
-  color?: ColorValue;
-  children: string | string[];
+  /**
+   * Variant of the button.
+   *
+   * - `plain`: transparent background, colored text
+   * - `tinted`: lightly tinted background, colored text
+   * - `filled`: colored background, contrasting text color
+   *
+   * @default 'tinted'
+   */
+  variant?: 'plain' | 'tinted' | 'filled' | undefined;
+  /**
+   * Custom color for the button.
+   * Changes the text color for `plain` and `tinted` variants,
+   * and background color for `filled` variant.
+   */
+  color?: ColorValue | undefined;
+  /**
+   * Icon to display before the label.
+   *
+   * Supported types:
+   * - image: custom image source
+   * - sfSymbol: SF Symbol icon (iOS only)
+   * - materialSymbol: material symbol icon (Android only)
+   * - React Node: function that returns a React Element
+   */
+  icon?:
+    | Icon
+    | ((props: { color: ColorValue; size: number }) => Icon | React.ReactNode)
+    | undefined;
+  /**
+   * Whether to show a loading indicator instead of the icon.
+   */
+  loading?: boolean | undefined;
+  /**
+   * Label text to display inside the button.
+   */
+  children: string | string[] | React.ReactElement | React.ReactElement[];
 };
 
 type ButtonLinkProps<
   ParamList extends {} = RootParamList,
-  RouteName extends keyof ParamList = keyof ParamList,
-> = LinkProps<ParamList, RouteName> & Omit<ButtonBaseProps, 'onPress'>;
+  RouteName extends Extract<keyof ParamList, string> = Extract<
+    keyof ParamList,
+    string
+  >,
+> = LinkProps<NoInfer<ParamList>, RouteName> & ButtonBaseProps;
 
 const BUTTON_RADIUS = 40;
+const ICON_SIZE = 14;
 
+/**
+ * Component to render a button that navigates to a screen using a path.
+ * Uses an anchor tag on the web.
+ *
+ * @param props.in Name of the current or parent screen whose navigator contains the target screen.
+ * @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 override the in-page navigation. The `href` is still derived from `screen`, so this can be used to render a link while dispatching a different action (e.g. a `replace`).
+ */
 export function Button<
   ParamList extends {} = RootParamList,
-  RouteName extends keyof ParamList = keyof ParamList,
+  RouteName extends Extract<keyof ParamList, string> = Extract<
+    keyof ParamList,
+    string
+  >,
 >(props: ButtonLinkProps<ParamList, RouteName>): React.JSX.Element;
 
+/**
+ * Component to render a button.
+ */
 export function Button(props: ButtonBaseProps): React.JSX.Element;
 
-export function Button<
-  ParamList extends {} = RootParamList,
-  RouteName extends keyof ParamList = keyof ParamList,
->(props: ButtonBaseProps | ButtonLinkProps<ParamList, RouteName>) {
+export function Button(
+  props: ButtonBaseProps | ButtonLinkProps<ParamListBase>
+) {
   if ('screen' in props || 'action' in props) {
-    // @ts-expect-error: This is already type-checked by the prop types
     return <ButtonLink {...props} />;
   } else {
     return <ButtonBase {...props} />;
   }
 }
 
-function ButtonLink<
-  const ParamList extends {} = RootParamList,
-  const RouteName extends keyof ParamList = keyof ParamList,
->({
+function ButtonLink({
+  in: parent,
   screen,
   params,
   action,
   href,
+  onPress,
   ...rest
-}: ButtonLinkProps<ParamList, RouteName>) {
-  // @ts-expect-error: This is already type-checked by the prop types
-  const props = useLinkProps({ screen, params, action, href });
+}: ButtonLinkProps<ParamListBase>) {
+  // @ts-expect-error: destructuring loses the relationship between target props
+  const props = useLinkProps({ in: parent, screen, params, action, href });
+
+  const [isPending, startTransition] = React.useTransition();
+
+  // Avoid flashing the loading indicator when the transition is fast
+  const isPendingDeferred = React.useDeferredValue(isPending);
+
+  return (
+    <ButtonBase
+      {...rest}
+      {...props}
+      loading={
+        typeof rest.loading === 'boolean'
+          ? rest.loading
+          : isPending && isPendingDeferred
+      }
+      onPress={(e) => {
+        onPress?.(e);
 
-  return <ButtonBase {...rest} {...props} />;
+        startTransition(() => {
+          props.onPress(e);
+        });
+      }}
+    />
+  );
 }
 
 function ButtonBase({
   variant = 'tinted',
   color: customColor,
+  icon,
+  loading = false,
   android_ripple,
+  disabled,
   style,
   children,
   ...rest
@@ -90,18 +175,39 @@ function ButtonBase({
       break;
     case 'filled':
       backgroundColor = color;
-      textColor = Color(color)?.isDark()
-        ? 'white'
-        : (Color(color)?.darken(0.71).string() ?? '#fff');
+      textColor = Color.foreground(backgroundColor);
       break;
   }
 
+  if (disabled || loading) {
+    textColor = dark ? 'rgba(235, 235, 245, 0.3)' : 'rgba(60, 60, 67, 0.3)';
+
+    if (variant !== 'plain') {
+      backgroundColor = dark
+        ? 'rgba(118, 118, 128, 0.24)'
+        : 'rgba(118, 118, 128, 0.12)';
+    }
+  }
+
+  const rippleColor =
+    Color(textColor)?.fade(0.88).string() ??
+    (variant === 'filled' || dark
+      ? 'rgba(255, 255, 255, 0.12)'
+      : 'rgba(0, 0, 0, 0.12)');
+
+  const iconNode = loading ? (
+    <ActivityIndicator color={textColor} size={ICON_SIZE} />
+  ) : (
+    renderIcon(icon, textColor, ICON_SIZE)
+  );
+
   return (
     <PlatformPressable
       {...rest}
+      disabled={disabled || loading}
       android_ripple={{
-        radius: BUTTON_RADIUS,
-        color: Color(textColor)?.fade(0.85).string() ?? 'rgba(0, 0, 0, 0.1)',
+        foreground: true,
+        color: rippleColor,
         ...android_ripple,
       }}
       pressOpacity={Platform.OS === 'ios' ? undefined : 1}
@@ -110,19 +216,58 @@ function ButtonBase({
       }
       style={[{ backgroundColor }, styles.button, style]}
     >
-      <Text style={[{ color: textColor }, fonts.regular, styles.text]}>
-        {children}
-      </Text>
+      <View style={styles.content}>
+        {iconNode && <View style={styles.icon}>{iconNode}</View>}
+        <Text style={[{ color: textColor }, fonts.regular, styles.text]}>
+          {children}
+        </Text>
+      </View>
     </PlatformPressable>
   );
 }
 
+function renderIcon(
+  icon: ButtonBaseProps['icon'],
+  color: ColorValue,
+  size: number
+) {
+  if (!icon) {
+    return null;
+  }
+
+  const iconValue = typeof icon === 'function' ? icon({ color, size }) : icon;
+
+  if (React.isValidElement(iconValue)) {
+    return iconValue;
+  }
+
+  if (
+    typeof iconValue === 'object' &&
+    iconValue != null &&
+    'type' in iconValue
+  ) {
+    return <PlatformIcon icon={iconValue} size={size} color={color} />;
+  }
+
+  return null;
+}
+
 const styles = StyleSheet.create({
   button: {
     paddingHorizontal: 24,
     paddingVertical: 10,
     borderRadius: BUTTON_RADIUS,
     borderCurve: 'continuous',
+    overflow: 'hidden',
+  },
+  content: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 8,
+  },
+  icon: {
+    marginLeft: -6,
   },
   text: {
     fontSize: 14,