/**
 * @file Popover.tsx
 * @input Uses React, usePopover hook
 * @output Exports Popover component for click-triggered popovers
 * @position Layer component; declarative wrapper around usePopover hook
 *
 * For hover-triggered overlays, use HoverCard instead.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Popover/Popover.test.tsx
 * - /packages/core/src/Popover/index.ts
 * - /apps/storybook/stories/Popover.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Popover/ (showcase blocks)
 */
import React, { type ReactElement, type ReactNode } from 'react';
import type { BaseProps } from '../BaseProps';
import type { LayerAlignment, LayerPlacement } from '../Layer/useLayer';
/**
 * Props passed to render-prop children for explicit trigger wiring.
 */
export interface PopoverTriggerRenderProps {
    /** Ref callback — attach to the trigger element for anchor positioning. */
    ref: (el: HTMLElement | null) => void;
    /** Toggle the popover open/closed. */
    onClick: () => void;
    /** ARIA attribute: indicates the element triggers a dialog. */
    'aria-haspopup': 'dialog';
    /** ARIA attribute: whether the popover is currently open. */
    'aria-expanded': boolean;
    /** ARIA attribute: ID of the controlled popover element. */
    'aria-controls': string;
}
export interface PopoverProps extends Pick<BaseProps, 'xstyle' | 'className' | 'style'> {
    /**
     * The trigger element. Accepts either:
     *
     * **ReactNode (automatic mode):** Must contain a `<button>` or
     * `[role="button"]` element — the popover locates it and applies
     * click/keydown handlers and ARIA attributes automatically.
     * Components that consume `InteractiveRoleContext` (e.g., Token)
     * will render as a button automatically when placed here.
     *
     * **Render function (explicit mode):** Receives `PopoverTriggerRenderProps`
     * with ref, onClick, and ARIA attributes. The consumer is responsible
     * for attaching these to their trigger element. Use this for custom
     * triggers or third-party components.
     *
     * The trigger is rendered inside an anchor wrapper used for CSS anchor
     * positioning. The wrapper is stable (no pressed-state transforms),
     * preventing popover position jitter.
     *
     * When `anchorRef` is provided, children can be omitted and the popover
     * attaches to the external ref element as a sibling.
     *
     * @example
     * ```
     * <Popover content={...}><Button label="Open" /></Popover>
     * <Popover content={...}><Token label="Filter" /></Popover>
     * <Popover content={...}>
     *   {(triggerProps) => <MyCustomTrigger {...triggerProps} />}
     * </Popover>
     * ```
     */
    children?: ReactNode | ((props: PopoverTriggerRenderProps) => ReactNode);
    /**
     * External ref to use as the popover anchor.
     * When provided (and no children), the popover attaches to this element
     * instead of wrapping children. The referenced element must be a
     * `<button>` or `[role="button"]` — the popover applies click/keydown
     * handlers and ARIA attributes to it directly.
     */
    anchorRef?: React.RefObject<HTMLElement>;
    /**
     * Content to display inside the popover.
     */
    content: ReactNode;
    /**
     * Position placement relative to the trigger.
     * Uses CSS anchor positioning via useLayer.
     * @default 'below'
     */
    placement?: LayerPlacement;
    /**
     * Alignment along the placement axis.
     * @default 'start'
     */
    alignment?: LayerAlignment;
    /**
     * Whether the popover is open (controlled mode).
     * Omit for uncontrolled behavior.
     */
    isOpen?: boolean;
    /**
     * Callback fired when the popover visibility changes.
     */
    onOpenChange?: (isOpen: boolean) => void;
    /**
     * Whether the popover is enabled.
     * When false, trigger interactions are ignored.
     * @default true
     */
    isEnabled?: boolean;
    /**
     * Width of the popover container.
     * Numbers are px, strings used as-is.
     * @default 'auto'
     */
    width?: number | string;
    /**
     * Accessible label for the popover dialog.
     * Recommended for accessibility when `role` is `'dialog'`.
     */
    label?: string;
    /**
     * ARIA role stamped on the popover content wrapper.
     *
     * Use `'dialog'` for dialog-style popovers. Use `'none'` when the popup
     * content owns its own role, such as a child `role="menu"` or
     * `role="listbox"`.
     *
     * @default 'dialog'
     */
    role?: 'dialog' | 'none';
    /**
     * Whether a dialog-style popover is modal (`aria-modal`). Only applies when
     * `role` is `'dialog'`.
     *
     * @default true
     */
    isModal?: 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;
    /**
     * Whether to auto-focus the first focusable element when the popover opens.
     * Set to `false` for inline showcases or documentation previews.
     * @default true
     */
    hasAutoFocus?: boolean;
    /**
     * Whether clicking outside dismisses the popover.
     * Set to `false` for surfaces that should stay open until explicitly
     * dismissed, like onboarding coachmarks or multi-step flows.
     * @default true
     */
    hasLightDismiss?: boolean;
    /**
     * Whether pressing Escape dismisses the popover.
     *
     * Only takes full effect together with `hasLightDismiss={false}`: with
     * light dismiss on, the browser's native light dismiss also closes on
     * Escape. Set both to `false` for explicit-dismiss-only surfaces.
     * @default true
     */
    hasEscapeDismiss?: boolean;
    /**
     * Test ID for the popover container.
     */
    'data-testid'?: string;
}
/**
 * A click-triggered popover for displaying interactive content anchored to a trigger.
 *
 * Implements the button + dialog ARIA pattern. The trigger must contain a
 * `<button>` or `[role="button"]` element — the popover finds it and applies
 * click/keydown handlers and ARIA attributes automatically.
 *
 * Uses an inline-flex wrapper as the CSS anchor for stable positioning
 * (immune to pressed-state transforms like `:active { scale(0.98) }`).
 *
 * Focus is trapped inside the popover when open.
 * Supports light dismiss by default (click outside or Escape to close).
 *
 * For hover-triggered overlays, use {@link HoverCard} instead.
 *
 * @example
 * ```
 * <Popover label="Settings" content={<SettingsPanel />} placement="below">
 *   <Button label="Settings" />
 * </Popover>
 * <Popover
 *   isOpen={isOpen}
 *   onOpenChange={setIsOpen}
 *   label="Filter"
 *   content={<FilterForm />}>
 *   <Button label="Filter" />
 * </Popover>
 * <Popover
 *   anchorRef={myButtonRef}
 *   label="Actions"
 *   content={<ActionMenu />}
 *   placement="below"
 * />
 * ```
 */
export declare function Popover({ children, anchorRef, content, placement, alignment, isOpen, onOpenChange, isEnabled, width, label, role, isModal, hasCloseButton, closeButtonLabel, hasAutoFocus, hasLightDismiss, hasEscapeDismiss, xstyle, className, style, 'data-testid': testId, }: PopoverProps): ReactElement;
export declare namespace Popover {
    var displayName: string;
}
//# sourceMappingURL=Popover.d.ts.map