Overlays and Modals

/**
 * Provides dialog behavior and accessibility
 * @param props - Dialog configuration
 * @param ref - Ref to the dialog element
 * @returns Dialog props
 */
function useDialog(props: AriaDialogProps, ref: RefObject<Element>): DialogAria;

interface AriaDialogProps {
  /** Role of the dialog */
  role?: 'dialog' | 'alertdialog';
  /** ID of the dialog */
  id?: string;
  /** Accessible name for the dialog */
  'aria-label'?: string;
  /** ID of element that labels the dialog */
  'aria-labelledby'?: string;
  /** ID of element that describes the dialog */
  'aria-describedby'?: string;
}

interface DialogAria {
  /** Props for the dialog element */
  dialogProps: DOMAttributes<Element>;
  /** Props for the dialog title element */
  titleProps: DOMAttributes<Element>;
}

/**
 * Provides disclosure behavior and accessibility
 * @param props - Disclosure configuration
 * @param ref - Ref to the disclosure element
 * @returns Disclosure props and state
 */
function useDisclosure(props: AriaDisclosureProps, ref: RefObject<Element>): DisclosureAria;

interface AriaDisclosureProps {
  /** Whether the disclosure is expanded */
  isExpanded?: boolean;
  /** Default expanded state (uncontrolled) */
  defaultExpanded?: boolean;
  /** Handler called when expansion changes */
  onExpandedChange?: (isExpanded: boolean) => void;
  /** Whether the disclosure is disabled */
  isDisabled?: boolean;
}

interface DisclosureAria {
  /** Props for the disclosure button */
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the disclosure panel */
  panelProps: DOMAttributes<Element>;
  /** Whether the disclosure is expanded */
  isExpanded: boolean;
}

/**
 * Provides modal behavior and accessibility
 * @param options - Modal configuration options
 * @returns Modal props and state
 */
function useModal(options?: AriaModalOptions): ModalAria;

/**
 * Provides modal overlay behavior
 * @param props - Modal overlay configuration
 * @param state - Modal state
 * @param ref - Ref to the overlay element
 * @returns Modal overlay props
 */
function useModalOverlay(props: AriaModalOverlayProps, state: OverlayTriggerState, ref: RefObject<Element>): ModalOverlayAria;

/**
 * Provides modal provider context
 * @param props - Modal provider configuration
 * @returns Modal provider props and state
 */
function useModalProvider(props: ModalProviderProps): ModalProviderAria;

interface AriaModalOptions {
  /** Whether the modal is open */
  isOpen?: boolean;
  /** Handler called when the modal should close */
  onClose?: () => void;
  /** Whether the modal is keyboard modal */
  isKeyboardDismissDisabled?: boolean;
  /** Whether to disable outside clicks */
  isDismissable?: boolean;
}

interface ModalAria {
  /** Props for the modal element */
  modalProps: DOMAttributes<Element>;
  /** Props for the underlay element */
  underlayProps: DOMAttributes<Element>;
}

interface AriaModalOverlayProps {
  /** Whether the overlay is open */
  isOpen?: boolean;
  /** Handler called when the overlay should close */
  onClose?: () => void;
  /** Whether the overlay is dismissable */
  isDismissable?: boolean;
  /** Whether keyboard dismissal is disabled */
  isKeyboardDismissDisabled?: boolean;
  /** Whether to prevent scrolling */
  shouldCloseOnBlur?: boolean;
}

interface ModalOverlayAria {
  /** Props for the modal overlay element */
  modalProps: DOMAttributes<Element>;
  /** Props for the underlay element */
  underlayProps: DOMAttributes<Element>;
}

/**
 * Provides popover behavior and accessibility
 * @param props - Popover configuration
 * @param state - Popover state
 * @param ref - Ref to the popover element
 * @returns Popover props
 */
function usePopover(props: AriaPopoverProps, state: PopoverState, ref: RefObject<Element>): PopoverAria;

interface AriaPopoverProps {
  /** Type of popover */
  triggerRef: RefObject<Element>;
  /** Whether the popover is non-modal */
  isNonModal?: boolean;
  /** Trigger source for the popover */
  triggerSource?: string;
  /** Whether keyboard dismissal is disabled */
  isKeyboardDismissDisabled?: boolean;
  /** Whether the popover should close on blur */
  shouldCloseOnBlur?: boolean;
  /** Whether to flip placement when space is limited */
  shouldFlip?: boolean;
  /** Boundary element for flipping */
  boundaryElement?: Element;
  /** Scroll ref for repositioning */
  scrollRef?: RefObject<Element>;
  /** Whether the popover should update position */
  shouldUpdatePosition?: boolean;
  /** Arrow boundary offset */
  arrowBoundaryOffset?: number;
  /** Placement of the popover */
  placement?: Placement;
  /** Container padding */
  containerPadding?: number;
  /** Offset from trigger */
  offset?: number;
  /** Cross offset */
  crossOffset?: number;
  /** Whether the popover should close on interact outside */
  shouldCloseOnInteractOutside?: (element: Element) => boolean;
  /** Max height of the popover */
  maxHeight?: number;
  /** Arrow size */
  arrowSize?: number;
  /** Arrow boundary offset */
  arrowBoundaryOffset?: number;
}

interface PopoverAria {
  /** Props for the popover element */
  popoverProps: DOMAttributes<Element>;
  /** Props for the arrow element */
  arrowProps: DOMAttributes<Element>;
  /** Placement that was actually used */
  placement: PlacementAxis;
  /** Arrow props */
  arrowProps: DOMAttributes<Element>;
  /** Props for the underlay element */
  underlayProps: DOMAttributes<Element>;
}

/**
 * Provides overlay behavior and accessibility
 * @param props - Overlay configuration
 * @param ref - Ref to the overlay element
 * @returns Overlay props
 */
function useOverlay(props: AriaOverlayProps, ref: RefObject<Element>): OverlayAria;

/**
 * Provides overlay positioning behavior
 * @param props - Position configuration
 * @param ref - Ref to the overlay element
 * @returns Position props and placement
 */
function useOverlayPosition(props: AriaPositionProps, ref: RefObject<Element>): PositionAria;

/**
 * Provides overlay trigger behavior
 * @param props - Overlay trigger configuration
 * @param state - Overlay trigger state
 * @param ref - Ref to the trigger element
 * @returns Overlay trigger props
 */
function useOverlayTrigger(props: OverlayTriggerProps, state: OverlayTriggerState, ref?: RefObject<Element>): OverlayTriggerAria;

interface AriaOverlayProps {
  /** Whether the overlay is open */
  isOpen?: boolean;
  /** Handler called when the overlay should close */
  onClose?: () => void;
  /** Whether the overlay should close on blur */
  shouldCloseOnBlur?: boolean;
  /** Whether the overlay is dismissable */
  isDismissable?: boolean;
  /** Whether keyboard dismissal is disabled */
  isKeyboardDismissDisabled?: boolean;
  /** Whether to prevent scrolling */
  shouldCloseOnInteractOutside?: (element: Element) => boolean;
}

interface OverlayAria {
  /** Props for the overlay element */
  overlayProps: DOMAttributes<Element>;
  /** Props for the underlay element */
  underlayProps: DOMAttributes<Element>;
}

interface AriaPositionProps extends PositionProps {
  /** Element to position relative to */
  targetRef: RefObject<Element>;
  /** Element to position */
  overlayRef: RefObject<Element>;
  /** Scroll refs for repositioning */
  scrollRef?: RefObject<Element>;
  /** Placement preference */
  placement?: Placement;
  /** Container padding */
  containerPadding?: number;
  /** Offset from target */
  offset?: number;
  /** Cross-axis offset */
  crossOffset?: number;
  /** Whether to flip when space is limited */
  shouldFlip?: boolean;
  /** Boundary element */
  boundaryElement?: Element;
  /** Whether position should update */
  shouldUpdatePosition?: boolean;
  /** Whether the overlay is open */
  isOpen?: boolean;
  /** Handler called when the overlay should close */
  onClose?: () => void;
  /** Max height */
  maxHeight?: number;
  /** Arrow size for popover arrows */
  arrowSize?: number;
  /** Arrow boundary offset */
  arrowBoundaryOffset?: number;
}

interface PositionAria {
  /** Props for the overlay element */
  overlayProps: DOMAttributes<Element>;
  /** Props for the arrow element */
  arrowProps: DOMAttributes<Element>;
  /** Placement that was used */
  placement: PlacementAxis;
  /** Update position manually */
  updatePosition(): void;
}

interface OverlayTriggerProps {
  /** Type of overlay */
  type: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid';
  /** Whether the overlay is open */
  isOpen?: boolean;
  /** Default open state (uncontrolled) */
  defaultOpen?: boolean;
  /** Handler called when open state changes */
  onOpenChange?: (isOpen: boolean) => void;
}

interface OverlayTriggerAria {
  /** Props for the trigger element */
  triggerProps: ButtonHTMLAttributes<HTMLButtonElement>;
  /** Props for the overlay element */
  overlayProps: DOMAttributes<Element>;
}

/**
 * Provides tooltip behavior and accessibility
 * @param props - Tooltip configuration
 * @param state - Tooltip trigger state
 * @returns Tooltip props
 */
function useTooltip(props: AriaTooltipProps, state: TooltipTriggerState): TooltipAria;

/**
 * Provides tooltip trigger behavior
 * @param props - Tooltip trigger configuration
 * @param state - Tooltip trigger state
 * @param ref - Ref to the trigger element
 * @returns Tooltip trigger props
 */
function useTooltipTrigger(props: TooltipTriggerProps, state: TooltipTriggerState, ref?: RefObject<Element>): TooltipTriggerAria;

interface AriaTooltipProps {
  /** Whether the tooltip is open */
  isOpen?: boolean;
  /** ID for the tooltip */
  id?: string;
}

interface TooltipAria {
  /** Props for the tooltip element */
  tooltipProps: DOMAttributes<Element>;
}

interface TooltipTriggerProps {
  /** Whether the tooltip is disabled */
  isDisabled?: boolean;
  /** Delay before showing tooltip */
  delay?: number;
  /** Close delay */
  closeDelay?: number;
  /** Trigger events */
  trigger?: 'focus' | 'focus+hover';
  /** Whether the tooltip is open */
  isOpen?: boolean;
  /** Default open state (uncontrolled) */
  defaultOpen?: boolean;
  /** Handler called when open state changes */
  onOpenChange?: (isOpen: boolean) => void;
}

interface TooltipTriggerAria {
  /** Props for the trigger element */
  triggerProps: DOMAttributes<Element>;
  /** Props for the tooltip element */
  tooltipProps: DOMAttributes<Element>;
}

/**
 * Provides toast behavior and accessibility
 * @param props - Toast configuration
 * @param state - Toast state
 * @param ref - Ref to the toast element
 * @returns Toast props
 */
function useToast(props: AriaToastProps, state: ToastState, ref: RefObject<Element>): ToastAria;

/**
 * Provides toast region behavior for managing multiple toasts
 * @param props - Toast region configuration
 * @param state - Toast region state
 * @param ref - Ref to the toast region element
 * @returns Toast region props
 */
function useToastRegion(props: AriaToastRegionProps, state: ToastRegionState, ref: RefObject<Element>): ToastRegionAria;

interface AriaToastProps {
  /** Toast priority level */
  priority?: 'low' | 'normal' | 'high';
  /** Whether the toast should auto-dismiss */
  shouldCloseOnAction?: boolean;
  /** Handler called when the toast is closed */
  onClose?: () => void;
}

interface ToastAria {
  /** Props for the toast element */
  toastProps: DOMAttributes<Element>;
  /** Props for the title element */
  titleProps: DOMAttributes<Element>;
  /** Props for the description element */
  descriptionProps: DOMAttributes<Element>;
  /** Props for the close button */
  closeButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
}

interface AriaToastRegionProps {
  /** Accessible label for the toast region */
  'aria-label'?: string;
  /** ID of element that labels the toast region */
  'aria-labelledby'?: string;
}

interface ToastRegionAria {
  /** Props for the toast region element */
  regionProps: DOMAttributes<Element>;
}

/**
 * Provides scroll prevention behavior
 * @param options - Scroll prevention options
 * @returns Scroll prevention state
 */
function usePreventScroll(options?: { isDisabled?: boolean }): void;

/**
 * Button for dismissing overlays
 */
function DismissButton(props: DismissButtonProps): JSX.Element;

/**
 * Provider for modal context
 */  
function ModalProvider(props: { children: ReactNode }): JSX.Element;

/**
 * Base overlay component
 */
function Overlay(props: OverlayProps): JSX.Element;

/**
 * Container for overlay portals
 */
function OverlayContainer(props: OverlayContainerProps): JSX.Element;

/**
 * Provider for overlay context
 */
function OverlayProvider(props: { children: ReactNode }): JSX.Element;

/**
 * Portal provider (marked as unsafe)
 */
function UNSAFE_PortalProvider(props: { children: ReactNode; getContainer?: () => Element }): JSX.Element;

interface DismissButtonProps {
  /** Handler called when button is pressed */
  onDismiss?: () => void;
}

interface OverlayProps {
  /** Children to render in overlay */
  children: ReactNode;
  /** Whether the overlay is open */
  isOpen?: boolean;
  /** Container to render overlay in */
  container?: Element;
  /** Handler called when overlay should close */
  onClose?: () => void;
}

interface OverlayContainerProps {
  /** Container element to render portals in */
  portalContainer?: Element;
  /** Children to render */
  children: ReactNode;
}

type Placement = 
  | 'bottom' 
  | 'bottom left' 
  | 'bottom right' 
  | 'bottom start' 
  | 'bottom end'
  | 'top' 
  | 'top left' 
  | 'top right' 
  | 'top start' 
  | 'top end'
  | 'left' 
  | 'left top' 
  | 'left bottom'
  | 'start' 
  | 'start top' 
  | 'start bottom'
  | 'right' 
  | 'right top' 
  | 'right bottom'
  | 'end' 
  | 'end top' 
  | 'end bottom';

type PlacementAxis = 'top' | 'bottom' | 'left' | 'right' | 'center';

interface OverlayTriggerState {
  /** Whether the overlay is open */
  isOpen: boolean;
  /** Set the open state */
  setOpen(isOpen: boolean): void;
  /** Open the overlay */
  open(): void;
  /** Close the overlay */
  close(): void;
  /** Toggle the overlay */
  toggle(): void;
}

interface PopoverState extends OverlayTriggerState {
  /** Trigger source */
  triggerSource?: string;
  /** Set trigger source */
  setTriggerSource(source: string): void;
}

interface TooltipTriggerState extends OverlayTriggerState {
  /** Whether the tooltip is immediately open */
  isWarmupFinished: boolean;
  /** Warm up the tooltip globally */
  warmUp(): void;
  /** Cool down the tooltip globally */
  coolDown(): void;
}

interface ToastState {
  /** Whether the toast is visible */
  isVisible: boolean;
  /** Whether the toast is paused */
  isPaused: boolean;
  /** Remaining time before auto-dismiss */
  remainingTime: number;
  /** Pause the toast */
  pause(): void;
  /** Resume the toast */
  resume(): void;
  /** Close the toast */
  close(): void;
}

interface ToastRegionState {
  /** List of toasts in the region */
  toasts: Toast[];
  /** Add a toast */
  add(toast: Toast): void;
  /** Remove a toast */
  remove(key: string): void;
  /** Pause all toasts */
  pauseAll(): void;
  /** Resume all toasts */
  resumeAll(): void;
}

interface Toast {
  /** Unique key for the toast */
  key: string;
  /** Toast content */
  content: ReactNode;
  /** Toast priority */
  priority?: 'low' | 'normal' | 'high';
  /** Auto-dismiss timeout */
  timeout?: number;
  /** Handler called when closed */
  onClose?: () => void;
}

interface PositionProps {
  /** Container padding */
  containerPadding?: number;
  /** Offset from target */
  offset?: number;
  /** Cross-axis offset */
  crossOffset?: number;
  /** Whether to flip placement */
  shouldFlip?: boolean;
  /** Boundary element */
  boundaryElement?: Element;
  /** Max height */
  maxHeight?: number;
}