Navigation Container

/**
 * Container component which holds the navigation state designed for React Native apps.
 * This should be rendered at the root wrapping the whole app.
 */
function NavigationContainer<ParamList extends {} = ReactNavigation.RootParamList>(
  props: NavigationContainerProps & {
    /** Text direction of the components. Defaults to device locale direction */
    direction?: LocaleDirection;
    /** Options for deep linking. Deep link handling is enabled when this prop is provided */
    linking?: LinkingOptions<ParamList>;
    /** Fallback component to render until initial state is ready when linking is enabled */
    fallback?: React.ReactNode;
    /** Options to configure the document title on Web */
    documentTitle?: DocumentTitleOptions;
    /** Child elements to render the content */
    children: React.ReactNode;
  } & React.RefAttributes<NavigationContainerRef<ParamList>>
): React.ReactElement;

type LocaleDirection = 'ltr' | 'rtl';

import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';

const Stack = createStackNavigator();

// Basic usage
function BasicApp() {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Profile" component={ProfileScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

// With deep linking
function AppWithLinking() {
  const linking = {
    prefixes: ['myapp://'],
    config: {
      screens: {
        Home: 'home',
        Profile: 'user/:id',
      },
    },
  };

  return (
    <NavigationContainer linking={linking}>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Profile" component={ProfileScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

// With custom theme and direction
function ThemedApp() {
  const customTheme = {
    ...DefaultTheme,
    colors: {
      ...DefaultTheme.colors,
      primary: '#007AFF',
    },
  };

  return (
    <NavigationContainer 
      theme={customTheme}
      direction="rtl"
      onReady={() => console.log('Navigation is ready')}
      onStateChange={(state) => console.log('Navigation state changed', state)}
    >
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

interface NavigationContainerProps {
  /** Initial state object for the navigation tree */
  initialState?: NavigationState | PartialState<NavigationState>;
  /** Callback which is called after the navigation tree mounts */
  onReady?: () => void;
  /** Callback which is called with the latest navigation state when it changes */
  onStateChange?: (state: NavigationState | undefined) => void;
  /** Callback which is called when an action is not handled */
  onUnhandledAction?: (action: NavigationAction) => void;
  /** Theme object for the UI elements */
  theme?: Theme;
  /** Whether to render children inside a React.Fragment */
  independent?: boolean;
}

interface DocumentTitleOptions {
  /** Whether document title updating is enabled. Defaults to true on web */
  enabled?: boolean;
  /** Custom formatter for the document title */
  formatter?: (
    options: Record<string, any> | undefined,
    route: Route<string> | undefined
  ) => string;
}

interface NavigationContainerRef<ParamList extends {} = ReactNavigation.RootParamList> {
  /** Navigate to a route in current navigation tree */
  navigate<RouteName extends keyof ParamList>(
    name: RouteName,
    params?: ParamList[RouteName]
  ): void;
  /** Navigate to a route in current navigation tree */
  navigate<RouteName extends keyof ParamList>(
    route: { name: RouteName; params?: ParamList[RouteName]; path?: string }
  ): void;
  /** Go back to the previous route in history */
  goBack(): void;
  /** Check if it's possible to go back in current navigation tree */
  canGoBack(): boolean;
  /** Dispatch a navigation action */
  dispatch(action: NavigationAction): void;
  /** Get the current navigation state */
  getState(): NavigationState;
  /** Get the currently focused route */
  getCurrentRoute(): Route<string> | undefined;
  /** Get options for the currently focused route */
  getCurrentOptions(): object | undefined;
  /** Check if the screen is focused */
  isFocused(): boolean;
  /** Subscribe to navigation state updates */
  addListener<EventName extends keyof NavigationEventMap>(
    type: EventName,
    listener: NavigationEventMap[EventName]
  ): () => void;
  /** Remove all listeners for the given event type */
  removeListener<EventName extends keyof NavigationEventMap>(
    type: EventName,
    listener: NavigationEventMap[EventName]
  ): void;
}

import React, { useRef } from 'react';
import { NavigationContainer } from '@react-navigation/native';
import type { NavigationContainerRef } from '@react-navigation/native';

function App() {
  const navigationRef = useRef<NavigationContainerRef<RootParamList>>(null);

  const handleDeepLink = (url: string) => {
    // Custom deep link handling
    if (url.includes('profile')) {
      navigationRef.current?.navigate('Profile', { id: '123' });
    }
  };

  return (
    <NavigationContainer 
      ref={navigationRef}
      onReady={() => {
        // Navigation is ready, can safely navigate
        console.log('Current route:', navigationRef.current?.getCurrentRoute()?.name);
      }}
    >
      {/* Your navigation structure */}
    </NavigationContainer>
  );
}

// Platform-specific behavior is handled automatically
// No additional configuration required for basic integration

// For custom back button behavior:
interface NavigationContainerProps {
  /** Custom handler for unhandled actions (including back button) */
  onUnhandledAction?: (action: NavigationAction) => void;
}