Navigation Components

/**
 * Contextual menu component that displays a list of choices on a temporary surface
 * @param props - Menu props
 * @returns Menu React component
 */
function Menu(props: MenuProps): JSX.Element;

interface MenuProps extends StandardProps<PopoverProps, MenuClassKey> {
  autoFocus?: boolean;
  children?: React.ReactNode;
  disableAutoFocusItem?: boolean;
  MenuListProps?: Partial<MenuListProps>;
  onClose?: PopoverProps['onClose'];
  open: boolean;
  PopoverClasses?: PopoverProps['classes'];
  transitionDuration?: TransitionProps['timeout'] | 'auto';
  variant?: 'menu' | 'selectedMenu';
}

type MenuClassKey = 'paper' | 'list';

import { Menu, MenuItem, IconButton } from '@material-ui/core';
import { MoreVert as MoreVertIcon } from '@material-ui/icons';

const [anchorEl, setAnchorEl] = useState(null);

<IconButton onClick={(e) => setAnchorEl(e.currentTarget)}>
  <MoreVertIcon />
</IconButton>
<Menu
  anchorEl={anchorEl}
  open={Boolean(anchorEl)}
  onClose={() => setAnchorEl(null)}
>
  <MenuItem onClick={() => setAnchorEl(null)}>Profile</MenuItem>
  <MenuItem onClick={() => setAnchorEl(null)}>My account</MenuItem>
  <MenuItem onClick={() => setAnchorEl(null)}>Logout</MenuItem>
</Menu>

/**
 * Individual item within a menu component
 * @param props - Menu item props
 * @returns Menu item React component
 */
function MenuItem(props: MenuItemProps): JSX.Element;

interface MenuItemProps extends StandardProps<ListItemProps, MenuItemClassKey> {
  component?: React.ElementType;
  dense?: boolean;
  disableGutters?: boolean;
  divider?: boolean;
  selected?: boolean;
}

type MenuItemClassKey = 'root' | 'gutters' | 'selected' | 'dense';

/**
 * Wrapper for menu items providing keyboard navigation
 * @param props - Menu list props
 * @returns Menu list React component
 */
function MenuList(props: MenuListProps): JSX.Element;

interface MenuListProps extends StandardProps<ListProps, MenuListClassKey> {
  autoFocus?: boolean;
  autoFocusItem?: boolean;
  children?: React.ReactNode;
  disabledItemsFocusable?: boolean;
  disableListWrap?: boolean;
  variant?: 'menu' | 'selectedMenu';
}

type MenuListClassKey = 'root' | 'dense';

/**
 * Tab navigation component for organizing content into sections
 * @param props - Tabs props
 * @returns Tabs React component
 */
function Tabs(props: TabsProps): JSX.Element;

interface TabsProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, TabsClassKey> {
  action?: (actions: TabsActions) => void;
  centered?: boolean;
  children?: React.ReactNode;
  component?: React.ElementType;
  indicatorColor?: 'secondary' | 'primary';
  onChange?: (event: React.ChangeEvent<{}>, value: any) => void;
  orientation?: 'horizontal' | 'vertical';
  ScrollButtonComponent?: React.ComponentType<TabScrollButtonProps>;
  scrollButtons?: 'auto' | 'desktop' | 'on' | 'off';
  TabIndicatorProps?: Partial<React.HTMLAttributes<HTMLDivElement>>;
  TabScrollButtonProps?: Partial<TabScrollButtonProps>;
  textColor?: 'secondary' | 'primary' | 'inherit';
  value?: any;
  variant?: 'standard' | 'scrollable' | 'fullWidth';
}

type TabsClassKey = 'root' | 'vertical' | 'flexContainer' | 'flexContainerVertical' | 'centered' | 'scroller' | 'fixed' | 'scrollable' | 'scrollButtons' | 'scrollButtonsDesktop' | 'indicator';

interface TabsActions {
  updateIndicator(): void;
}

import { Tabs, Tab, AppBar } from '@material-ui/core';

const [value, setValue] = useState(0);

<AppBar position="static">
  <Tabs value={value} onChange={(e, newValue) => setValue(newValue)}>
    <Tab label="Item One" />
    <Tab label="Item Two" />
    <Tab label="Item Three" />
  </Tabs>
</AppBar>

// Vertical tabs
<Tabs
  orientation="vertical"
  variant="scrollable"
  value={value}
  onChange={(e, newValue) => setValue(newValue)}
>
  <Tab label="Item One" />
  <Tab label="Item Two" />
  <Tab label="Item Three" />
</Tabs>

/**
 * Individual tab component used within Tabs
 * @param props - Tab props
 * @returns Tab React component
 */
function Tab(props: TabProps): JSX.Element;

interface TabProps extends StandardProps<ButtonBaseProps, TabClassKey> {
  disabled?: boolean;
  fullWidth?: boolean;
  icon?: string | React.ReactElement;
  label?: React.ReactNode;
  value?: any;
  wrapped?: boolean;
}

type TabClassKey = 'root' | 'labelIcon' | 'textColorInherit' | 'textColorPrimary' | 'textColorSecondary' | 'selected' | 'disabled' | 'fullWidth' | 'wrapped' | 'wrapper';

/**
 * Stepper component for displaying progress through numbered steps
 * @param props - Stepper props
 * @returns Stepper React component
 */
function Stepper(props: StepperProps): JSX.Element;

interface StepperProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, StepperClassKey> {
  activeStep?: number;
  alternativeLabel?: boolean;
  children: React.ReactNode;
  connector?: React.ReactElement | null;
  nonLinear?: boolean;
  orientation?: 'horizontal' | 'vertical';
}

type StepperClassKey = 'root' | 'horizontal' | 'vertical' | 'alternativeLabel';

/**
 * Individual step component within a stepper
 * @param props - Step props
 * @returns Step React component
 */
function Step(props: StepProps): JSX.Element;

interface StepProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, StepClassKey> {
  active?: boolean;
  children: React.ReactNode;
  completed?: boolean;
  disabled?: boolean;
  expanded?: boolean;
}

type StepClassKey = 'root' | 'horizontal' | 'vertical' | 'alternativeLabel' | 'completed';

/**
 * Label component for steps displaying text and optional icons
 * @param props - Step label props
 * @returns Step label React component
 */
function StepLabel(props: StepLabelProps): JSX.Element;

interface StepLabelProps extends StandardProps<React.HTMLAttributes<HTMLSpanElement>, StepLabelClassKey> {
  children?: React.ReactNode;
  disabled?: boolean;
  error?: boolean;
  icon?: React.ReactNode;
  optional?: React.ReactNode;
  StepIconComponent?: React.ComponentType<StepIconProps>;
  StepIconProps?: Partial<StepIconProps>;
}

type StepLabelClassKey = 'root' | 'horizontal' | 'vertical' | 'label' | 'active' | 'completed' | 'error' | 'disabled' | 'iconContainer' | 'alternativeLabel' | 'labelContainer';

/**
 * Icon component for steps showing step numbers or custom icons
 * @param props - Step icon props
 * @returns Step icon React component
 */
function StepIcon(props: StepIconProps): JSX.Element;

interface StepIconProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, StepIconClassKey> {
  active?: boolean;
  completed?: boolean;
  error?: boolean;
  icon: React.ReactNode;
}

type StepIconClassKey = 'root' | 'text' | 'active' | 'completed' | 'error';

/**
 * Clickable step component for non-linear steppers
 * @param props - Step button props
 * @returns Step button React component
 */
function StepButton(props: StepButtonProps): JSX.Element;

interface StepButtonProps extends StandardProps<ButtonBaseProps, StepButtonClassKey> {
  active?: boolean;
  alternativeLabel?: boolean;
  children: React.ReactNode;
  completed?: boolean;
  disabled?: boolean;
  icon?: React.ReactNode;
  last?: boolean;
  optional?: React.ReactNode;
  orientation?: 'horizontal' | 'vertical';
}

type StepButtonClassKey = 'root' | 'horizontal' | 'vertical' | 'touchRipple';

/**
 * Content area for vertical steppers
 * @param props - Step content props
 * @returns Step content React component
 */
function StepContent(props: StepContentProps): JSX.Element;

interface StepContentProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, StepContentClassKey> {
  children?: React.ReactNode;
  TransitionComponent?: React.ComponentType<TransitionProps>;
  transitionDuration?: TransitionProps['timeout'] | 'auto';
  TransitionProps?: TransitionProps;
}

type StepContentClassKey = 'root' | 'last' | 'transition';

/**
 * Connector component between steps in a stepper
 * @param props - Step connector props
 * @returns Step connector React component
 */
function StepConnector(props: StepConnectorProps): JSX.Element;

interface StepConnectorProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, StepConnectorClassKey> {}

type StepConnectorClassKey = 'root' | 'horizontal' | 'vertical' | 'alternativeLabel' | 'active' | 'completed' | 'disabled' | 'line' | 'lineHorizontal' | 'lineVertical';

/**
 * Compact stepper designed for mobile interfaces
 * @param props - Mobile stepper props
 * @returns Mobile stepper React component
 */
function MobileStepper(props: MobileStepperProps): JSX.Element;

interface MobileStepperProps extends StandardProps<PaperProps, MobileStepperClassKey> {
  activeStep: number;
  backButton: React.ReactNode;
  LinearProgressProps?: Partial<LinearProgressProps>;
  nextButton: React.ReactNode;
  position?: 'bottom' | 'top' | 'static';
  steps: number;
  variant?: 'text' | 'dots' | 'progress';
}

type MobileStepperClassKey = 'root' | 'positionBottom' | 'positionTop' | 'positionStatic' | 'dots' | 'dot' | 'dotActive' | 'progress';

/**
 * Bottom navigation bar for primary destinations in mobile apps
 * @param props - Bottom navigation props
 * @returns Bottom navigation React component
 */
function BottomNavigation(props: BottomNavigationProps): JSX.Element;

interface BottomNavigationProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, BottomNavigationClassKey> {
  children?: React.ReactNode;
  component?: React.ElementType;
  onChange?: (event: React.SyntheticEvent, value: any) => void;
  showLabels?: boolean;
  value?: any;
}

type BottomNavigationClassKey = 'root';

/**
 * Individual action within bottom navigation
 * @param props - Bottom navigation action props
 * @returns Bottom navigation action React component
 */
function BottomNavigationAction(props: BottomNavigationActionProps): JSX.Element;

interface BottomNavigationActionProps extends StandardProps<ButtonBaseProps, BottomNavigationActionClassKey> {
  icon?: React.ReactNode;
  label?: React.ReactNode;
  selected?: boolean;
  showLabel?: boolean;
  value?: any;
}

type BottomNavigationActionClassKey = 'root' | 'selected' | 'iconOnly' | 'wrapper' | 'label';

import { BottomNavigation, BottomNavigationAction } from '@material-ui/core';
import { Restore, Favorite, LocationOn } from '@material-ui/icons';

const [value, setValue] = useState(0);

<BottomNavigation
  value={value}
  onChange={(event, newValue) => setValue(newValue)}
  showLabels
>
  <BottomNavigationAction label="Recents" icon={<Restore />} />
  <BottomNavigationAction label="Favorites" icon={<Favorite />} />
  <BottomNavigationAction label="Nearby" icon={<LocationOn />} />
</BottomNavigation>

/**
 * Navigation link component with Material-UI styling
 * @param props - Link props
 * @returns Link React component
 */
function Link(props: LinkProps): JSX.Element;

interface LinkProps extends StandardProps<LinkTypeMap['props'], LinkClassKey> {
  TypographyClasses?: TypographyProps['classes'];
  underline?: 'none' | 'hover' | 'always';
}

type LinkClassKey = 'root' | 'underlineNone' | 'underlineHover' | 'underlineAlways' | 'button' | 'focusVisible';

interface LinkTypeMap<P = {}, D extends React.ElementType = 'a'> {
  props: P & TypographyProps<D, { component?: D; underline?: 'none' | 'hover' | 'always' }>;
  defaultComponent: D;
  classKey: LinkClassKey;
}