Tab View Component

/**
 * Main TabView component for creating swipeable tab interfaces
 * @param props - TabView configuration and event handlers
 * @returns JSX element containing the complete tab interface
 */
function TabView<T extends Route>(props: Props<T>): JSX.Element;

interface Props<T extends Route> extends Omit<PagerProps, 'layoutDirection'> {
  /** Required callback when active tab index changes */
  onIndexChange: (index: number) => void;
  /** Optional callback when tab is selected (before index change) */
  onTabSelect?: (props: { index: number }) => void;
  /** Required navigation state containing current index and routes */
  navigationState: NavigationState<T>;
  /** Required function to render scene content for each route */
  renderScene: (props: SceneRendererProps & { route: T }) => React.ReactNode;
  /** Optional placeholder renderer for lazy-loaded scenes */
  renderLazyPlaceholder?: (props: { route: T }) => React.ReactNode;
  /** Optional custom tab bar renderer (defaults to TabBar component) */
  renderTabBar?: (props: SceneRendererProps & {
    navigationState: NavigationState<T>;
    options: Record<string, TabDescriptor<T>> | undefined;
  }) => React.ReactNode;
  /** Tab bar position - 'top' or 'bottom' (default: 'top') */
  tabBarPosition?: 'top' | 'bottom';
  /** Initial layout dimensions for proper sizing */
  initialLayout?: Partial<Layout>;
  /** Enable lazy loading - boolean or function to determine per route */
  lazy?: boolean | ((props: { route: T }) => boolean);
  /** Distance ahead to preload lazy scenes (default: 0) */
  lazyPreloadDistance?: number;
  /** Text direction override - 'ltr' or 'rtl' */
  direction?: LocaleDirection;
  /** Style for the pager container */
  pagerStyle?: StyleProp<ViewStyle>;
  /** Style for the main TabView container */
  style?: StyleProp<ViewStyle>;
  /** Per-route options for tab appearance and behavior */
  options?: Record<string, TabDescriptor<T>>;
  /** Common options applied to all tabs */
  commonOptions?: TabDescriptor<T>;
}

import React, { useState } from 'react';
import { View, Text, ActivityIndicator } from 'react-native';
import { TabView, SceneMap, NavigationState, Route } from 'react-native-tab-view';

// Basic TabView with SceneMap
const BasicExample = () => {
  const [index, setIndex] = useState(0);
  const [routes] = useState([
    { key: 'home', title: 'Home' },
    { key: 'profile', title: 'Profile' },
  ]);

  const renderScene = SceneMap({
    home: () => <View><Text>Home Content</Text></View>,
    profile: () => <View><Text>Profile Content</Text></View>,
  });

  return (
    <TabView
      navigationState={{ index, routes }}
      renderScene={renderScene}
      onIndexChange={setIndex}
      initialLayout={{ width: 375 }}
    />
  );
};

// Advanced TabView with lazy loading and custom rendering
const AdvancedExample = () => {
  const [index, setIndex] = useState(0);
  const [routes] = useState([
    { key: 'feed', title: 'Feed' },
    { key: 'search', title: 'Search' },
    { key: 'notifications', title: 'Notifications' },
  ]);

  const renderScene = ({ route }: { route: Route }) => {
    switch (route.key) {
      case 'feed':
        return <FeedScreen />;
      case 'search':
        return <SearchScreen />;
      case 'notifications':
        return <NotificationsScreen />;
      default:
        return null;
    }
  };

  const renderLazyPlaceholder = ({ route }: { route: Route }) => (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <ActivityIndicator size="large" />
      <Text>Loading {route.title}...</Text>
    </View>
  );

  return (
    <TabView
      navigationState={{ index, routes }}
      renderScene={renderScene}
      renderLazyPlaceholder={renderLazyPlaceholder}
      onIndexChange={setIndex}
      lazy
      lazyPreloadDistance={1}
      tabBarPosition="bottom"
      swipeEnabled={true}
      animationEnabled={true}
      initialLayout={{ width: 375, height: 667 }}
    />
  );
};

/**
 * Navigation state interface defining current tab and available routes
 */
interface NavigationState<T extends Route> {
  /** Zero-based index of the currently active tab */
  index: number;
  /** Array of route objects defining available tabs */
  routes: T[];
}

/**
 * Base route interface that all tab routes must extend
 */
interface Route {
  /** Unique identifier for the route */
  key: string;
  /** Optional display title for the tab */
  title?: string;
  /** Optional icon identifier */
  icon?: string;
  /** Optional accessibility properties */
  accessible?: boolean;
  accessibilityLabel?: string;
  testID?: string;
}

/**
 * Props passed to scene render functions
 */
interface SceneRendererProps {
  /** Current layout dimensions */
  layout: Layout;
  /** Animated position value for transitions */
  position: Animated.AnimatedInterpolation<number>;
  /** Function to programmatically navigate to a route */
  jumpTo: (key: string) => void;
}

/**
 * Layout dimensions interface
 */
interface Layout {
  /** Container width in pixels */
  width: number;
  /** Container height in pixels */
  height: number;
}

/**
 * Configuration object for tab appearance and behavior
 */
interface TabDescriptor<T extends Route> {
  /** Accessibility label override */
  accessibilityLabel?: string;
  /** Accessibility enabled flag */
  accessible?: boolean;
  /** Test identifier */
  testID?: string;
  /** Tab label text override */
  labelText?: string;
  /** Allow font scaling for label */
  labelAllowFontScaling?: boolean;
  /** Web navigation href */
  href?: string;
  /** Custom label renderer function */
  label?: (props: {
    route: T;
    labelText?: string;
    focused: boolean;
    color: string;
    allowFontScaling?: boolean;
    style?: StyleProp<TextStyle>;
  }) => React.ReactNode;
  /** Label text styling */
  labelStyle?: StyleProp<TextStyle>;
  /** Custom icon renderer function */
  icon?: (props: {
    route: T;
    focused: boolean;
    color: string;
    size: number;
  }) => React.ReactNode;
  /** Custom badge renderer function */
  badge?: (props: { route: T }) => React.ReactElement;
  /** Scene container styling */
  sceneStyle?: StyleProp<ViewStyle>;
}

/**
 * Event object for tab interactions
 */
interface Event {
  /** Whether default behavior has been prevented */
  defaultPrevented: boolean;
  /** Function to prevent default navigation behavior */
  preventDefault(): void;
}

/**
 * Scene context interface
 */
interface Scene<T extends Route> {
  /** The route associated with this scene */
  route: T;
}

/**
 * Pager-specific properties inherited by TabView
 */
interface PagerProps {
  /** Keyboard dismiss behavior */
  keyboardDismissMode?: 'none' | 'on-drag' | 'auto';
  /** Enable/disable swipe gestures */
  swipeEnabled?: boolean;
  /** Enable/disable page animations */
  animationEnabled?: boolean;
  /** Callback when swipe gesture starts */
  onSwipeStart?: () => void;
  /** Callback when swipe gesture ends */
  onSwipeEnd?: () => void;
  /** Android scroll behavior */
  overScrollMode?: 'auto' | 'always' | 'never';
}