react-native-screens 4.12.0 → 4.13.0

package/src/components/BottomTabsScreen.tsx

@@ -0,0 +1,291 @@
+'use client';
+
+import React from 'react';
+import BottomTabsScreenNativeComponent, {
+  BlurEffect,
+  type IconType,
+  type NativeProps,
+} from '../fabric/BottomTabsScreenNativeComponent';
+import {
+  type ColorValue,
+  type ImageSourcePropType,
+  type NativeSyntheticEvent,
+  StyleSheet,
+  TextStyle,
+  type ViewProps,
+  findNodeHandle,
+} from 'react-native';
+import { Freeze } from 'react-freeze';
+import { freezeEnabled } from '../core';
+import { featureFlags } from '../flags';
+
+export type EmptyObject = Record<string, never>;
+export type BottomTabsScreenEventHandler<T> = (
+  event: NativeSyntheticEvent<T>,
+) => void;
+
+// iOS-specific: SFSymbol usage
+export interface SFIcon {
+  sfSymbolName: string;
+}
+
+export interface ImageIcon {
+  imageSource: ImageSourcePropType;
+}
+
+// iOS-specific: image as a template usage
+export interface TemplateIcon {
+  templateSource: ImageSourcePropType;
+}
+
+// iOS-specific: SFSymbol, image as a template usage
+export type Icon = SFIcon | ImageIcon | TemplateIcon;
+
+export interface BottomTabsScreenProps {
+  children?: ViewProps['children'];
+  placeholder?: React.ReactNode | undefined;
+
+  // Control
+
+  // Works only in 'controlled' mode. Otherwise this prop indicates only initally selected tab.
+  isFocused?: boolean;
+  tabKey: string;
+
+  // Tab Bar Appearance
+  // tabBarAppearance?: TabBarAppearance; // Does not work due to codegen issue.
+  tabBarBackgroundColor?: ColorValue;
+  tabBarBlurEffect?: BlurEffect; // defaults to 'none'
+
+  tabBarItemTitleFontFamily?: TextStyle['fontFamily'];
+  tabBarItemTitleFontSize?: TextStyle['fontSize'];
+  tabBarItemTitleFontWeight?: TextStyle['fontWeight'];
+  tabBarItemTitleFontStyle?: TextStyle['fontStyle'];
+  tabBarItemTitleFontColor?: TextStyle['color'];
+  tabBarItemTitlePositionAdjustment?: {
+    horizontal?: number;
+    vertical?: number;
+  };
+
+  tabBarItemIconColor?: ColorValue;
+
+  tabBarItemBadgeBackgroundColor?: ColorValue;
+
+  // General
+  title?: string;
+
+  // Android specific
+  iconResourceName?: string;
+
+  icon?: Icon;
+  selectedIcon?: Icon;
+
+  badgeValue?: string;
+
+  specialEffects?: {
+    repeatedTabSelection?: {
+      popToRoot?: boolean;
+      scrollToTop?: boolean;
+    };
+  };
+
+  overrideScrollViewContentInsetAdjustmentBehavior?: boolean; // defaults to true
+
+  // Events
+  onWillAppear?: BottomTabsScreenEventHandler<EmptyObject>;
+  onDidAppear?: BottomTabsScreenEventHandler<EmptyObject>;
+  onWillDisappear?: BottomTabsScreenEventHandler<EmptyObject>;
+  onDidDisappear?: BottomTabsScreenEventHandler<EmptyObject>;
+}
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function BottomTabsScreen(props: BottomTabsScreenProps) {
+  const componentNodeRef = React.useRef<React.Component<NativeProps>>(null);
+  const componentNodeHandle = React.useRef<number>(-1);
+
+  React.useEffect(() => {
+    if (componentNodeRef.current != null) {
+      componentNodeHandle.current =
+        findNodeHandle(componentNodeRef.current) ?? -1;
+    } else {
+      componentNodeHandle.current = -1;
+    }
+  }, []);
+
+  const [nativeViewIsVisible, setNativeViewIsVisible] = React.useState(false);
+
+  const {
+    onWillAppear,
+    onDidAppear,
+    onWillDisappear,
+    onDidDisappear,
+    isFocused = false,
+    icon,
+    selectedIcon,
+    ...rest
+  } = props;
+
+  let shouldFreeze = freezeEnabled();
+
+  if (featureFlags.experiment.controlledBottomTabs) {
+    // If the tabs are JS controlled, we want to freeze only when given view is not focused && it is not currently visible
+    shouldFreeze = shouldFreeze && !nativeViewIsVisible && !isFocused;
+  } else {
+    shouldFreeze = shouldFreeze && !nativeViewIsVisible;
+  }
+
+  const onWillAppearCallback = React.useCallback(
+    (event: NativeSyntheticEvent<EmptyObject>) => {
+      console.log(
+        `TabsScreen [${componentNodeHandle.current}] onWillAppear received`,
+      );
+      setNativeViewIsVisible(true);
+      onWillAppear?.(event);
+    },
+    [onWillAppear],
+  );
+
+  const onDidAppearCallback = React.useCallback(
+    (event: NativeSyntheticEvent<EmptyObject>) => {
+      console.log(
+        `TabsScreen [${componentNodeHandle.current}] onDidAppear received`,
+      );
+      onDidAppear?.(event);
+    },
+    [onDidAppear],
+  );
+
+  const onWillDisappearCallback = React.useCallback(
+    (event: NativeSyntheticEvent<EmptyObject>) => {
+      console.log(
+        `TabsScreen [${componentNodeHandle.current}] onWillDisappear received`,
+      );
+      onWillDisappear?.(event);
+    },
+    [onWillDisappear],
+  );
+
+  const onDidDisappearCallback = React.useCallback(
+    (event: NativeSyntheticEvent<EmptyObject>) => {
+      console.log(
+        `TabsScreen [${componentNodeHandle.current}] onDidDisappear received`,
+      );
+      setNativeViewIsVisible(false);
+      onDidDisappear?.(event);
+    },
+    [onDidDisappear],
+  );
+
+  console.info(
+    `TabsScreen [${componentNodeHandle.current ?? -1}] render; tabKey: ${
+      rest.tabKey
+    } shouldFreeze: ${shouldFreeze}, isFocused: ${isFocused} nativeViewIsVisible: ${nativeViewIsVisible}`,
+  );
+
+  const iconProps = parseIconsToNativeProps(icon, selectedIcon);
+
+  return (
+    <BottomTabsScreenNativeComponent
+      collapsable={false}
+      style={styles.fillParent}
+      onWillAppear={onWillAppearCallback}
+      onDidAppear={onDidAppearCallback}
+      onWillDisappear={onWillDisappearCallback}
+      onDidDisappear={onDidDisappearCallback}
+      isFocused={isFocused}
+      {...iconProps}
+      // @ts-ignore - This is debug only anyway
+      ref={componentNodeRef}
+      {...rest}>
+      <Freeze freeze={shouldFreeze} placeholder={rest.placeholder}>
+        {rest.children}
+      </Freeze>
+    </BottomTabsScreenNativeComponent>
+  );
+}
+
+function parseIconToNativeProps(icon: Icon | undefined): {
+  iconType?: IconType;
+  iconImageSource?: ImageSourcePropType;
+  iconSfSymbolName?: string;
+} {
+  if (!icon) {
+    return {};
+  }
+
+  if ('sfSymbolName' in icon) {
+    // iOS-specific: SFSymbol usage
+    return {
+      iconType: 'sfSymbol',
+      iconSfSymbolName: icon.sfSymbolName,
+    };
+  } else if ('imageSource' in icon) {
+    return {
+      iconType: 'image',
+      iconImageSource: icon.imageSource,
+    };
+  } else if ('templateSource' in icon) {
+    // iOS-specifig: image as a template usage
+    return {
+      iconType: 'template',
+      iconImageSource: icon.templateSource,
+    };
+  } else {
+    // iOS-specific: SFSymbol, image as a template usage
+    throw new Error(
+      '[RNScreens] Incorrect icon format. You must provide sfSymbolName, imageSource or templateSource.',
+    );
+  }
+}
+
+function parseIconsToNativeProps(
+  icon: Icon | undefined,
+  selectedIcon: Icon | undefined,
+): {
+  iconType?: IconType;
+  iconImageSource?: ImageSourcePropType;
+  iconSfSymbolName?: string;
+  selectedIconImageSource?: ImageSourcePropType;
+  selectedIconSfSymbolName?: string;
+} {
+  const { iconImageSource, iconSfSymbolName, iconType } =
+    parseIconToNativeProps(icon);
+  const {
+    iconImageSource: selectedIconImageSource,
+    iconSfSymbolName: selectedIconSfSymbolName,
+    iconType: selectedIconType,
+  } = parseIconToNativeProps(selectedIcon);
+
+  if (
+    iconType !== undefined &&
+    selectedIconType !== undefined &&
+    iconType !== selectedIconType
+  ) {
+    throw new Error('[RNScreens] icon and selectedIcon must be same type.');
+  } else if (iconType === undefined && selectedIconType !== undefined) {
+    // iOS-specific: UIKit requirement
+    throw new Error(
+      '[RNScreens] To use selectedIcon prop, the icon prop must also be provided.',
+    );
+  }
+
+  return {
+    iconType,
+    iconImageSource,
+    iconSfSymbolName,
+    selectedIconImageSource,
+    selectedIconSfSymbolName,
+  };
+}
+
+export default BottomTabsScreen;
+
+const styles = StyleSheet.create({
+  fillParent: {
+    position: 'absolute',
+    flex: 1,
+    width: '100%',
+    height: '100%',
+  },
+});

package/src/components/gamma/ScreenStackHost.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import type { ViewProps } from 'react-native';
+import type { NativeProps } from '../../fabric/gamma/ScreenStackHostNativeComponent';
+import ScreenStackHostNativeComponent from '../../fabric/gamma/ScreenStackHostNativeComponent';
+
+export type ScreenStackNativeProps = NativeProps & {
+  // Overrides
+};
+
+type ScreenStackHostProps = {
+  children?: ViewProps['children'];
+} & ScreenStackNativeProps;
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function ScreenStackHost({ children }: ScreenStackHostProps) {
+  return (
+    <ScreenStackHostNativeComponent style={styles.container}>
+      {children}
+    </ScreenStackHostNativeComponent>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});
+
+export default ScreenStackHost;

package/src/components/gamma/SplitViewHost.tsx

@@ -0,0 +1,84 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import type { ViewProps } from 'react-native';
+import SplitViewHostNativeComponent from '../../fabric/gamma/SplitViewHostNativeComponent';
+import type {
+  NativeProps,
+  SplitViewDisplayMode,
+  SplitViewSplitBehavior,
+} from '../../fabric/gamma/SplitViewHostNativeComponent';
+
+export type SplitViewNativeProps = NativeProps & {
+  // Overrides
+};
+
+type SplitViewHostProps = {
+  children?: ViewProps['children'];
+} & SplitViewNativeProps;
+
+// According to the UIKit documentation: https://developer.apple.com/documentation/uikit/uisplitviewcontroller/displaymode-swift.enum
+// Only specific pairs for displayMode - splitBehavior are valid and others may lead to unexpected results.
+// Therefore, we're adding check on the JS side to return a feedback to the client when that pairing isn't valid.
+// However, we're not blocking these props to be set on the native side, because it doesn't crash, just the result or transitions may not work as expected.
+const displayModeForSplitViewCompatibilityMap: Record<
+  SplitViewSplitBehavior,
+  SplitViewDisplayMode[]
+> = {
+  tile: ['secondaryOnly', 'oneBesideSecondary', 'twoBesideSecondary'],
+  overlay: ['secondaryOnly', 'oneOverSecondary', 'twoOverSecondary'],
+  displace: ['secondaryOnly', 'oneBesideSecondary', 'twoDisplaceSecondary'],
+  automatic: [], // placeholder for satisfying types; we'll handle it specially in logic
+};
+
+const isValidDisplayModeForSplitBehavior = (
+  displayMode: SplitViewDisplayMode,
+  splitBehavior: SplitViewSplitBehavior,
+) => {
+  if (splitBehavior === 'automatic') {
+    // for automatic we cannot easily verify the compatibility, because it depends on the system preference for display mode, therefore we're assuming that 'automatic' has only valid combinations
+    return true;
+  }
+  return displayModeForSplitViewCompatibilityMap[splitBehavior].includes(
+    displayMode,
+  );
+};
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function SplitViewHost(props: SplitViewHostProps) {
+  const { displayMode, splitBehavior } = props;
+
+  React.useEffect(() => {
+    if (displayMode && splitBehavior) {
+      const isValid = isValidDisplayModeForSplitBehavior(
+        displayMode,
+        splitBehavior,
+      );
+      if (!isValid) {
+        const validDisplayModes =
+          displayModeForSplitViewCompatibilityMap[splitBehavior];
+        console.warn(
+          `Invalid display mode "${displayMode}" for split behavior "${splitBehavior}".` +
+            `\nValid modes for "${splitBehavior}" are: ${validDisplayModes.join(
+              ', ',
+            )}.`,
+        );
+      }
+    }
+  }, [displayMode, splitBehavior]);
+
+  return (
+    <SplitViewHostNativeComponent {...props} style={styles.container}>
+      {props.children}
+    </SplitViewHostNativeComponent>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});
+
+export default SplitViewHost;

package/src/components/gamma/SplitViewScreen.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import type { ViewProps } from 'react-native';
+import SplitViewScreenNativeComponent from '../../fabric/gamma/SplitViewScreenNativeComponent';
+import type { NativeProps } from '../../fabric/gamma/SplitViewScreenNativeComponent';
+
+export type SplitViewScreenNativeProps = NativeProps & {
+  // Overrides
+};
+
+type SplitViewScreenProps = {
+  children?: ViewProps['children'];
+} & SplitViewScreenNativeProps;
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function SplitViewScreen({ children }: SplitViewScreenProps) {
+  return (
+    <SplitViewScreenNativeComponent style={StyleSheet.absoluteFill}>
+      {children}
+    </SplitViewScreenNativeComponent>
+  );
+}
+
+export default SplitViewScreen;

package/src/components/gamma/StackScreen.tsx

@@ -0,0 +1,64 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import StackScreenNativeComponent from '../../fabric/gamma/StackScreenNativeComponent';
+import type { NativeSyntheticEvent, ViewProps } from 'react-native';
+import type { NativeProps } from '../../fabric/gamma/StackScreenNativeComponent';
+
+export const StackScreenLifecycleState = {
+  INITIAL: 0,
+  DETACHED: 1,
+  ATTACHED: 2,
+} as const;
+
+export type StackScreenNativeProps = NativeProps & {
+  // Overrides
+  maxLifecycleState: (typeof StackScreenLifecycleState)[keyof typeof StackScreenLifecycleState];
+};
+
+type StackScreenProps = {
+  children?: ViewProps['children'];
+  // Custom events
+  onPop?: (screenKey: string) => void;
+} & StackScreenNativeProps;
+
+/**
+ * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
+ */
+function StackScreen({
+  children,
+  // Control
+  maxLifecycleState,
+  screenKey,
+  // Events
+  onWillAppear,
+  onWillDisappear,
+  onDidAppear,
+  onDidDisappear,
+  // Custom events
+  onPop,
+}: StackScreenProps) {
+  const handleOnDidDisappear = React.useCallback(
+    (e: NativeSyntheticEvent<Record<string, never>>) => {
+      onDidDisappear?.(e);
+      onPop?.(screenKey);
+    },
+    [onDidDisappear, onPop, screenKey],
+  );
+
+  return (
+    <StackScreenNativeComponent
+      style={StyleSheet.absoluteFill}
+      // Control
+      maxLifecycleState={maxLifecycleState}
+      screenKey={screenKey}
+      // Events
+      onWillAppear={onWillAppear}
+      onDidAppear={onDidAppear}
+      onWillDisappear={onWillDisappear}
+      onDidDisappear={handleOnDidDisappear}>
+      {children}
+    </StackScreenNativeComponent>
+  );
+}
+
+export default StackScreen;

package/src/fabric/BottomTabsNativeComponent.ts

@@ -0,0 +1,82 @@
+'use client';
+
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+import type { ColorValue, ViewProps } from 'react-native';
+import type {
+  DirectEventHandler,
+  Float,
+  WithDefault,
+} from 'react-native/Libraries/Types/CodegenTypes';
+
+// TODO: Report issue on RN repo, that nesting color value inside a struct does not work.
+// Generated code is ok, but the value is not passed down correctly - whatever color is set
+// host component receives RGBA(0, 0, 0, 0) anyway.
+// type TabBarAppearance = {
+//   backgroundColor?: ColorValue;
+// };
+
+export type NativeFocusChangeEvent = {
+  tabKey: string;
+};
+
+export type BlurEffect =
+  | 'none'
+  | 'extraLight'
+  | 'light'
+  | 'dark'
+  | 'regular'
+  | 'prominent'
+  | 'systemUltraThinMaterial'
+  | 'systemThinMaterial'
+  | 'systemMaterial'
+  | 'systemThickMaterial'
+  | 'systemChromeMaterial'
+  | 'systemUltraThinMaterialLight'
+  | 'systemThinMaterialLight'
+  | 'systemMaterialLight'
+  | 'systemThickMaterialLight'
+  | 'systemChromeMaterialLight'
+  | 'systemUltraThinMaterialDark'
+  | 'systemThinMaterialDark'
+  | 'systemMaterialDark'
+  | 'systemThickMaterialDark'
+  | 'systemChromeMaterialDark';
+
+export interface NativeProps extends ViewProps {
+  // Events
+  onNativeFocusChange?: DirectEventHandler<NativeFocusChangeEvent>;
+
+  // Appearance
+  // tabBarAppearance?: TabBarAppearance; // Does not work due to codegen issue.
+  tabBarBackgroundColor?: ColorValue;
+  tabBarBlurEffect?: WithDefault<BlurEffect, 'none'>;
+  tabBarTintColor?: ColorValue;
+
+  tabBarItemTitleFontFamily?: string;
+  tabBarItemTitleFontSize?: Float;
+  tabBarItemTitleFontWeight?: string;
+  tabBarItemTitleFontStyle?: string;
+  tabBarItemTitleFontColor?: ColorValue;
+  tabBarItemTitlePositionAdjustment?: {
+    horizontal?: Float;
+    vertical?: Float;
+  };
+
+  tabBarItemIconColor?: ColorValue;
+
+  tabBarItemBadgeBackgroundColor?: ColorValue;
+
+  // Android 
+  tabBarItemTitleFontColorActive?: ColorValue; 
+  tabBarItemIconColorActive?: ColorValue;
+  tabBarItemTitleFontSizeActive?: Float;
+
+  // Control
+
+  // Experimental support
+  controlNavigationStateInJS?: WithDefault<boolean, false>;
+}
+
+export default codegenNativeComponent<NativeProps>('RNSBottomTabs', {
+  interfaceOnly: true,
+});

package/src/fabric/BottomTabsScreenNativeComponent.ts

@@ -0,0 +1,107 @@
+'use client';
+
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+import type { ColorValue, ViewProps } from 'react-native';
+import {
+  DirectEventHandler,
+  Float,
+  Int32,
+  WithDefault,
+} from 'react-native/Libraries/Types/CodegenTypes';
+
+// @ts-ignore: ImageSource type has been recently added: https://github.com/facebook/react-native/pull/51969
+import type { ImageSource } from 'react-native/Libraries/Image/ImageSource';
+
+// iOS-specific: SFSymbol, image as a template usage
+export type IconType = 'image' | 'template' | 'sfSymbol';
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type GenericEmptyEvent = Readonly<{}>;
+
+export type LifecycleStateChangeEvent = Readonly<{
+  previousState: Int32;
+  newState: Int32;
+}>;
+
+export type BlurEffect =
+  | 'none'
+  | 'extraLight'
+  | 'light'
+  | 'dark'
+  | 'regular'
+  | 'prominent'
+  | 'systemUltraThinMaterial'
+  | 'systemThinMaterial'
+  | 'systemMaterial'
+  | 'systemThickMaterial'
+  | 'systemChromeMaterial'
+  | 'systemUltraThinMaterialLight'
+  | 'systemThinMaterialLight'
+  | 'systemMaterialLight'
+  | 'systemThickMaterialLight'
+  | 'systemChromeMaterialLight'
+  | 'systemUltraThinMaterialDark'
+  | 'systemThinMaterialDark'
+  | 'systemMaterialDark'
+  | 'systemThickMaterialDark'
+  | 'systemChromeMaterialDark';
+
+export interface NativeProps extends ViewProps {
+  // Events
+  onLifecycleStateChange?: DirectEventHandler<LifecycleStateChangeEvent>;
+  onWillAppear?: DirectEventHandler<GenericEmptyEvent>;
+  onDidAppear?: DirectEventHandler<GenericEmptyEvent>;
+  onWillDisappear?: DirectEventHandler<GenericEmptyEvent>;
+  onDidDisappear?: DirectEventHandler<GenericEmptyEvent>;
+
+  // Control
+  isFocused?: boolean;
+  tabKey: string;
+
+  // Tab Bar Appearance
+  // tabBarAppearance?: TabBarAppearance; // Does not work due to codegen issue.
+  tabBarBackgroundColor?: ColorValue;
+  tabBarBlurEffect?: WithDefault<BlurEffect, 'none'>;
+
+  tabBarItemTitleFontFamily?: string;
+  tabBarItemTitleFontSize?: Float;
+  tabBarItemTitleFontWeight?: string;
+  tabBarItemTitleFontStyle?: string;
+  tabBarItemTitleFontColor?: ColorValue;
+  tabBarItemTitlePositionAdjustment?: {
+    horizontal?: Float;
+    vertical?: Float;
+  };
+
+  tabBarItemIconColor?: ColorValue;
+
+  tabBarItemBadgeBackgroundColor?: ColorValue;
+
+  // General
+  title?: string | undefined | null;
+
+  // Android-specific image handling
+  iconResourceName?: string;
+
+  // iOS-specific: SFSymbol usage
+  iconType?: WithDefault<IconType, 'sfSymbol'>;
+
+  iconImageSource?: ImageSource;
+  iconSfSymbolName?: string;
+
+  selectedIconImageSource?: ImageSource;
+  selectedIconSfSymbolName?: string;
+
+  badgeValue?: string;
+
+  specialEffects?: {
+    repeatedTabSelection?: {
+      popToRoot?: WithDefault<boolean, true>;
+      scrollToTop?: WithDefault<boolean, true>;
+    };
+  };
+
+  overrideScrollViewContentInsetAdjustmentBehavior?: WithDefault<boolean, true>;
+}
+
+export default codegenNativeComponent<NativeProps>('RNSBottomTabsScreen', {});

package/src/fabric/gamma/ScreenStackHostNativeComponent.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { ViewProps } from 'react-native';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+
+export interface NativeProps extends ViewProps {}
+
+export default codegenNativeComponent<NativeProps>('RNSScreenStackHost', {});