import "./index.css";
import type { CombineAriaPropsWithCustomProps } from "../../utilities/reactAriaProps";
import React, { type ReactElement, type ReactNode } from "react";
import type { Key, MenuItemProps, MenuSectionProps, PopoverProps } from "react-aria-components";
export type DropdownPlacement = NonNullable<PopoverProps["placement"]>;
export interface DropdownProps {
    /**
     * A `<DropdownTrigger>` followed by a `<DropdownMenu>` containing the items.
     */
    children: ReactNode;
    /** Fires when the menu closes. */
    onClose?: () => void;
    /** Fires when the menu opens. Useful for analytics or lazy data prep. */
    onOpen?: () => void;
}
export type DropdownElementProps = DropdownProps;
/**
 * An action menu — a button that, when activated, reveals a list of actions or
 * navigation links. Composed of a `<DropdownTrigger>` wrapping a Tapestry
 * dropdown-trigger button (`DropdownButton`, `DropdownIconButton`, or
 * `PageHeaderActionsDropdownButton`) and a `<DropdownMenu>` containing
 * `<DropdownAction>`, `<DropdownLink>`, `<DropdownSection>`, and
 * `<DropdownSeparator>` items.
 *
 * **Dropdown vs Select.** Use `Dropdown` to trigger an action ("Edit",
 * "Delete") or navigate ("Go to documentation"). Use `Select` to collect a
 * value that is bound to form data or component state. They look visually
 * similar but follow different ARIA patterns (Menu vs Combobox/Listbox) and
 * are not interchangeable.
 *
 * Built on React Aria's `MenuTrigger` primitive; popover positioning and menu
 * identity live on `<DropdownMenu>`.
 *
 * @component
 * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/menu/ | W3C APG Menu Pattern}
 */
export declare function Dropdown({ children, onClose, onOpen }: DropdownElementProps): React.JSX.Element;
export interface DropdownMenuProps {
    /**
     * `<DropdownAction>` / `<DropdownLink>` / `<DropdownSection>` /
     * `<DropdownSeparator>` elements.
     */
    children: ReactNode;
    /** Override for the underlying `<Menu>` element id. */
    id?: string;
    /**
     * Popover position relative to the trigger. Uses React Aria's
     * space-separated format (e.g., `"bottom start"`, `"top end"`,
     * `"left top"`). Defaults to `"bottom start"`.
     */
    placement?: DropdownPlacement;
}
export type DropdownMenuElementProps = DropdownMenuProps;
/**
 * The popover surface for a `<Dropdown>`. Wraps React Aria's `<Popover>` and
 * `<Menu>` and contains the menu items.
 *
 * @component
 */
export declare function DropdownMenu({ children, id, placement, }: DropdownMenuElementProps): React.JSX.Element;
export interface DropdownTriggerProps {
    /**
     * A single Tapestry dropdown-trigger button element (`DropdownButton`,
     * `DropdownIconButton`, or `PageHeaderActionsDropdownButton`).
     */
    children: ReactElement;
}
export declare function DropdownTrigger({ children }: DropdownTriggerProps): React.JSX.Element;
export interface DropdownItemBaseProps {
    /** Applies destructive styling. */
    destructive?: boolean;
    /** Applies staff-only visual treatment. */
    staffOnly?: boolean;
}
export interface DropdownActionProps extends DropdownItemBaseProps {
    /**
     * Disables the item. Renamed to React Aria's `isDisabled` inside the
     * wrapper. Disabled items are skipped by keyboard traversal and won't fire
     * `onAction`.
     */
    disabled?: boolean;
    /**
     * Stable identifier — required by React Aria's collection model for keying
     * and focus tracking.
     */
    id: Key;
    /** Callback fired when the item is activated. */
    onAction: () => void;
}
type AriaActionPropsToOmit = "href" | "isDisabled" | "rel" | "routerOptions" | "target" | "value";
type AriaActionPropsToInclude = "textValue";
export type DropdownActionElementProps<T extends object = object> = CombineAriaPropsWithCustomProps<MenuItemProps<T>, DropdownActionProps, AriaActionPropsToOmit, AriaActionPropsToInclude>;
/**
 * A `<Dropdown>` item that fires a callback when activated. Renders an RA
 * `<MenuItem>` (`role="menuitem"`). Children are passed through and can use
 * the slot convention (`slot="label" | "prefix" | "suffix" | "description"`)
 * for structured content.
 *
 * @component
 */
export declare function DropdownAction<T extends object>({ className, destructive, disabled, staffOnly, ...restProps }: DropdownActionElementProps<T>): React.JSX.Element;
export interface DropdownLinkProps extends DropdownItemBaseProps {
    /** If `true`, sets `target="_blank"` and `rel="noreferrer noopener"`. */
    external?: boolean;
    /** Destination URL. */
    href: string;
    /**
     * Stable identifier — required by React Aria's collection model for keying
     * and focus tracking.
     */
    id: Key;
}
type AriaLinkPropsToOmit = "isDisabled" | "onAction" | "rel" | "target" | "value";
type AriaLinkPropsToInclude = "href" | "routerOptions" | "textValue";
export type DropdownLinkElementProps<T extends object = object> = CombineAriaPropsWithCustomProps<MenuItemProps<T>, DropdownLinkProps, AriaLinkPropsToOmit, AriaLinkPropsToInclude>;
/**
 * A `<Dropdown>` item that navigates to a URL. Renders an RA `<MenuItem>` as
 * an anchor (`<a role="menuitem" href="…">`). Pass `external` to open in a
 * new tab with `rel="noreferrer noopener"`.
 *
 * `disabled` is intentionally not accepted — HTML has no native disabled state
 * for anchors, and a "disabled link" has no accessible analog. If a link
 * shouldn't be activatable, omit it.
 *
 * @component
 */
export declare function DropdownLink<T extends object>({ className, destructive, external, staffOnly, ...restProps }: DropdownLinkElementProps<T>): React.JSX.Element;
export interface DropdownSectionProps {
    /** The items rendered within the section. */
    children: ReactNode;
    /**
     * Heading rendered above the section's items. Required — RA renders the
     * section as `role="group"` and the heading provides the group's
     * accessible name via `aria-labelledby`.
     */
    title: string;
}
export type DropdownSectionElementProps<T extends object = object> = CombineAriaPropsWithCustomProps<MenuSectionProps<T>, DropdownSectionProps, "value", never>;
/**
 * A grouped section within a `<Dropdown>`. Renders an RA `<MenuSection>`
 * (`role="group"`) with an optional `<Header>` heading when `title` is set.
 *
 * @component
 */
export declare function DropdownSection<T extends object>({ children, className, title, ...restProps }: DropdownSectionElementProps<T>): React.JSX.Element;
export type DropdownSeparatorElementProps = Record<string, never>;
/**
 * A divider between items in a `<Dropdown>`. Renders an RA `<Separator>`
 * (`role="separator"`).
 *
 * @component
 */
export declare function DropdownSeparator(): React.JSX.Element;
export {};
//# sourceMappingURL=Dropdown.d.ts.map