Utility Components

/**
 * Portal component for rendering content in a different part of the DOM tree
 * @param props - Portal props
 * @returns Portal React component or null
 */
function Portal(props: PortalProps): React.ReactPortal | null;

interface PortalProps {
  children?: React.ReactNode;
  container?: Element | (() => Element | null) | null;
  disablePortal?: boolean;
  onRendered?: () => void;
}

import { Portal } from '@material-ui/core';

// Render to document body
<Portal>
  <div>This content is rendered in document.body</div>
</Portal>

// Render to specific container
<Portal container={() => document.getElementById('modal-root')}>
  <div>This content is rendered in #modal-root</div>
</Portal>

// Conditionally disable portal
<Portal disablePortal={!usePortal}>
  <div>Conditional portal rendering</div>
</Portal>

/**
 * Utility component for detecting clicks outside of a specified element
 * @param props - Click away listener props
 * @returns Click away listener React component
 */
function ClickAwayListener(props: ClickAwayListenerProps): JSX.Element;

interface ClickAwayListenerProps {
  children: React.ReactElement<any, any>;
  mouseEvent?: 'onClick' | 'onMouseDown' | 'onMouseUp' | false;
  onClickAway: (event: MouseEvent | TouchEvent) => void;
  touchEvent?: 'onTouchStart' | 'onTouchEnd' | false;
}

import { ClickAwayListener, Paper } from '@material-ui/core';

const [open, setOpen] = useState(false);

<ClickAwayListener onClickAway={() => setOpen(false)}>
  <Paper>
    <p>Click outside this paper to close</p>
  </Paper>
</ClickAwayListener>

/**
 * Base modal component providing focus management and backdrop functionality
 * @param props - Modal props  
 * @returns Modal React component
 */
function Modal(props: ModalProps): JSX.Element;

interface ModalProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, ModalClassKey> {
  BackdropComponent?: React.ComponentType<BackdropProps>;
  BackdropProps?: Partial<BackdropProps>;
  children: React.ReactElement<any, any>;
  closeAfterTransition?: boolean;
  container?: Element | (() => Element | null) | null;
  disableAutoFocus?: boolean;
  disableBackdropClick?: boolean;
  disableEnforceFocus?: boolean;
  disableEscapeKeyDown?: boolean;
  disablePortal?: boolean;
  disableRestoreFocus?: boolean;
  disableScrollLock?: boolean;
  hideBackdrop?: boolean;
  keepMounted?: boolean;
  manager?: ModalManager;
  onBackdropClick?: React.ReactEventHandler<{}>;
  onClose?: (event: {}, reason: 'backdropClick' | 'escapeKeyDown') => void;
  onEscapeKeyDown?: React.ReactEventHandler<{}>;
  onRendered?: () => void;
  open: boolean;
}

type ModalClassKey = 'root' | 'hidden' | 'backdrop';

/**
 * Utility class for managing multiple modals and their z-index stacking
 */
class ModalManager {
  constructor();
  add(modal: any, container: HTMLElement): number;
  mount(modal: any): void;
  remove(modal: any): number;
  isTopModal(modal: any): boolean;
}

/**
 * Component for preventing server-side rendering of its children
 * @param props - No SSR props
 * @returns No SSR React component
 */
function NoSsr(props: NoSsrProps): JSX.Element;

interface NoSsrProps {
  children?: React.ReactNode;
  defer?: boolean;
  fallback?: React.ReactNode;
}

import { NoSsr } from '@material-ui/core';

// Prevent SSR for component that uses browser APIs
<NoSsr>
  <ComponentThatUsesWindow />
</NoSsr>

// With fallback content
<NoSsr fallback={<div>Loading...</div>}>
  <ClientOnlyComponent />
</NoSsr>

/**
 * Popover component for displaying content in an overlay positioned relative to a target element
 * @param props - Popover props
 * @returns Popover React component
 */
function Popover(props: PopoverProps): JSX.Element;

interface PopoverProps extends StandardProps<ModalProps, PopoverClassKey> {
  action?: React.Ref<PopoverActions>;
  anchorEl?: null | Element | ((element: Element) => Element);
  anchorOrigin?: PopoverOrigin;
  anchorPosition?: PopoverPosition;
  anchorReference?: 'anchorEl' | 'anchorPosition' | 'none';
  children?: React.ReactNode;
  elevation?: number;
  getContentAnchorEl?: null | ((element: Element) => Element);
  marginThreshold?: number;
  onEnter?: TransitionHandlersProps['onEnter'];
  onEntered?: TransitionHandlersProps['onEntered'];
  onEntering?: TransitionHandlersProps['onEntering'];
  onExit?: TransitionHandlersProps['onExit'];
  onExited?: TransitionHandlersProps['onExited'];
  onExiting?: TransitionHandlersProps['onExiting'];
  open: boolean;
  PaperProps?: Partial<PaperProps>;
  transformOrigin?: PopoverOrigin;
  TransitionComponent?: React.ComponentType<TransitionProps>;
  transitionDuration?: TransitionProps['timeout'] | 'auto';
  TransitionProps?: TransitionProps;
}

interface PopoverOrigin {
  horizontal: 'left' | 'center' | 'right' | number;
  vertical: 'top' | 'center' | 'bottom' | number;
}

interface PopoverPosition {
  top: number;
  left: number;
}

interface PopoverActions {
  updatePosition(): void;
}

type PopoverClassKey = 'root' | 'paper';

/**
 * Popper component for advanced positioning using Popper.js
 * @param props - Popper props
 * @returns Popper React component
 */
function Popper(props: PopperProps): JSX.Element;

interface PopperProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, PopperClassKey> {
  anchorEl?: null | Element | ((element: Element) => Element);
  children: React.ReactNode | ((props: { placement: PopperPlacementType }) => React.ReactNode);
  container?: Element | (() => Element | null) | null;
  disablePortal?: boolean;
  keepMounted?: boolean;
  modifiers?: object;
  open: boolean;
  placement?: PopperPlacementType;
  popperOptions?: object;
  popperRef?: React.Ref<Element>;
  transition?: boolean;
}

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

/**
 * Collapse transition component for height-based animations
 * @param props - Collapse props
 * @returns Collapse React component
 */
function Collapse(props: CollapseProps): JSX.Element;

interface CollapseProps extends StandardProps<TransitionProps, CollapseClassKey> {
  children?: React.ReactNode;
  collapsedHeight?: string | number;
  component?: React.ElementType;
  in?: boolean;
  timeout?: TransitionProps['timeout'] | 'auto';
}

type CollapseClassKey = 'root' | 'entered' | 'hidden' | 'wrapper' | 'wrapperInner';

/**
 * Fade transition component for opacity-based animations
 * @param props - Fade props
 * @returns Fade React component
 */
function Fade(props: FadeProps): JSX.Element;

interface FadeProps extends StandardProps<TransitionProps, FadeClassKey> {
  children?: React.ReactElement<any, any>;
  in?: boolean;
  timeout?: TransitionProps['timeout'];
}

type FadeClassKey = 'root';

/**
 * Grow transition component for scale-based animations
 * @param props - Grow props
 * @returns Grow React component
 */
function Grow(props: GrowProps): JSX.Element;

interface GrowProps extends StandardProps<TransitionProps, GrowClassKey> {
  children?: React.ReactElement<any, any>;
  in?: boolean;
  timeout?: TransitionProps['timeout'] | 'auto';
}

type GrowClassKey = 'root';

/**
 * Slide transition component for directional slide animations
 * @param props - Slide props
 * @returns Slide React component
 */
function Slide(props: SlideProps): JSX.Element;

interface SlideProps extends StandardProps<TransitionProps, SlideClassKey> {
  children?: React.ReactElement<any, any>;
  direction?: 'left' | 'right' | 'up' | 'down';
  in?: boolean;
  timeout?: TransitionProps['timeout'];
}

type SlideClassKey = 'root';

/**
 * Zoom transition component for scale-based animations with different timing
 * @param props - Zoom props
 * @returns Zoom React component
 */
function Zoom(props: ZoomProps): JSX.Element;

interface ZoomProps extends StandardProps<TransitionProps, ZoomClassKey> {
  children?: React.ReactElement<any, any>;
  in?: boolean;
  timeout?: TransitionProps['timeout'];
}

type ZoomClassKey = 'root';

/**
 * HOC that makes dialogs full-screen on mobile devices
 * @param options - Mobile dialog options
 * @returns HOC function
 */
function withMobileDialog<P = {}>(options?: WithMobileDialogOptions): (Component: React.ComponentType<P>) => React.ComponentType<P & WithMobileDialogProps>;

interface WithMobileDialogOptions {
  breakpoint?: Breakpoint;
}

interface WithMobileDialogProps {
  fullScreen: boolean;
}

/**
 * HOC that provides the current breakpoint width to components
 * @param options - Width detection options
 * @returns HOC function
 */
function withWidth<P extends WithWidthProps = WithWidthProps>(options?: WithWidthOptions): (Component: React.ComponentType<P>) => React.ComponentType<Omit<P, keyof WithWidthProps> & Partial<WithWidthProps>>;

interface WithWidthOptions {
  withTheme?: boolean;
  noSSR?: boolean;
  initialWidth?: Breakpoint;
  resizeInterval?: number;
}

interface WithWidthProps {
  width: Breakpoint;
}

import { withMobileDialog, withWidth } from '@material-ui/core';

// Mobile dialog HOC
const ResponsiveDialog = withMobileDialog({ breakpoint: 'xs' })(Dialog);

// Width detection HOC
const ResponsiveComponent = withWidth()(({ width, ...props }) => (
  <div>
    Current breakpoint: {width}
    {width === 'xs' && <MobileLayout />}
    {width !== 'xs' && <DesktopLayout />}
  </div>
));

/**
 * Utility component for forwarding refs to the root element
 * @param props - Root ref props
 * @returns Root ref React component
 */
function RootRef(props: RootRefProps): JSX.Element;

interface RootRefProps {
  rootRef: React.Ref<any>;
  children: React.ReactElement<any, any>;
}

/**
 * Component for providing consistent CSS baseline across browsers
 * @param props - CSS Baseline props
 * @returns CSS Baseline React component
 */
function CssBaseline(props: CssBaselineProps): JSX.Element;

interface CssBaselineProps {
  children?: React.ReactNode;
}

import { CssBaseline } from '@material-ui/core';

// Apply at app root
function App() {
  return (
    <>
      <CssBaseline />
      <AppContent />
    </>
  );
}

/**
 * Experimental hook for media query matching
 * @param query - Media query string
 * @param options - Media query options
 * @returns Boolean indicating if query matches
 */
function unstable_useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;

interface UseMediaQueryOptions {
  defaultMatches?: boolean;
  noSsr?: boolean;
  ssrMatchMedia?: (query: string) => { matches: boolean };
}

import { unstable_useMediaQuery as useMediaQuery } from '@material-ui/core/useMediaQuery';

function ResponsiveComponent() {
  const isMobile = useMediaQuery('(max-width:600px)');
  
  return (
    <div>
      {isMobile ? <MobileView /> : <DesktopView />}
    </div>
  );
}