/** The preferred side of the trigger to render the popover. */
export type UiPopoverSide = 'top' | 'right' | 'bottom' | 'left';
/** The preferred alignment against the trigger. */
export type UiPopoverAlign = 'start' | 'center' | 'end';
/**
 * A floating panel that appears relative to a trigger element. Use for
 * rich content like forms, pickers, or detailed information.
 * @category Overlays
 * @useCases floating panel, picker container, form popup, info panel
 * @keywords popover, popup, floating, panel, overlay, dropdown
 * @related UiTooltip, UiDropdownMenu
 */
export interface UiPopoverProps {
    /**
     * The controlled open state of the popover.
     * - Omit for uncontrolled mode (component manages state internally)
     * - Use `v-model:open` for controlled mode
     * @example
     * ```vue
     * <!-- Uncontrolled (component manages state) -->
     * <UiPopover>...</UiPopover>
     *
     * <!-- Controlled (parent manages state) -->
     * <UiPopover v-model:open="isOpen">...</UiPopover>
     * ```
     */
    open?: boolean;
    /**
     * The modality of the popover.
     *
     * When set to `true`:
     * - Interaction with outside elements is disabled (outside clicks won't trigger underlying UI)
     * - Focus is trapped within the popover while open
     * - Only popover content is visible to screen readers
     *
     * Note: The popover is still **dismissed on outside click**. `modal` controls outside interaction,
     * not whether the popover closes.
     * @default false
     */
    modal?: boolean;
}
/**
 * Props for the UiPopoverTrigger component.
 * The element that opens the popover when clicked.
 */
export interface UiPopoverTriggerProps {
    /**
     * Accessible label for the trigger button.
     * **REQUIRED** when trigger contains only icons or images (no visible text).
     * Applied as `aria-label` attribute.
     */
    ariaLabel?: string;
    /**
     * Render as child element (merges props into slotted element instead of wrapping).
     * Set to `true` when using custom button components like `UiButton`.
     * @default false
     */
    asChild?: boolean;
}
/**
 * Props for the UiPopoverContent component.
 * The floating container for popover content.
 */
export interface UiPopoverContentProps {
    /**
     * The preferred side of the trigger to render against when open.
     * @default 'bottom'
     */
    side?: UiPopoverSide;
    /**
     * The distance in pixels from the trigger.
     * @default 4
     */
    sideOffset?: number;
    /**
     * The preferred alignment against the trigger.
     * @default 'center'
     */
    align?: UiPopoverAlign;
}
/**
 * Emits for the UiPopoverContent component.
 */
export interface UiPopoverContentEmits {
    /**
     * Event emitted when the escape key is pressed.
     * Can be used to prevent closing or add custom behavior.
     */
    (e: 'escapeKeyDown', event: KeyboardEvent): void;
}
