Overlay System

/**
 * Modal dialog with backdrop, close controls, and customizable sections
 * @param props - Dialog configuration, content, and event handlers
 */
function Dialog(props: DialogProps): JSX.Element;

/**
 * Multi-step dialog with navigation and step management
 * @param props - Multi-step dialog configuration and steps
 */
function MultistepDialog(props: MultistepDialogProps): JSX.Element;

/**
 * Dialog body section with scrollable content area
 * @param props - Body content and scroll configuration
 */
function DialogBody(props: DialogBodyProps): JSX.Element;

/**
 * Dialog footer section with action buttons and layout
 * @param props - Footer content and layout options
 */
function DialogFooter(props: DialogFooterProps): JSX.Element;

interface DialogProps extends OverlayableProps, OverlayLifecycleProps, Props {
  autoFocus?: boolean;
  canEscapeKeyClose?: boolean;
  canOutsideClickClose?: boolean;
  enforceFocus?: boolean;
  icon?: IconName | MaybeElement;
  isCloseButtonShown?: boolean;
  lazy?: boolean;
  portalClassName?: string;
  portalContainer?: HTMLElement;
  shouldReturnFocusOnClose?: boolean;
  title?: React.ReactNode;
  transitionName?: string;
  usePortal?: boolean;
  children?: React.ReactNode;
}

interface MultistepDialogProps extends DialogProps {
  initialStepIndex?: number;
  navigationPosition?: MultistepDialogNavPosition;
  nextButtonProps?: Partial<ButtonProps>;
  finalButtonProps?: Partial<ButtonProps>;
  backButtonProps?: Partial<ButtonProps>;
  onChange?: (newDialogStepId: DialogStepId, prevDialogStepId: DialogStepId | undefined, event: React.MouseEvent<HTMLElement>) => void;
  onClose?: (event?: React.SyntheticEvent<HTMLElement>) => void;
  resetOnClose?: boolean;
  showCloseButtonInFooter?: boolean;
  children?: React.ReactElement<DialogStepProps> | Array<React.ReactElement<DialogStepProps>>;
}

type MultistepDialogNavPosition = "left" | "top" | "right";
type DialogStepId = string | number;

import { Dialog, DialogBody, DialogFooter, MultistepDialog, DialogStep, Button } from "@blueprintjs/core";

// Basic dialog
<Dialog
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Confirm Action"
  icon="info-sign"
>
  <DialogBody>
    Are you sure you want to delete this item?
  </DialogBody>
  <DialogFooter
    actions={
      <>
        <Button onClick={() => setIsOpen(false)}>Cancel</Button>
        <Button intent="danger" onClick={handleDelete}>Delete</Button>
      </>
    }
  />
</Dialog>

// Multi-step dialog
<MultistepDialog
  isOpen={wizardOpen}
  onClose={() => setWizardOpen(false)}
  title="Setup Wizard"
>
  <DialogStep id="step1" title="Basic Info" panel={<BasicInfoPanel />} />
  <DialogStep id="step2" title="Configuration" panel={<ConfigPanel />} />
  <DialogStep id="step3" title="Review" panel={<ReviewPanel />} />
</MultistepDialog>

/**
 * Floating panel positioned relative to a trigger element
 * @param props - Popover positioning, content, and interaction configuration
 */
function Popover(props: PopoverProps): JSX.Element;

/**
 * Simple tooltip with text content and positioning
 * @param props - Tooltip text and positioning options
 */
function Tooltip(props: TooltipProps): JSX.Element;

interface PopoverProps extends OverlayableProps, PopoverSharedProps, Props {
  backdropProps?: React.HTMLProps<HTMLDivElement>;
  boundary?: PopperBoundary;
  captureDismiss?: boolean;
  defaultIsOpen?: boolean;
  disabled?: boolean;
  fill?: boolean;
  hoverCloseDelay?: number;
  hoverOpenDelay?: number;
  inheritDarkTheme?: boolean;
  interactionKind?: PopoverInteractionKind;
  lazy?: boolean;
  matchTargetWidth?: boolean;
  minimal?: boolean;
  modifiers?: PopperModifierOverrides;
  onInteraction?: (nextOpenState: boolean, event?: React.SyntheticEvent<HTMLElement>) => void;
  openOnTargetFocus?: boolean;
  placement?: Placement;
  popoverClassName?: string;
  portalClassName?: string;
  portalContainer?: HTMLElement;
  renderTarget?: (props: PopoverTargetProps) => React.ReactNode;
  shouldReturnFocusOnClose?: boolean;
  targetTagName?: keyof JSX.IntrinsicElements;
  transitionDuration?: number;
  usePortal?: boolean;
  content?: React.ReactNode;
  children?: React.ReactNode;
}

interface TooltipProps extends Omit<PopoverProps, "content" | "interactionKind"> {
  content: React.ReactNode;
  compact?: boolean;
}

enum PopoverInteractionKind {
  CLICK = "click",
  CLICK_TARGET_ONLY = "click-target",
  HOVER = "hover", 
  HOVER_TARGET_ONLY = "hover-target"
}

/**
 * Slide-out panel that overlays the main content area
 * @param props - Drawer positioning, size, and content configuration
 */
function Drawer(props: DrawerProps): JSX.Element;

interface DrawerProps extends OverlayableProps, OverlayLifecycleProps, Props {
  autoFocus?: boolean;
  canEscapeKeyClose?: boolean;
  canOutsideClickClose?: boolean;
  enforceFocus?: boolean;
  hasBackdrop?: boolean;
  icon?: IconName | MaybeElement;
  isCloseButtonShown?: boolean;
  lazy?: boolean;
  position?: Position;
  portalClassName?: string;
  shouldReturnFocusOnClose?: boolean;
  size?: number | string;
  title?: React.ReactNode;
  transitionDuration?: number;
  transitionName?: string;
  usePortal?: boolean;
  children?: React.ReactNode;
}

enum DrawerSize {
  SMALL = "360px",
  STANDARD = "50%",
  LARGE = "90%"
}

/**
 * Base overlay component with backdrop and portal management
 * @param props - Overlay behavior and lifecycle configuration
 */
function Overlay(props: OverlayProps): JSX.Element;

/**
 * Enhanced overlay component with improved performance
 * @param props - Enhanced overlay configuration
 */
function Overlay2(props: Overlay2Props): JSX.Element;

interface OverlayProps extends OverlayableProps, OverlayLifecycleProps, Props {
  autoFocus?: boolean;
  backdropClassName?: string;
  backdropProps?: React.HTMLProps<HTMLDivElement>;
  canEscapeKeyClose?: boolean;
  canOutsideClickClose?: boolean;
  containerClassName?: string;
  enforceFocus?: boolean;
  hasBackdrop?: boolean;
  lazy?: boolean;
  portalClassName?: string;
  portalContainer?: HTMLElement;
  scrollContainer?: HTMLElement;
  shouldReturnFocusOnClose?: boolean;
  transitionDuration?: number;
  transitionName?: string;
  usePortal?: boolean;
  children?: React.ReactNode;
}

interface OverlayableProps {
  isOpen: boolean;
  onClose?: (event?: React.SyntheticEvent<HTMLElement>) => void;
}

/**
 * Context menu component with dynamic positioning and interaction handling
 * @param props - Context menu content and trigger configuration
 */
function ContextMenu(props: ContextMenuProps): JSX.Element;

/**
 * Popover-based context menu implementation
 * @param props - Context menu popover configuration
 */
function ContextMenuPopover(props: ContextMenuPopoverProps): JSX.Element;

/**
 * Shows a context menu at the specified coordinates
 * @param menu - Menu content to display
 * @param offset - Position coordinates and options
 * @param onClose - Callback when menu closes
 * @returns Context menu instance
 */
function showContextMenu(
  menu: React.ReactElement<MenuProps>,
  offset: { left: number; top: number },
  onClose?: () => void
): ContextMenuInstance | undefined;

/**
 * Hides the currently displayed context menu
 */
function hideContextMenu(): void;

interface ContextMenuProps extends Props {
  content?: React.ReactNode;
  disabled?: boolean;
  popoverProps?: Partial<PopoverProps>;
  tagName?: keyof JSX.IntrinsicElements;
  children?: React.ReactNode;
}

interface ShowContextMenuOptions {
  left: number;
  top: number;
  onClose?: () => void;
}

/**
 * Renders children in a portal outside the current DOM hierarchy
 * @param props - Portal target and content configuration
 */
function Portal(props: PortalProps): React.ReactPortal | null;

interface PortalProps extends Props {
  container?: HTMLElement;
  onChildrenMount?: () => void;
  stopPropagationEvents?: string[];
  children?: React.ReactNode;
}

import { 
  Popover, 
  Tooltip, 
  Drawer, 
  ContextMenu, 
  showContextMenu, 
  Portal, 
  Menu, 
  MenuItem 
} from "@blueprintjs/core";

// Popover with custom content
<Popover
  content={
    <div style={{ padding: 20 }}>
      <h4>Popover Content</h4>
      <p>This is custom popover content.</p>
    </div>
  }
  position="bottom"
>
  <Button text="Show Popover" />
</Popover>

// Simple tooltip
<Tooltip content="This is a tooltip">
  <Button icon="info-sign" />
</Tooltip>

// Drawer panel
<Drawer
  isOpen={drawerOpen}
  onClose={() => setDrawerOpen(false)}
  title="Settings"
  size={DrawerSize.SMALL}
>
  <div style={{ padding: 20 }}>
    Drawer content goes here
  </div>
</Drawer>

// Context menu
<ContextMenu
  content={
    <Menu>
      <MenuItem text="Edit" icon="edit" />
      <MenuItem text="Delete" icon="trash" intent="danger" />
    </Menu>
  }
>
  <div>Right-click me</div>
</ContextMenu>

// Programmatic context menu
const handleRightClick = (event: React.MouseEvent) => {
  showContextMenu(
    <Menu>
      <MenuItem text="Option 1" />
      <MenuItem text="Option 2" />
    </Menu>,
    { left: event.clientX, top: event.clientY }
  );
};

// Portal usage
<Portal>
  <div>This renders at document.body</div>
</Portal>

// Placement options for positioned overlays
type Placement = 
  | "auto"
  | "auto-start" 
  | "auto-end"
  | "top"
  | "top-start"
  | "top-end"
  | "bottom"
  | "bottom-start"
  | "bottom-end"
  | "right"
  | "right-start"
  | "right-end"
  | "left"
  | "left-start"
  | "left-end";

// Popper.js boundary types
type PopperBoundary = "scrollParent" | "viewport" | "window" | HTMLElement;

// Popover target props
interface PopoverTargetProps {
  "aria-haspopup": string;
  className: string;
  onClick?: (event: React.MouseEvent<HTMLElement>) => void;
  onKeyDown?: (event: React.KeyboardEvent<HTMLElement>) => void;
  onMouseEnter?: (event: React.MouseEvent<HTMLElement>) => void;
  onMouseLeave?: (event: React.MouseEvent<HTMLElement>) => void;
  tabIndex?: number;
}