Navigation and Routing

/**
 * Router outlet component that renders routed components with stack management.
 * Handles page transitions and maintains navigation history.
 */
const IonRouterOutlet: React.FC<{
  className?: string;
  basePath?: string;
  /** Whether to automatically wrap rendered components in IonPage */
  ionPage?: boolean;
}>;

/**
 * Route definition component that maps URL paths to React components.
 * Works with IonRouterOutlet to provide declarative routing.
 */
const IonRoute: React.FC<{
  /** URL path pattern to match */
  path?: string;
  /** Whether the path must match exactly */
  exact?: boolean;
  /** Whether to show this route */
  show?: boolean;
  /** Function that returns the component to render */
  render: (props?: any) => JSX.Element;
  /** Disable automatic IonPage wrapping */
  disableIonPageManagement?: boolean;
}>;

/**
 * Route redirect component that redirects from one path to another.
 */
const IonRedirect: React.FC<{
  /** Source path to redirect from */
  path?: string;
  /** Whether the path must match exactly */
  exact?: boolean;
  /** Destination path to redirect to */
  to: string;
  /** Additional router options for the redirect */
  routerOptions?: RouterOptions;
}>;

/**
 * Router-aware link component for programmatic navigation.
 * Provides native-like transitions and maintains navigation stack.
 */
const IonRouterLink: React.FC<{
  className?: string;
  children?: React.ReactNode;
  href: string;
  routerDirection?: 'forward' | 'back' | 'root' | 'none';
  routerAnimation?: any;
}>;

/**
 * Back navigation button with automatic route detection.
 * Automatically shows/hides based on navigation stack.
 */
const IonBackButton: React.FC<{
  className?: string;
  color?: string;
  defaultHref?: string;
  disabled?: boolean;
  icon?: any;
  text?: string;
  routerAnimation?: any;
}>;

/**
 * Tab container component with router integration and outlet support.
 * Manages tab state and provides context for tab buttons and outlets.
 */
const IonTabs: React.FC<{
  className?: string;
  children?: React.ReactNode;
  /** Callback fired when tab will change */
  onIonTabsWillChange?: (event: CustomEvent<{ tab: string }>) => void;
  /** Callback fired when tab did change */
  onIonTabsDidChange?: (event: CustomEvent<{ tab: string }>) => void;
}>;

/**
 * Tab bar component that contains tab buttons.
 * Typically used as a child of IonTabs.
 */
const IonTabBar: React.FC<{
  className?: string;
  children?: React.ReactNode;
  color?: string;
  selectedTab?: string;
  translucent?: boolean;
}>;

/**
 * Individual tab button component.
 * Used within IonTabBar to create tappable tab navigation.
 */
const IonTabButton: React.FC<{
  className?: string;
  children?: React.ReactNode;
  tab: string;
  disabled?: boolean;
  download?: string;
  href?: string;
  rel?: string;
  target?: string;
  layout?: 'icon-top' | 'icon-start' | 'icon-end' | 'icon-bottom' | 'icon-hide' | 'label-hide';
}>;

/**
 * Tab content container.
 * Represents the content area for a specific tab.
 */
const IonTab: React.FC<{
  className?: string;
  children?: React.ReactNode;
  tab: string;
}>;

/**
 * Side menu component that slides in from the side.
 * Can contain navigation items and other content.
 */
const IonMenu: React.FC<{
  className?: string;
  children?: React.ReactNode;
  contentId: string;
  menuId?: string;
  side?: 'start' | 'end';
  type?: 'overlay' | 'reveal' | 'push';
  disabled?: boolean;
  swipeGesture?: boolean;
  maxEdgeStart?: number;
}>;

/**
 * Button to toggle menu open/closed state.
 * Automatically detects and controls the nearest menu.
 */
const IonMenuButton: React.FC<{
  className?: string;
  autoHide?: boolean;
  color?: string;
  disabled?: boolean;
  menu?: string;
  type?: 'button' | 'submit' | 'reset';
}>;

/**
 * Menu toggle wrapper that shows/hides content based on menu state.
 */
const IonMenuToggle: React.FC<{
  className?: string;
  children?: React.ReactNode;
  autoHide?: boolean;
  menu?: string;
  disabled?: boolean;
}>;

/**
 * Programmatic navigation component that manages a stack of pages.
 * Provides imperative API for pushing and popping pages.
 */
const IonNav: React.FC<{
  className?: string;
  root?: React.ComponentType<any>;
  rootParams?: any;
  onIonNavDidChange?: (event: CustomEvent) => void;
  onIonNavWillChange?: (event: CustomEvent) => void;
}>;

/**
 * Navigation link component for programmatic navigation.
 * Pushes a new component onto the navigation stack.
 */
const IonNavLink: React.FC<{
  className?: string;
  children?: React.ReactNode;
  component?: React.ComponentType<any>;
  componentProps?: any;
  routerDirection?: 'forward' | 'back' | 'root' | 'none';
}>;

/**
 * Container for breadcrumb navigation items.
 */
const IonBreadcrumbs: React.FC<{
  className?: string;
  children?: React.ReactNode;
  color?: string;
  maxItems?: number;
  itemsAfterCollapse?: number;
  itemsBeforeCollapse?: number;
}>;

/**
 * Individual breadcrumb item with routing capabilities.
 */
const IonBreadcrumb: React.FC<{
  className?: string;
  children?: React.ReactNode;
  active?: boolean;
  disabled?: boolean;
  download?: string;
  href?: string;
  rel?: string;
  target?: string;
  routerLink?: string;
  routerDirection?: 'forward' | 'back' | 'root' | 'none';
}>;

import React from 'react';
import { 
  IonRouterOutlet, IonRoute, IonRedirect, 
  IonTabs, IonTabBar, IonTabButton, IonTab,
  IonBackButton, IonRouterLink
} from '@ionic/react';
import { IonReactRouter } from '@ionic/react-router';

// Basic routing setup
const AppRouting: React.FC = () => (
  <IonReactRouter>
    <IonRouterOutlet>
      <IonRoute path="/home" render={() => <HomePage />} exact />
      <IonRoute path="/settings" render={() => <SettingsPage />} exact />
      <IonRedirect from="/" to="/home" exact />
    </IonRouterOutlet>
  </IonReactRouter>
);

// Tab navigation setup
const TabsExample: React.FC = () => (
  <IonTabs>
    <IonRouterOutlet>
      <IonRoute path="/tabs/home" render={() => <HomePage />} />
      <IonRoute path="/tabs/settings" render={() => <SettingsPage />} />
      <IonRedirect from="/tabs" to="/tabs/home" exact />
    </IonRouterOutlet>
    
    <IonTabBar>
      <IonTabButton tab="home" href="/tabs/home">
        <IonIcon icon={home} />
        Home
      </IonTabButton>
      <IonTabButton tab="settings" href="/tabs/settings">
        <IonIcon icon={settings} />
        Settings
      </IonTabButton>
    </IonTabBar>
  </IonTabs>
);

// Page with navigation
const DetailPage: React.FC = () => (
  <IonPage>
    <IonHeader>
      <IonToolbar>
        <IonButtons slot="start">
          <IonBackButton defaultHref="/home" />
        </IonButtons>
        <IonTitle>Details</IonTitle>
      </IonToolbar>
    </IonHeader>
    
    <IonContent>
      <IonRouterLink href="/other-page">
        Go to Other Page
      </IonRouterLink>
    </IonContent>
  </IonPage>
);

interface RouterOptions {
  /** Navigation direction for animations */
  direction?: 'forward' | 'back' | 'root' | 'none';
  /** Whether to animate the transition */
  animated?: boolean;
  /** Custom animation to use */
  animation?: any;
  /** Animation duration in milliseconds */
  duration?: number;
}

interface RouteInfo {
  /** Current pathname */
  pathname: string;
  /** Current search string */
  search: string;
  /** Current hash */
  hash: string;
  /** Route state object */
  state?: any;
}

type RouterDirection = 'forward' | 'back' | 'root' | 'none';

/** Props interface for routing-enabled components */
interface HrefProps {
  /** URL to navigate to */
  href?: string;
  /** Target window for link */
  target?: string;
  /** Download attribute */
  download?: string;
  /** Relationship between current and linked document */
  rel?: string;
  /** Router direction for animations */
  routerDirection?: RouterDirection;
  /** Custom animation for navigation */
  routerAnimation?: any;
}

/** Navigation action types */
enum RouteAction {
  Push = 'push',
  Pop = 'pop',
  Replace = 'replace'
}

/** React component or element type */
type ReactComponentOrElement = React.ComponentType<any> | React.ReactElement<any>;