react-native-tab-view 4.2.2 → 5.0.0-alpha.1

package/src/TabView.tsx

@@ -1,7 +1,6 @@
 import * as React from 'react';
 import {
   I18nManager,
-  type LayoutChangeEvent,
   Platform,
   type StyleProp,
   StyleSheet,
@@ -13,35 +12,131 @@ import { Pager } from './Pager';
 import { SceneView } from './SceneView';
 import { TabBar } from './TabBar';
 import type {
-  Layout,
+  AdapterCommonProps,
+  AdapterProps,
+  EventEmitterProps,
   LocaleDirection,
   NavigationState,
-  PagerProps,
   Route,
   SceneRendererProps,
   TabDescriptor,
 } from './types';
 
-export type Props<T extends Route> = Omit<PagerProps, 'layoutDirection'> & {
+export type Props<T extends Route> = AdapterCommonProps & {
+  /**
+   * Callback which is called when the index of the active tab changes.
+   * Must update the `navigationState.index` prop to the new index.
+   *
+   * Example:
+   * ```js
+   * onIndexChange={(index) => setState({ ...state, index })}
+   * ```
+   */
   onIndexChange: (index: number) => void;
+  /**
+   * Callback which is called when the tab navigation animation ends.
+   * Useful for side effects that should run after the tab change animation.
+   *
+   * Unlike `onIndexChange`, this is called regardless of whether the index changed or not.
+   */
   onTabSelect?: (props: { index: number }) => void;
+  /**
+   * State for the tab view containing the current index and routes.
+   *
+   * Example:
+   * ```js
+   * {
+   *   index: 0,
+   *   routes: [
+   *     { key: 'first' },
+   *     { key: 'second' },
+   *   ],
+   * }
+   * ```
+   */
   navigationState: NavigationState<T>;
+  /**
+   * Callback which returns a custom placeholder element.
+   * The placeholder is shown when a scene is not yet loaded when `lazy` is enabled.
+   */
   renderLazyPlaceholder?: (props: { route: T }) => React.ReactNode;
+  /**
+   * Callback which returns a custom tab bar element to display.
+   */
   renderTabBar?: (
-    props: SceneRendererProps & {
-      navigationState: NavigationState<T>;
-      options: Record<string, TabDescriptor<T>> | undefined;
-    }
+    props: SceneRendererProps &
+      EventEmitterProps & {
+        navigationState: NavigationState<T>;
+        options: Record<string, TabDescriptor<T>> | undefined;
+      }
   ) => React.ReactNode;
+  /**
+   * Callback which returns a custom adapter to use for the tab view.
+   * Adapters are responsible for handling gestures and animations between tabs.
+   *
+   * The following adapters are provided out of the box:
+   * - `PagerViewAdapter`: Uses `react-native-pager-view` for native experience.
+   * - `PanResponderAdapter`: Uses `PanResponder` for a JS-based implementation.
+   * - `ScrollViewAdapter`: Uses `ScrollView` for an implementation based on `ScrollView`.
+   *
+   * Defaults to `PagerViewAdapter` on Android and iOS, and `PanResponderAdapter` on other platforms.
+   */
+  renderAdapter?: (props: AdapterProps) => React.ReactElement;
+  /**
+   * Position of the tab bar in the tab view.
+   * Defaults to `'top'`.
+   */
   tabBarPosition?: 'top' | 'bottom';
-  initialLayout?: Partial<Layout>;
+  /**
+   * Whether to lazily render the scenes.
+   * When enabled, scenes are rendered only when they come into view.
+   *
+   * Can be a boolean or a function that receives the route and returns a boolean.
+   * Defaults to `false`.
+   */
   lazy?: ((props: { route: T }) => boolean) | boolean;
+  /**
+   * How many screens to preload when `lazy` is enabled.
+   *
+   * Defaults to `0`.
+   */
   lazyPreloadDistance?: number;
+  /**
+   * The layout direction of the tab view.
+   *
+   * Defaults to the app's locale direction (RTL or LTR).
+   */
   direction?: LocaleDirection;
+  /**
+   * Style to apply to the pager container.
+   */
   pagerStyle?: StyleProp<ViewStyle>;
+  /**
+   * Style to apply to the tab view container.
+   */
   style?: StyleProp<ViewStyle>;
+  /**
+   * Callback which returns a React element to render for each route.
+   */
   renderScene: (props: SceneRendererProps & { route: T }) => React.ReactNode;
+  /**
+   * Options for individual tabs, keyed by route key.
+   *
+   * Example:
+   * ```js
+   * {
+   *  first: { labelText: 'First Tab' },
+   *  second: { labelText: 'Second Tab' },
+   * }
+   *
+   * These options are merged with `commonOptions`.
+   */
   options?: Record<string, TabDescriptor<T>>;
+  /**
+   * Options that apply to all tabs.
+   *
+   * Individual tab options from `options` will override these.
+   */
   commonOptions?: TabDescriptor<T>;
 };
 
@@ -52,7 +147,6 @@ export function TabView<T extends Route>({
   onTabSelect,
   navigationState,
   renderScene,
-  initialLayout,
   keyboardDismissMode = 'auto',
   lazy = false,
   lazyPreloadDistance = 0,
@@ -61,13 +155,14 @@ export function TabView<T extends Route>({
   renderLazyPlaceholder = renderLazyPlaceholderDefault,
   // eslint-disable-next-line @eslint-react/no-unstable-default-props
   renderTabBar = (props) => <TabBar {...props} />,
+  // eslint-disable-next-line @eslint-react/no-unstable-default-props
+  renderAdapter = (props) => <Pager {...props} />,
   pagerStyle,
   style,
   direction = I18nManager.getConstants().isRTL ? 'rtl' : 'ltr',
   swipeEnabled = true,
   tabBarPosition = 'top',
   animationEnabled = true,
-  overScrollMode,
   options: sceneOptions,
   commonOptions,
 }: Props<T>) {
@@ -82,30 +177,12 @@ export function TabView<T extends Route>({
     );
   }
 
-  const [layout, setLayout] = React.useState({
-    width: 0,
-    height: 0,
-    ...initialLayout,
-  });
-
   const jumpToIndex = (index: number) => {
     if (index !== navigationState.index) {
       onIndexChange(index);
     }
   };
 
-  const handleLayout = (e: LayoutChangeEvent) => {
-    const { height, width } = e.nativeEvent.layout;
-
-    setLayout((prevLayout) => {
-      if (prevLayout.width === width && prevLayout.height === height) {
-        return prevLayout;
-      }
-
-      return { height, width };
-    });
-  };
-
   const options = Object.fromEntries(
     navigationState.routes.map((route) => [
       route.key,
@@ -116,82 +193,78 @@ export function TabView<T extends Route>({
     ])
   );
 
-  return (
-    <View onLayout={handleLayout} style={[styles.pager, style]}>
-      <Pager
-        layout={layout}
-        navigationState={navigationState}
-        keyboardDismissMode={keyboardDismissMode}
-        swipeEnabled={swipeEnabled}
-        onSwipeStart={onSwipeStart}
-        onSwipeEnd={onSwipeEnd}
-        onIndexChange={jumpToIndex}
-        onTabSelect={onTabSelect}
-        animationEnabled={animationEnabled}
-        overScrollMode={overScrollMode}
-        style={pagerStyle}
-        layoutDirection={direction}
-      >
-        {({ position, render, addEnterListener, jumpTo }) => {
-          // All the props here must not change between re-renders
-          // This is crucial to optimizing the routes with PureComponent
-          const sceneRendererProps = {
-            position,
-            layout,
-            jumpTo,
-          };
+  const element = renderAdapter({
+    navigationState,
+    keyboardDismissMode,
+    swipeEnabled,
+    onSwipeStart,
+    onSwipeEnd,
+    onIndexChange: jumpToIndex,
+    onTabSelect,
+    animationEnabled,
+    layoutDirection: direction,
+    style: pagerStyle,
+    children: ({ position, render, subscribe, jumpTo }) => {
+      // All the props here must not change between re-renders
+      // This is crucial to optimizing the routes with PureComponent
+      const sceneRendererProps = {
+        position,
+        jumpTo,
+      };
 
-          return (
-            <React.Fragment>
-              {tabBarPosition === 'top' &&
-                renderTabBar({
-                  ...sceneRendererProps,
-                  options,
-                  navigationState,
-                })}
-              {render(
-                navigationState.routes.map((route, i) => {
-                  const { sceneStyle } = options?.[route.key] ?? {};
+      return (
+        <React.Fragment>
+          {tabBarPosition === 'top' &&
+            renderTabBar({
+              ...sceneRendererProps,
+              subscribe,
+              options,
+              navigationState,
+            })}
+          {render(
+            navigationState.routes.map((route, i) => {
+              const { sceneStyle } = options?.[route.key] ?? {};
 
-                  return (
-                    <SceneView
-                      key={route.key}
-                      {...sceneRendererProps}
-                      addEnterListener={addEnterListener}
-                      index={i}
-                      lazy={typeof lazy === 'function' ? lazy({ route }) : lazy}
-                      lazyPreloadDistance={lazyPreloadDistance}
-                      navigationState={navigationState}
-                      style={sceneStyle}
-                    >
-                      {({ loading }) =>
-                        loading
-                          ? renderLazyPlaceholder({ route })
-                          : renderScene({
-                              ...sceneRendererProps,
-                              route,
-                            })
-                      }
-                    </SceneView>
-                  );
-                })
-              )}
-              {tabBarPosition === 'bottom' &&
-                renderTabBar({
-                  ...sceneRendererProps,
-                  options,
-                  navigationState,
-                })}
-            </React.Fragment>
-          );
-        }}
-      </Pager>
-    </View>
-  );
+              return (
+                <SceneView
+                  key={route.key}
+                  {...sceneRendererProps}
+                  subscribe={subscribe}
+                  index={i}
+                  lazy={typeof lazy === 'function' ? lazy({ route }) : lazy}
+                  lazyPreloadDistance={lazyPreloadDistance}
+                  navigationState={navigationState}
+                  style={sceneStyle}
+                >
+                  {({ loading }) =>
+                    loading
+                      ? renderLazyPlaceholder({ route })
+                      : renderScene({
+                          ...sceneRendererProps,
+                          route,
+                        })
+                  }
+                </SceneView>
+              );
+            })
+          )}
+          {tabBarPosition === 'bottom' &&
+            renderTabBar({
+              ...sceneRendererProps,
+              subscribe,
+              options,
+              navigationState,
+            })}
+        </React.Fragment>
+      );
+    },
+  });
+
+  return <View style={[styles.container, style]}>{element}</View>;
 }
 
 const styles = StyleSheet.create({
-  pager: {
+  container: {
     flex: 1,
     overflow: 'hidden',
   },

package/src/index.tsx

@@ -1,4 +1,13 @@
+export {
+  PagerViewAdapter,
+  type PagerViewAdapterProps,
+} from './PagerViewAdapter';
+export { PanResponderAdapter } from './PanResponderAdapter';
 export { SceneMap } from './SceneMap';
+export {
+  ScrollViewAdapter,
+  type ScrollViewAdapterProps,
+} from './ScrollViewAdapter';
 export type { Props as TabBarProps } from './TabBar';
 export { TabBar } from './TabBar';
 export type { Props as TabBarIndicatorProps } from './TabBarIndicator';
@@ -8,6 +17,7 @@ export { TabBarItem } from './TabBarItem';
 export type { Props as TabViewProps } from './TabView';
 export { TabView } from './TabView';
 export type {
+  AdapterProps,
   NavigationState,
   Route,
   SceneRendererProps,

package/src/types.tsx

@@ -1,5 +1,11 @@
-import type { Animated, StyleProp, TextStyle, ViewStyle } from 'react-native';
-import type { PagerViewProps } from 'react-native-pager-view';
+import * as React from 'react';
+import type {
+  Animated,
+  ColorValue,
+  StyleProp,
+  TextStyle,
+  ViewStyle,
+} from 'react-native';
 
 export type TabDescriptor<T extends Route> = {
   accessibilityLabel?: string;
@@ -12,7 +18,7 @@ export type TabDescriptor<T extends Route> = {
     route: T;
     labelText?: string;
     focused: boolean;
-    color: string;
+    color: ColorValue;
     allowFontScaling?: boolean;
     style?: StyleProp<TextStyle>;
   }) => React.ReactNode;
@@ -20,7 +26,7 @@ export type TabDescriptor<T extends Route> = {
   icon?: (props: {
     route: T;
     focused: boolean;
-    color: string;
+    color: ColorValue;
     size: number;
   }) => React.ReactNode;
   badge?: (props: { route: T }) => React.ReactElement;
@@ -57,31 +63,83 @@ export type Layout = {
   height: number;
 };
 
-export type Listener = (value: number) => void;
+export type Listener = (event: { type: 'enter'; index: number }) => void;
 
 export type SceneRendererProps = {
-  layout: Layout;
   position: Animated.AnimatedInterpolation<number>;
   jumpTo: (key: string) => void;
 };
 
 export type EventEmitterProps = {
-  addEnterListener: (listener: Listener) => () => void;
+  subscribe: (listener: Listener) => () => void;
 };
 
-export type PagerProps = Omit<
-  PagerViewProps,
-  | 'initialPage'
-  | 'scrollEnabled'
-  | 'onPageScroll'
-  | 'onPageSelected'
-  | 'onPageScrollStateChanged'
-  | 'keyboardDismissMode'
-  | 'children'
-> & {
+export type AdapterCommonProps = {
+  /**
+   * Determines whether the keyboard gets dismissed in response to a drag.
+   * - 'auto' (default) - the keyboard is dismissed on drag and tab changes
+   * - 'on-drag' - the keyboard is dismissed when a drag begins
+   * - 'none' - drags and tab changes do not dismiss the keyboard
+   */
   keyboardDismissMode?: 'none' | 'on-drag' | 'auto';
+  /**
+   * Whether swiping between tabs is enabled.
+   */
   swipeEnabled?: boolean;
+  /**
+   * Whether the tab switch animation is enabled.
+   * If set to false, the tab switch will happen immediately without animation.
+   */
   animationEnabled?: boolean;
+  /**
+   * Callback that is called when the swipe gesture starts.
+   */
   onSwipeStart?: () => void;
+  /**
+   * Callback that is called when the swipe gesture ends.
+   */
   onSwipeEnd?: () => void;
+  /**
+   * Callback that is called when a tab is selected.
+   * This is called regardless of whether the index has changed or not.
+   */
+  onTabSelect?: (props: { index: number }) => void;
+  /**
+   * Style for the pager adapter.
+   */
+  style?: StyleProp<ViewStyle>;
 };
+
+export type AdapterRendererProps = {
+  /**
+   * Callback to call when the index changes.
+   */
+  onIndexChange: (index: number) => void;
+  /**
+   * The current navigation state of the tab view.
+   */
+  navigationState: NavigationState<Route>;
+  /**
+   * The writing direction of the layout.
+   * This can be 'ltr' or 'rtl' based on tab view's `direction` prop.
+   */
+  layoutDirection?: LocaleDirection;
+  /**
+   * Render callback that should render the pages of the tab view.
+   */
+  children: (
+    props: EventEmitterProps & {
+      // Animated value which represents the state of current index
+      // It can include fractional digits as it represents the intermediate value
+      position: Animated.AnimatedInterpolation<number>;
+      // Function to actually render the content of the pager
+      // The parent component takes care of rendering
+      render: (children: React.ReactElement[]) => React.ReactNode;
+      // Callback to call when switching the tab
+      // The tab switch animation is performed even if the index in state is unchanged
+      jumpTo: (key: string) => void;
+    }
+  ) => React.ReactElement;
+};
+
+export type AdapterProps = AdapterRendererProps & AdapterCommonProps;

package/src/useMeasureLayout.tsx

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import { type LayoutChangeEvent, type View } from 'react-native';
+import useLatestCallback from 'use-latest-callback';
+
+import type { Layout } from './types';
+
+export function useMeasureLayout(
+  ref: React.RefObject<View | null>,
+  onMeasure?: (layout: Layout) => void
+) {
+  const [layout, setLayout] = React.useState<Layout>({ width: 0, height: 0 });
+
+  const onMeasureLatest = useLatestCallback(({ width, height }: Layout) => {
+    setLayout((layout) =>
+      layout.width === width && layout.height === height
+        ? layout
+        : { width, height }
+    );
+
+    onMeasure?.({ width, height });
+  });
+
+  React.useLayoutEffect(() => {
+    ref.current?.measure((_x, _y, width, height) => {
+      onMeasureLatest({ width, height });
+    });
+  }, [onMeasureLatest, ref]);
+
+  const onLayout = useLatestCallback((event: LayoutChangeEvent) => {
+    onMeasureLatest(event.nativeEvent.layout);
+  });
+
+  return [layout, onLayout] as const;
+}