/**
 * @file useHoverCard.ts
 * @input Uses useLayer, React hooks
 * @output Exports useHoverCard hook for hover/focus triggered layers
 * @position Layer hook; builds on useLayer for hover card behavior
 *
 * SYNC: When modified, update:
 * - /packages/core/src/HoverCard/index.ts
 */
import { type ReactNode, type RefCallback } from 'react';
import { type ContextRenderProps, type LayerAlignment, type LayerPlacement } from '../Layer/useLayer';
/**
 * Focus trigger behavior for hover cards
 */
export type HoverCardFocusTrigger = 'auto' | 'always' | 'never';
export interface HoverCardOptions {
    /**
     * Position placement relative to anchor
     * @default 'above'
     */
    placement?: LayerPlacement;
    /**
     * Alignment along the placement axis
     * @default 'center'
     */
    alignment?: LayerAlignment;
    /**
     * Delay before showing on hover (ms)
     * @default 300
     */
    delay?: number;
    /**
     * Delay before hiding after mouse/focus leave (ms)
     * @default 200
     */
    hideDelay?: number;
    /**
     * When to trigger on focus:
     * - `auto`: Only if element is naturally focusable
     * - `always`: Always attach focus listeners
     * - `never`: Never attach focus listeners (for composite widgets)
     *
     * @default 'auto'
     */
    focusTrigger?: HoverCardFocusTrigger;
    /**
     * Whether the hover card is enabled.
     * When false, hover/focus triggers are disabled.
     *
     * @default true
     */
    isEnabled?: boolean;
    /**
     * Accessible name for the hover card popup.
     *
     * When provided, the popup is exposed to assistive technology as a named
     * `role="dialog"`. When omitted, the popup falls back to `role="group"` —
     * a group may validly be unnamed, an unnamed dialog may not.
     */
    label?: string;
    /**
     * Controlled open state. When provided, overrides hover/focus triggers:
     * - `true`: force-show the hover card (hover/focus hide is suppressed)
     * - `false`: force-hide the hover card
     * - `undefined`: uncontrolled — hover/focus triggers manage visibility
     */
    isOpen?: boolean;
    /**
     * Whether the hover card should be shown on mount.
     * The hover card is still dismissible — this just opens it initially.
     */
    isDefaultOpen?: boolean;
    /**
     * Callback fired when hover card is shown.
     * Wrap in useCallback for stable identity.
     */
    onShow?: () => void;
    /**
     * Callback fired when hover card is hidden.
     * Wrap in useCallback for stable identity.
     */
    onHide?: () => void;
}
export interface HoverCardReturn {
    /**
     * Combined ref that sets both position and interaction on the same element.
     * Shorthand for calling both positionRef and interactionRef.
     */
    ref: RefCallback<HTMLElement>;
    /**
     * Ref for the positioning anchor element.
     * Injects anchorName style for CSS anchor positioning.
     */
    positionRef: RefCallback<HTMLElement>;
    /**
     * Ref for the interaction element.
     * Attaches hover/focus event listeners via addEventListener.
     * Can be the same element as positionRef or different.
     */
    interactionRef: RefCallback<HTMLElement>;
    /**
     * The CSS anchor name to use for positioning.
     * Use this when you need to set anchorName manually (e.g., display:contents wrapper).
     */
    anchorId: string;
    /**
     * ID for aria-describedby on the trigger element.
     * Caller should compose with other IDs using mergeIds utility.
     */
    describedBy: string;
    /**
     * Render function for hover card content.
     * Returns anchor-positioned popover element.
     *
     * `positioning` is excluded: the hover card always derives its position
     * from placement/alignment, so accepting the custom opt-out here would be
     * a silent no-op.
     */
    renderHoverCard: (children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode;
    /**
     * Imperatively show the hover card (bypassing hover delay).
     */
    show: () => void;
    /**
     * Imperatively hide the hover card.
     */
    hide: () => void;
}
/**
 * Hook for hover card behavior with hover/focus triggers.
 *
 * Builds on useLayer to add:
 * - Hover triggers with configurable delay
 * - Focus triggers with auto-detection for focusable elements
 * - Stay-open behavior when mouse/focus moves into the hover card
 *
 * @example
 * ```
 * const hoverCard = useHoverCard({ placement: 'above' });
 * <Button ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>
 *   Hover me
 * </Button>
 * {hoverCard.renderHoverCard(<ProfileCard user={user} />)}
 * ```
 */
export declare function useHoverCard(options?: HoverCardOptions): HoverCardReturn;
//# sourceMappingURL=useHoverCard.d.ts.map