Layout & Positioning

/**
 * Modal dialog component with backdrop and focus management
 * @param props - Modal properties including open state and event handlers
 * @returns Modal element with proper accessibility and focus trapping
 */
function Modal(props: ModalProps): JSX.Element;

interface ModalProps {
  /** Single child element to render in modal */
  children: React.ReactElement;
  /** Whether to wait for transition before closing */
  closeAfterTransition?: boolean;
  /** Container element or function returning container */
  container?: HTMLElement | (() => HTMLElement | null) | null;
  /** Whether to disable auto focus on open */
  disableAutoFocus?: boolean;
  /** Whether to disable focus enforcement */
  disableEnforceFocus?: boolean;
  /** Whether to disable escape key handling */
  disableEscapeKeyDown?: boolean;
  /** Whether to disable portal rendering */
  disablePortal?: boolean;
  /** Whether to disable focus restoration on close */
  disableRestoreFocus?: boolean;
  /** Whether to disable scroll lock */
  disableScrollLock?: boolean;
  /** Whether to hide backdrop */
  hideBackdrop?: boolean;
  /** Whether to keep mounted when closed */
  keepMounted?: boolean;
  /** Close event handler */
  onClose?: (event: {}, reason: ModalCloseReason) => void;
  /** Transition enter handler */
  onTransitionEnter?: () => void;
  /** Transition exited handler */
  onTransitionExited?: () => void;
  /** Whether modal is open */
  open: boolean;
}

type ModalCloseReason = 'escapeKeyDown' | 'backdropClick';

// Modal manager for handling multiple modals
declare class ModalManager {
  add(modal: any, container: HTMLElement): number;
  remove(modal: any): number;
  isTopModal(modal: any): boolean;
}

import { Modal } from "@mui/base/Modal";

// Basic modal
<Modal 
  open={isOpen} 
  onClose={() => setIsOpen(false)}
>
  <div className="modal-content">
    <h2>Modal Title</h2>
    <p>Modal content goes here.</p>
    <button onClick={() => setIsOpen(false)}>Close</button>
  </div>
</Modal>

// Modal with custom backdrop behavior
<Modal
  open={isOpen}
  onClose={(event, reason) => {
    if (reason === 'backdropClick') {
      console.log('Closed by backdrop click');
    }
    setIsOpen(false);
  }}
  disableEscapeKeyDown
>
  <div className="modal-content">
    <p>This modal can only be closed by clicking backdrop</p>
  </div>
</Modal>

/**
 * Floating popup component using Floating UI for positioning
 * @param props - Popup properties including anchor and placement
 * @returns Popup element with advanced positioning capabilities
 */
function Unstable_Popup(props: PopupProps): JSX.Element;

interface PopupProps {
  /** Anchor element for positioning */
  anchor?: VirtualElement | (() => VirtualElement) | null;
  /** Popup content */
  children?: React.ReactNode | ((props: PopupChildrenProps) => React.ReactNode);
  /** Container element for portal */
  container?: HTMLElement | null | (() => HTMLElement | null);
  /** Whether to disable portal rendering */
  disablePortal?: boolean;
  /** Whether to keep mounted when closed */
  keepMounted?: boolean;
  /** Floating UI middleware array */
  middleware?: Array<Middleware | null | undefined | false>;
  /** Offset from anchor element */
  offset?: number | Options;
  /** Whether popup is visible */
  open?: boolean;
  /** Popup placement relative to anchor */
  placement?: Placement;
  /** Positioning strategy */
  strategy?: 'absolute' | 'fixed';
}

interface PopupChildrenProps {
  placement: Placement;
  arrowRef: React.RefCallback<Element>;
  arrowProps: React.HTMLProps<HTMLElement>;
}

// Popup context for accessing popup state
const PopupContext: React.Context<PopupContextValue | null>;

interface PopupContextValue {
  open: boolean;
  setOpen: (open: boolean) => void;
  placement: Placement;
  anchor: VirtualElement | null;
  setAnchor: (anchor: VirtualElement | null) => void;
}

/**
 * Legacy popup component using Popper.js for positioning
 * @param props - Popper properties including anchor element and placement
 * @returns Popper element with Popper.js positioning
 */
function Popper(props: PopperProps): JSX.Element;

interface PopperProps {
  /** Anchor element for positioning */
  anchorEl?: null | VirtualElement | (() => VirtualElement);
  /** Popper content */
  children?: React.ReactNode | ((props: PopperChildrenProps) => React.ReactNode);
  /** Container element for portal */
  container?: HTMLElement | (() => HTMLElement | null) | null;
  /** Text direction for placement calculations */
  direction?: 'ltr' | 'rtl';
  /** Whether to disable portal rendering */
  disablePortal?: boolean;
  /** Whether to keep mounted when closed */
  keepMounted?: boolean;
  /** Popper.js modifiers */
  modifiers?: ReadonlyArray<Modifier<any, any>>;
  /** Whether popper is visible */
  open: boolean;
  /** Popper placement */
  placement?: PopperPlacementType;
  /** Popper.js options */
  popperOptions?: Partial<Options>;
  /** Ref to Popper.js instance */
  popperRef?: React.Ref<Instance>;
  /** Whether to use transition */
  transition?: boolean;
}

interface PopperChildrenProps {
  placement: PopperPlacementType;
  TransitionProps?: {
    in: boolean;
    onEnter: () => void;
    onExited: () => void;
  };
}

type PopperPlacementType = 
  | 'auto-end'
  | 'auto-start'
  | 'auto'
  | 'bottom-end'
  | 'bottom-start'
  | 'bottom'
  | 'left-end'
  | 'left-start'
  | 'left'
  | 'right-end'
  | 'right-start'
  | 'right'
  | 'top-end'
  | 'top-start'
  | 'top';

/**
 * Renders children into different part of DOM tree
 * @param props - Portal properties including container and children
 * @returns Portal that renders children in specified container
 */
function Portal(props: PortalProps): React.ReactPortal | null;

interface PortalProps {
  /** Content to render in portal */
  children?: React.ReactNode;
  /** DOM element to render children into */
  container?: Element | (() => Element | null) | null;
  /** Whether to disable portal (render in normal location) */
  disablePortal?: boolean;
}

import { Portal } from "@mui/base/Portal";

// Basic portal
<Portal>
  <div>This will render at document.body</div>
</Portal>

// Portal with custom container
<Portal container={() => document.getElementById('modal-root')}>
  <div>This will render in #modal-root</div>
</Portal>

// Conditional portal
<Portal disablePortal={!usePortal}>
  <div>This may or may not use portal based on usePortal state</div>
</Portal>

/**
 * Traps focus within container element for accessibility
 * @param props - Focus trap properties including open state and options
 * @returns Focus trap wrapper around single child element
 */
function FocusTrap(props: FocusTrapProps): JSX.Element;

interface FocusTrapProps {
  /** Single child element to wrap with focus trap */
  children: React.ReactElement;
  /** Whether to disable auto focus on mount */
  disableAutoFocus?: boolean;
  /** Whether to disable focus enforcement */
  disableEnforceFocus?: boolean;
  /** Whether to disable focus restoration on unmount */
  disableRestoreFocus?: boolean;
  /** Function to get tabbable elements */
  getTabbable?: () => HTMLElement[];
  /** Function determining if focus trap is enabled */
  isEnabled?: () => boolean;
  /** Whether focus trap is active */
  open: boolean;
}

/**
 * Toast notification component with auto-hide functionality
 * @param props - Snackbar properties including open state and duration
 * @returns Snackbar element with notification display
 */
function Snackbar<RootComponentType extends React.ElementType = "div">(
  props: SnackbarProps<RootComponentType>
): JSX.Element;

interface SnackbarProps<RootComponentType extends React.ElementType = "div">
  extends PolymorphicProps<SnackbarTypeMap, RootComponentType> {
  /** Time in milliseconds to auto-hide (default: null) */
  autoHideDuration?: number | null;
  /** Snackbar content */
  children?: React.ReactNode;
  /** Whether snackbar is fully exited from view */
  exited?: boolean;
  /** Close event handler */
  onClose?: (event: Event | React.SyntheticEvent<any> | null, reason: SnackbarCloseReason) => void;
  /** Whether snackbar is visible */
  open?: boolean;
  /** Time left before auto-hide when resuming */
  resumeHideDuration?: number;
}

type SnackbarCloseReason = 'timeout' | 'clickaway' | 'escapeKeyDown';

import { Snackbar } from "@mui/base/Snackbar";

// Basic snackbar
<Snackbar 
  open={showNotification}
  autoHideDuration={4000}
  onClose={() => setShowNotification(false)}
>
  <div className="snackbar-content">
    Operation completed successfully!
  </div>
</Snackbar>

// Snackbar with close reason handling
<Snackbar
  open={showError}
  onClose={(event, reason) => {
    if (reason === 'timeout') {
      console.log('Auto-closed after timeout');
    }
    setShowError(false);
  }}
>
  <div className="error-snackbar">
    <span>Error occurred!</span>
    <button onClick={() => setShowError(false)}>×</button>
  </div>
</Snackbar>

/**
 * CSS transition wrapper component
 * @param props - CSS transition properties including class names
 * @returns Element with CSS transition support
 */
function CssTransition(props: CssTransitionProps): JSX.Element;

interface CssTransitionProps {
  /** Content to animate */
  children?: React.ReactNode;
  /** Base CSS class name */
  className?: string;
  /** CSS class applied when entering */
  enterClassName?: string;
  /** CSS class applied when exiting */
  exitClassName?: string;
  /** Property name to determine transition end */
  lastTransitionedPropertyOnExit?: string;
}

/**
 * CSS animation wrapper component
 * @param props - CSS animation properties including animation names
 * @returns Element with CSS animation support
 */
function CssAnimation(props: CssAnimationProps): JSX.Element;

interface CssAnimationProps {
  /** Content to animate */
  children?: React.ReactNode;
  /** Base CSS class name */
  className?: string;
  /** CSS animation name for enter */
  enterAnimationName?: string;
  /** CSS class applied when entering */
  enterClassName?: string;
  /** CSS animation name for exit */
  exitAnimationName?: string;
  /** CSS class applied when exiting */
  exitClassName?: string;
}

/**
 * Detects clicks outside wrapped element
 * @param props - Click away listener properties including callback
 * @returns Wrapper that detects outside clicks
 */
function ClickAwayListener(props: ClickAwayListenerProps): JSX.Element;

interface ClickAwayListenerProps {
  /** Single child element to monitor for outside clicks */
  children: React.ReactElement;
  /** Whether to ignore React tree for click detection */
  disableReactTree?: boolean;
  /** Mouse event type to listen for */
  mouseEvent?: 'onClick' | 'onMouseDown' | 'onMouseUp' | false;
  /** Callback fired when click occurs outside */
  onClickAway: (event: MouseEvent | TouchEvent) => void;
  /** Touch event type to listen for */
  touchEvent?: 'onTouchStart' | 'onTouchEnd' | false;
}

/**
 * Prevents server-side rendering of children
 * @param props - NoSsr properties including fallback content
 * @returns Wrapper that conditionally renders children on client
 */
function NoSsr(props: NoSsrProps): JSX.Element;

interface NoSsrProps {
  /** Content to render on client side only */
  children?: React.ReactNode;
  /** Whether to defer rendering until after first client render */
  defer?: boolean;
  /** Placeholder content during SSR */
  fallback?: React.ReactNode;
}

/**
 * Textarea that automatically adjusts height based on content
 * @param props - Textarea autosize properties including min/max rows
 * @returns Textarea element with auto-sizing behavior
 */
const TextareaAutosize: React.ForwardRefExoticComponent<
  TextareaAutosizeProps & React.RefAttributes<HTMLTextAreaElement>
>;

interface TextareaAutosizeProps
  extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'rows'> {
  /** Maximum number of rows */
  maxRows?: number;
  /** Minimum number of rows (default: 1) */
  minRows?: number;
}

// Modal behavior hook
function unstable_useModal(props: UseModalParameters): UseModalReturnValue;

// Snackbar behavior hook
function useSnackbar(props: UseSnackbarParameters): UseSnackbarReturnValue;

// Transition hooks (used internally by transition components)
function useTransition(props: UseTransitionParameters): UseTransitionReturnValue;