@react-navigation/elements 3.0.0-alpha.5 → 3.0.0-alpha.51

package/src/ActivityView.tsx

@@ -0,0 +1,127 @@
+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 [delayedPaused, setDelayedPaused] = useState(mode === 'paused');
+
+  useEffect(() => {
+    if (!delay) {
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      setDelayedPaused(mode === 'paused');
+    }, delay);
+
+    return () => clearTimeout(timer);
+  }, [delay, mode]);
+
+  const display = visible ? 'flex' : 'none';
+  const activityMode =
+    mode !== 'paused' || (delay && !delayedPaused) ? '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 | React.ComponentRef<typeof 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?: 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) {
@@ -70,10 +72,9 @@ export function Badge({
     }
   }
 
-  // @ts-expect-error: backgroundColor definitely exists
   const { backgroundColor = colors.notification, ...restStyle } =
-    StyleSheet.flatten(style) || {};
-  const textColor = Color(backgroundColor)?.isLight() ? 'black' : 'white';
+    StyleSheet.flatten(style) ?? {};
+  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();
 
-  return <ButtonBase {...rest} {...props} />;
+  // 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);
+
+        startTransition(() => {
+          props.onPress(e);
+        });
+      }}
+    />
+  );
 }
 
 function ButtonBase({
   variant = 'tinted',
   color: customColor,
+  icon,
+  loading = false,
   android_ripple,
+  disabled,
   style,
   children,
   ...rest
@@ -90,18 +175,43 @@ 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}
+      aria-disabled={
+        // Keep the button focusable while loading
+        disabled || loading || undefined
+      }
+      disabled={disabled}
       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 +220,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,