/**
 * @file usePopover.tsx
 * @input Uses useLayer, useFocusTrap, React hooks
 * @output Exports usePopover hook for popover dialogs with focus trapping
 * @position Higher-level layer utility; used by DatePicker, Combobox, etc.
 *
 * Combines popover layer behavior with focus trap for dialog-like popovers.
 * Use this for interactive popover content that should trap focus.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Popover/index.ts
 */
import React, { type ReactNode } from 'react';
import { type ContextRenderProps } from '../Layer/useLayer';
import type { StyleXStyles } from '@stylexjs/stylex';
/**
 * Options for usePopover
 */
export interface UsePopoverOptions {
    /**
     * Callback fired when popover is shown.
     * Wrap in useCallback for stable identity.
     */
    onShow?: () => void;
    /**
     * Callback fired when popover is hidden.
     * Use this to return focus to the trigger element.
     * Wrap in useCallback for stable identity.
     */
    onHide?: () => void;
    /**
     * StyleX styles applied to the popover's content wrapper.
     * Merges after the surface styles (when hasSurface is true), so these
     * can override background, radius, etc.
     *
     * For styles on the layer's positioned element (e.g., animations using
     * `:popover-open`), pass `xstyle` via the `render()` call's props instead.
     */
    xstyle?: StyleXStyles;
    /**
     * Whether clicking outside should dismiss the popover.
     * @default true
     */
    hasLightDismiss?: boolean;
    /**
     * Whether pressing Escape dismisses the popover.
     *
     * Takes effect together with `hasLightDismiss: false`: with light dismiss
     * on, the native popover uses `popover="auto"`, whose browser-level light
     * dismiss also closes on Escape, so Escape handling stays registered to
     * keep topmost-only dismissal intact. Set both to `false` for
     * explicit-dismiss-only surfaces like onboarding coachmarks.
     *
     * @default true
     */
    hasEscapeDismiss?: boolean;
    /**
     * Whether to automatically focus the first focusable element when opened.
     * @default true
     */
    hasAutoFocus?: boolean;
    /**
     * Whether to include a hidden close button for accessibility.
     * The button appears when keyboard users tab past the last element.
     * @default true
     */
    hasCloseButton?: boolean;
    /**
     * Label for the hidden close button.
     * @default "Close popover"
     */
    closeButtonLabel?: string;
    /**
     * Accessible label for the dialog.
     * Required for screen readers to announce the dialog purpose
     * (only applies when `role` is `'dialog'`).
     */
    dialogLabel?: string;
    /**
     * ARIA role stamped on the popover content wrapper.
     *
     * - `'dialog'` (default): the wrapper is a `role="dialog"` and, when
     *   `isModal` is true, carries `aria-modal`. Use for genuine dialog content.
     * - `'none'`: the wrapper carries no role or `aria-modal`, so the popup's own
     *   content role (e.g. a child `role="listbox"` or `role="menu"`) is the
     *   exposed semantics. Use for comboboxes, listboxes, and menus — their
     *   trigger keeps DOM focus, so announcing an unnamed modal dialog around
     *   them is incorrect.
     *
     * @default 'dialog'
     */
    role?: 'dialog' | 'none';
    /**
     * Whether the dialog is modal (`aria-modal`). Only applies when `role` is
     * `'dialog'`. Set to `false` for non-modal dialogs that do not inert the rest
     * of the page.
     *
     * @default true
     */
    isModal?: boolean;
    /**
     * Whether to apply the default popover surface (background, border-radius,
     * box-shadow) to the content wrapper.
     *
     * Set to false when the popover content provides its own surface styling
     * (e.g., mega menus with custom layouts). If you find yourself opting out,
     * consider whether useLayer is a better fit.
     *
     * @default true
     */
    hasSurface?: boolean;
}
/**
 * Return type for usePopover
 */
export interface UsePopoverReturn {
    /**
     * Ref callback to attach to the trigger element.
     * Sets up CSS anchor positioning.
     */
    triggerRef: (el: HTMLElement | null) => void;
    /**
     * Ref for the popover content container (used internally for focus trapping).
     * You typically don't need to use this directly - the render function
     * automatically wraps content in a focus trap container.
     */
    contentRef: React.RefObject<HTMLDivElement | null>;
    /**
     * The CSS anchor name to use for positioning.
     * Use when you need to set anchorName manually (e.g., display:contents wrapper).
     */
    anchorId: string;
    /**
     * Show the popover.
     * @param options.skipAutoFocus - If true, don't auto-focus the first element.
     *   Useful when triggered by mouse click on an input that should retain focus.
     */
    show: (options?: {
        skipAutoFocus?: boolean;
    }) => void;
    /**
     * Hide the popover
     */
    hide: () => void;
    /**
     * Toggle the popover open/closed
     */
    toggle: () => void;
    /**
     * Whether the popover is currently open
     */
    isOpen: boolean;
    /**
     * Unique ID for aria-describedby or aria-controls
     */
    id: string;
    /**
     * Render function for popover content.
     * Automatically wraps content in a focus trap container with a hidden close button.
     *
     * @example
     * ```
     * {popover.render(
     *   <Calendar />,
     *   { placement: 'below', alignment: 'start' }
     * )}
     * ```
     */
    render: (children: ReactNode, props?: ContextRenderProps) => ReactNode;
    /**
     * ARIA attributes to spread on the trigger element
     */
    triggerProps: {
        'aria-haspopup': 'dialog' | 'true';
        'aria-expanded': boolean;
        'aria-controls': string;
    };
}
/**
 * Hook for creating popover dialogs with focus trapping.
 *
 * Combines:
 * - `useLayer` for popover positioning using CSS anchor positioning
 * - `useFocusTrap` for trapping focus within the popover content
 * - Auto-focus first element on open
 * - Escape key to close (configurable via hasEscapeDismiss)
 * - Hidden close button that reveals on focus for accessibility
 *
 * The render function automatically wraps your content in a focus trap container
 * and appends a hidden close button. The button appears at the end of the popover,
 * is visually hidden until focused, then shows a tooltip-like message (default: "Close popover").
 *
 * @example
 * ```
 * function DatePickerExample() {
 *   const inputRef = useRef<HTMLInputElement>(null);
 *   const popover = usePopover({
 *     onHide: () => inputRef.current?.focus(),
 *     closeButtonLabel: 'Close calendar',
 *   });
 *   return (
 *     <>
 *       <input ref={inputRef} />
 *       <button
 *         ref={popover.triggerRef}
 *         onClick={popover.toggle}
 *         {...popover.triggerProps}>
 *         Open Calendar
 *       </button>
 *       {popover.render(
 *         <Calendar />,
 *         { placement: 'below', alignment: 'start' }
 *       )}
 *     </>
 *   );
 * }
 * ```
 */
export declare function usePopover(options?: UsePopoverOptions): UsePopoverReturn;
//# sourceMappingURL=usePopover.d.ts.map