import { type ComponentProps, type CSSProperties, type KeyboardEventHandler, type ReactNode, type SyntheticEvent, type FocusEventHandler } from 'react';
type Side = 'top' | 'right' | 'bottom' | 'left';
type Alignment = 'start' | 'end';
/**
 * Placement options for the popover relative to the trigger element.
 * Follows the same pattern as Floating UI but with our own type definition.
 */
export type PopoverPlacement = Side | `${Side}-${Alignment}`;
/**
 * Options to control the behavior of the Popover, which be used to render the Trigger and the Popover Content
 */
export type PopoverRenderOptions = {
    /**
     * If the Popover is opening, close it
     * If the Popover is closed, open it
     */
    togglePopover: (event?: SyntheticEvent) => void;
    /**
     * Open the Popover
     */
    openPopover: (event?: SyntheticEvent) => void;
    /**
     * Close the Popover
     */
    closePopover: (event?: SyntheticEvent) => void;
    /**
     * Current state of the Popover
     */
    isPopoverOpen: boolean;
    /**
     * This is required parameter to make the Trigger and the Popover automatically align with each other.
     *
     * @param element - The trigger element, must be an HTMLElement like button or div.
     *
     * @example
     * ```tsx
     * <Popover renderTrigger={({setTriggerRef}) => {
     *   return <button ref={setTriggerRef} />
     * }} .../>
     * ```
     */
    setTriggerRef: (element: HTMLElement | null) => void;
    /**
     * This is an optional parameter but should be used in the Trigger Element to open the Popover when user press `Up` or `Down` when focusing on the Trigger element
     *
     * @example
     * ```tsx
     * <Popover renderTrigger={({handleTriggerKeyDown}) => {
     *   return <button onKeyDown={handleTriggerKeyDown} />
     * }} .../>
     * ```
     */
    handleTriggerKeyDown: KeyboardEventHandler<HTMLElement>;
    /**
     * This is an optional parameter but should be used in the Trigger Element to handle blur events with smart blur detection
     *
     * @example
     * ```tsx
     * <Popover renderTrigger={({handleTriggerBlur}) => {
     *   return <button onBlur={handleTriggerBlur} />
     * }} .../>
     * ```
     */
    handleTriggerBlur: FocusEventHandler<HTMLElement>;
};
/**
 * Props for the Popover component
 */
export type PopoverProps = {
    /**
     * The function to render a trigger element, you must use the options params to control its behavior.
     *
     * @param options - Options to control the behavior of the Popover.
     */
    renderTrigger: (options: PopoverRenderOptions) => ReactNode;
    /**
     * The content of the Popover.
     * This is the content inside the popover, not the popover itself.
     */
    renderContent: (options: PopoverRenderOptions) => ReactNode;
    /**
     * The open state of the Popover.
     * You only need to use this prop if you want to control the Popover programmatically
     *
     * @default false
     */
    open?: boolean;
    /**
     * Callback fired when the open state of the Popover changes.
     *
     * @param open - The new open state of the Popover.
     */
    onOpenStateChanged?: (open: boolean) => void;
    /**
     * This callback function will be called when the Popover opened.
     * The default action is focusing on the Popover.
     * You can prevent that action by using `event.preventDefault()` in the callback function.
     *
     * @param event - The trigger event which makes the Popover open, this param can be undefined if you use `toggle` or
     * `open` without passing the event parameter. If you don't pass the event, you can't prevent the default action.
     */
    onOpen?: (event?: SyntheticEvent) => void;
    /**
     * This callback function will be called with the Popover closed.
     * The default action is focusing on the Trigger.
     * You can prevent that action by using `event.preventDefault()` in the callback function.
     *
     * @param event - The trigger event which makes the Popover close, this param can be undefined if you use `toggle` or
     * `close` without passing the event parameter. If you don't pass the event, you can't prevent the default action.
     */
    onClose?: (event?: SyntheticEvent) => void;
    /**
     * The flag to enable or disable autofocus on the trigger element when the Popover closes.
     *
     * @default true - By default, it will automatically focus on the trigger element when the Popover closes.
     */
    enableAutoFocusOnTrigger?: boolean;
    /**
     * The flag to enable or disable autofocus on the popover element when the Popover opens.
     *
     * @default true - By default, it will automatically focus on the popover element when the popover opens.
     */
    enableAutoFocusOnPopover?: boolean;
    /**
     * The props for the popover content element.
     *
     * @default {}
     */
    contentProps?: Pick<ComponentProps<'div'>, 'className'> & {
        /**
         * The tab index of the popover content element.
         * Please note if you set this prop, it may cause the incorrect focus behavior when `enableAutoFocusOnPopover` is true.
         * You should only set this prop with `enableAutoFocusOnPopover` is false, or the customize focus behavior.
         *
         * @default 0
         */
        tabIndex?: ComponentProps<'div'>['tabIndex'];
    };
    /**
     * The minimum width of the popover. Default is the width of the trigger element.
     */
    minWidth?: CSSProperties['minWidth'];
    /**
     * The maximum height of the popover
     */
    maxHeight?: CSSProperties['maxHeight'];
    /**
     * Whether to constrain the popover content width to exactly match the trigger element width.
     * When enabled, both minWidth and maxWidth will be set to the trigger width.
     *
     * @default false
     */
    enableConstrainedContentWidth?: boolean;
    /**
     * The DOM node where the popover should be rendered.
     *
     * If provided, the popover is rendered inside this node. Otherwise, a suitable
     * DOM node is chosen automatically.
     */
    targetDOMNode?: HTMLElement | null;
    /**
     * Enable auto unmounting of the popover content when it's not displayed.
     * When true, the popover content will return null instead of hiding via CSS.
     *
     * @default true
     */
    enableAutoUnmount?: boolean;
    /**
     * Callback fired when the user blurs away from the trigger element or popover content.
     * This implements smart blur detection - only fires when focus leaves both the trigger and popover.
     *
     * @param event - The blur event from the trigger element
     */
    onBlur?: FocusEventHandler<HTMLElement>;
    /**
     * Allowed placements for the popover relative to the trigger element.
     * When provided, the popover will try each placement in order until it finds one that fits within the viewport.
     *
     * @default ['bottom-start', 'bottom-end', 'top-start', 'top-end']
     *
     * @example
     * ```tsx
     * // Try bottom-start first, fallback to top-start
     * <Popover allowedPlacements={['bottom-start', 'top-start']}>
     *   ...
     * </Popover>
     *
     * // Allow all bottom placements
     * <Popover allowedPlacements={['bottom', 'bottom-start', 'bottom-end']}>
     *   ...
     * </Popover>
     * ```
     */
    allowedPlacements?: PopoverPlacement[];
    /**
     * Whether to enable viewport constraint for the popover content.
     * When enabled, the popover will be constrained to fit within the viewport and may become scrollable.
     * When disabled, the popover content can overflow the viewport boundaries.
     *
     * This is useful for components like DatePicker where you want the calendar to display fully
     * even in constrained spaces, rather than being forced to scroll.
     *
     * @default true - By default, the popover content is constrained to the viewport for accessibility
     *
     * @example
     * ```tsx
     * // Default behavior - content constrained to viewport
     * <Popover enableViewportConstraint={true}>
     *   ...
     * </Popover>
     *
     * // Allow content to overflow viewport
     * <Popover enableViewportConstraint={false}>
     *   ...
     * </Popover>
     * ```
     */
    enableViewportConstraint?: boolean;
    /**
     * Enable automatic portal target resolution for nested Popover scenarios.
     * Automatically handles ShadowDOM compatibility and nested context detection.
     * When enabled and the component is nested inside another Popover, automatically
     * uses getTargetDomNode utility for portal target resolution.
     *
     * This prop is intended for internal MFUI components like BasePicker and BaseRangePicker.
     *
     * @internal
     *
     * @default false
     */
    enableAutomaticPortalTargetResolution?: boolean;
    /**
     * Enable centered layout on narrow viewport (< 600px).
     * When enabled, the popover will be centered horizontally on the screen
     * with 14px margins on both sides, instead of being positioned relative to the trigger.
     *
     * This is useful for preventing content from being cut off on narrow viewports.
     *
     * @default false
     *
     * @example
     * ```tsx
     * // Enable centered layout on narrow viewport
     * <Popover enableCenteredLayoutOnNarrowViewport={true}>
     *   ...
     * </Popover>
     * ```
     */
    enableCenteredLayoutOnNarrowViewport?: boolean;
};
export {};