@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Dropdown/Dropdown.d.ts

@@ -0,0 +1,476 @@
+import type { ReactElement } from "react";
+import { DropdownCheckboxItemProps, DropdownContentProps, DropdownGroupProps, DropdownItemIndicatorProps, DropdownItemProps, DropdownLabelProps, DropdownRadioGroupProps, DropdownRadioItemProps, DropdownRootProps, DropdownSeparatorProps, DropdownSubContentProps, DropdownSubProps, DropdownSubTriggerProps, DropdownTriggerProps } from "./types.js";
+/**
+ * The root of a Dropdown menu — owns the open state and provides context to
+ * descendants. Renders no DOM of its own; it is a context boundary.
+ *
+ * Supports two state modes, statically discriminated at the type level so
+ * only one shape is accepted by TypeScript:
+ *
+ * - **Uncontrolled** — pass {@link DropdownRootProps.defaultOpen | `defaultOpen`}
+ *   (or omit it to start closed). The component owns and updates the open
+ *   state internally. Optional {@link DropdownRootProps.onOpenChange | `onOpenChange`}
+ *   observes transitions.
+ * - **Controlled** — pass {@link DropdownRootProps.open | `open`} *and*
+ *   {@link DropdownRootProps.onOpenChange | `onOpenChange`} together. The
+ *   parent owns the state; the component defers every transition back through
+ *   the callback.
+ *
+ * Only user-driven transitions (trigger clicks, Escape, selection) invoke
+ * `onOpenChange`. External state flips made by the parent do not.
+ *
+ * **Reading direction.** Pass {@link DropdownRootProps.dir | `dir`} to set
+ * `"ltr"` or `"rtl"`, which inverts the submenu open / close arrow keys
+ * (`ArrowRight` ↔ `ArrowLeft`). When omitted, the component reads the
+ * inherited {@link DirectionProvider} value, falling back to `"ltr"`.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Dropdown.Root>
+ *   <Dropdown.Trigger>Options</Dropdown.Trigger>
+ *   <Dropdown.Content>
+ *     <Dropdown.Item>Rename</Dropdown.Item>
+ *     <Dropdown.Item>Delete</Dropdown.Item>
+ *   </Dropdown.Content>
+ * </Dropdown.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Dropdown.Root open={open} onOpenChange={setOpen}>
+ *   ...
+ * </Dropdown.Root>
+ * ```
+ */
+export declare function DropdownRoot({ defaultOpen, open, onOpenChange, dir, children, }: DropdownRootProps): ReactElement;
+export declare namespace DropdownRoot {
+    var displayName: string;
+}
+/**
+ * The menu button. Toggles the Dropdown open/closed on click and exposes
+ * the ARIA contract for WAI-ARIA Menu Button: `aria-haspopup="menu"`,
+ * `aria-expanded` reflecting the open state, and `aria-controls` pointing
+ * at the content's id.
+ *
+ * Renders a `<button type="button">` by default. Pass `asChild` to render
+ * the composed child element instead (e.g. a link, or a custom button
+ * component). All ARIA attributes and event handlers are merged onto the
+ * child following the {@link Slot} composition rules.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example With an anchor via `asChild`
+ * ```tsx
+ * <Dropdown.Trigger asChild>
+ *   <a href="#options">Options</a>
+ * </Dropdown.Trigger>
+ * ```
+ */
+export declare function DropdownTrigger({ children, onClick, asChild, ...rest }: DropdownTriggerProps): ReactElement;
+export declare namespace DropdownTrigger {
+    var displayName: string;
+}
+/**
+ * The menu panel rendered with the native HTML
+ * [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+ * (`popover="auto"`) — no portal, no floating-ui. The browser manages
+ * layering via the top layer and dispatches a light-dismiss on outside
+ * click and Escape in the light-dismiss flow.
+ *
+ * Renders a `<menu role="menu">` by default; pass `asChild` to render
+ * any element with menu semantics.
+ *
+ * **Keyboard interaction.** While the menu is open:
+ *
+ * | Key                     | Behaviour                                          |
+ * | ----------------------- | -------------------------------------------------- |
+ * | `ArrowDown` / `ArrowUp` | Move focus to next / previous item (wraps)         |
+ * | `Home` / `End`          | Jump to first / last item                          |
+ * | `Enter` / `Space`       | Activate the focused item                          |
+ * | `Escape`                | Close the menu and return focus to the trigger     |
+ * | any printable character | Typeahead — focuses the next item matching prefix  |
+ *
+ * Typeahead accumulates keystrokes within a 500 ms window; pressing the
+ * same character repeatedly cycles through items that share that first
+ * letter. Disabled items are skipped during arrow navigation and typeahead.
+ *
+ * Arrow navigation is scoped to the popover that currently holds focus —
+ * a {@link DropdownSubContent | `Dropdown.SubContent`} rendered inside
+ * this menu does not pull its items into the parent's navigation cycle,
+ * so `ArrowDown` past a {@link DropdownSubTrigger | `Dropdown.SubTrigger`}
+ * lands on the next sibling item in the parent rather than getting
+ * stuck on a non-focusable item inside a closed sub-popover.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Content>
+ *   <Dropdown.Item onSelect={rename}>Rename</Dropdown.Item>
+ *   <Dropdown.Separator />
+ *   <Dropdown.Item onSelect={remove}>Delete</Dropdown.Item>
+ * </Dropdown.Content>
+ * ```
+ */
+export declare function DropdownContent({ children, onKeyDown, asChild, ...rest }: DropdownContentProps): ReactElement;
+export declare namespace DropdownContent {
+    var displayName: string;
+}
+/**
+ * A standard menu item. Renders a `<li role="menuitem">` by default; pass
+ * `asChild` to render any element with menuitem semantics.
+ *
+ * Clicking the item (or pressing Enter / Space while focused) fires
+ * {@link DropdownItemProps.onSelect | `onSelect`} with a cancellable
+ * `Event`. The menu auto-closes after selection; call
+ * `event.preventDefault()` inside `onSelect` to keep it open — useful
+ * for actions that perform in-place mutations (e.g. copying to clipboard).
+ *
+ * Disabled items receive `aria-disabled="true"` and are skipped by arrow
+ * navigation, typeahead, and activation handlers.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example Keep the menu open after selecting
+ * ```tsx
+ * <Dropdown.Item onSelect={(event) => {
+ *   copyToClipboard();
+ *   event.preventDefault();
+ * }}>
+ *   Copy link
+ * </Dropdown.Item>
+ * ```
+ */
+export declare function DropdownItem({ children, onClick, onSelect, disabled, asChild, ...rest }: DropdownItemProps): ReactElement;
+export declare namespace DropdownItem {
+    var displayName: string;
+}
+/**
+ * A visual separator between groups of items. Renders a `<li role="separator">`
+ * by default; pass `asChild` to render any element with separator semantics.
+ * Non-interactive — skipped by focus, arrow navigation, and typeahead.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Item>Cut</Dropdown.Item>
+ * <Dropdown.Separator />
+ * <Dropdown.Item>Paste</Dropdown.Item>
+ * ```
+ */
+export declare function DropdownSeparator({ asChild, children, ...rest }: DropdownSeparatorProps): ReactElement;
+export declare namespace DropdownSeparator {
+    var displayName: string;
+}
+/**
+ * A semantic grouping of related items. Renders as a `<li role="group">`
+ * wrapping an inner `<ul role="none">`, or — with `asChild` — a single
+ * grouping element composed onto the provided child.
+ *
+ * Generates a stable id for its accompanying {@link DropdownLabel | `Dropdown.Label`},
+ * wired automatically via `aria-labelledby`. Nest a `Dropdown.Label` as the
+ * first child to provide the accessible name; screen readers will announce
+ * the group when arrowing into it.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Group>
+ *   <Dropdown.Label>Sort by</Dropdown.Label>
+ *   <Dropdown.Item>Name</Dropdown.Item>
+ *   <Dropdown.Item>Date</Dropdown.Item>
+ * </Dropdown.Group>
+ * ```
+ */
+export declare function DropdownGroup({ children, asChild, ...rest }: DropdownGroupProps): ReactElement;
+export declare namespace DropdownGroup {
+    var displayName: string;
+}
+/**
+ * A non-interactive label, typically used inside a {@link DropdownGroup |
+ * `Dropdown.Group`} to give that group an accessible name. When nested in
+ * a group, the label's `id` is auto-wired to the group's `aria-labelledby`
+ * — consumers don't need to thread ids manually.
+ *
+ * Renders a `<li>` by default; pass `asChild` to render any element. A
+ * caller-supplied `id` takes precedence over the auto-generated one.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Group>
+ *   <Dropdown.Label>Actions</Dropdown.Label>
+ *   <Dropdown.Item>Duplicate</Dropdown.Item>
+ * </Dropdown.Group>
+ * ```
+ */
+export declare function DropdownLabel({ id, children, asChild, ...rest }: DropdownLabelProps): ReactElement;
+export declare namespace DropdownLabel {
+    var displayName: string;
+}
+/**
+ * A toggleable menu item. Renders a `<li role="menuitemcheckbox">` with
+ * `aria-checked` reflecting the current state. `asChild` is supported.
+ *
+ * Supports a WAI-ARIA tri-state: `true`, `false`, or `"indeterminate"`
+ * (encoded as `aria-checked="mixed"`). An indeterminate item resolves to
+ * `true` on the next activation, matching the native `<input type="checkbox">`
+ * behaviour.
+ *
+ * State modes are discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultChecked` (or omit to start unchecked).
+ *   Optional `onCheckedChange` observes toggles.
+ * - **Controlled** — pass `checked` *and* `onCheckedChange` together.
+ *
+ * Activation (click / Enter / Space) toggles the checked state, then
+ * fires {@link DropdownCheckboxItemProps.onSelect | `onSelect`} with a
+ * cancellable `Event`. Call `event.preventDefault()` to keep the menu
+ * open — useful for rapidly toggling multiple checkboxes.
+ *
+ * Nest a {@link DropdownItemIndicator | `Dropdown.ItemIndicator`} to
+ * render the visible check mark; it reads its parent's state from
+ * context and exposes `data-state` for styling.
+ *
+ * Disabled items receive `aria-disabled="true"` and no-op on activation.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example Controlled checkbox item
+ * ```tsx
+ * <Dropdown.CheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
+ *   <Dropdown.ItemIndicator>
+ *     <CheckIcon />
+ *   </Dropdown.ItemIndicator>
+ *   Show grid
+ * </Dropdown.CheckboxItem>
+ * ```
+ */
+export declare function DropdownCheckboxItem({ children, onClick, onSelect, disabled, defaultChecked, checked: controlledChecked, onCheckedChange, asChild, ...rest }: DropdownCheckboxItemProps): ReactElement;
+export declare namespace DropdownCheckboxItem {
+    var displayName: string;
+}
+/**
+ * A single-selection group of menu items. Children must be
+ * {@link DropdownRadioItem | `Dropdown.RadioItem`} elements. Renders a
+ * `<li role="group">` wrapping `<ul role="none">`, or — with `asChild` —
+ * composes onto the provided child.
+ *
+ * State modes are discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultValue` (or omit for no initial selection).
+ *   Optional `onValueChange` observes selections.
+ * - **Controlled** — pass `value` *and* `onValueChange` together.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.RadioGroup value={sort} onValueChange={setSort}>
+ *   <Dropdown.RadioItem value="name">
+ *     <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *     Name
+ *   </Dropdown.RadioItem>
+ *   <Dropdown.RadioItem value="date">
+ *     <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *     Date
+ *   </Dropdown.RadioItem>
+ * </Dropdown.RadioGroup>
+ * ```
+ */
+export declare function DropdownRadioGroup({ defaultValue, value: controlledValue, onValueChange, children, asChild, ...rest }: DropdownRadioGroupProps): ReactElement;
+export declare namespace DropdownRadioGroup {
+    var displayName: string;
+}
+/**
+ * A single radio choice. Must be rendered inside a
+ * {@link DropdownRadioGroup | `Dropdown.RadioGroup`}; rendering it outside
+ * one throws a descriptive error.
+ *
+ * Renders a `<li role="menuitemradio">` with `aria-checked` reflecting
+ * whether this item's `value` matches the group's active value. `asChild`
+ * is supported.
+ *
+ * Activation (click / Enter / Space) selects this item, updating the
+ * group's value, then fires {@link DropdownRadioItemProps.onSelect |
+ * `onSelect`} with a cancellable `Event`. Call `event.preventDefault()`
+ * to keep the menu open.
+ *
+ * Nest a {@link DropdownItemIndicator | `Dropdown.ItemIndicator`} to
+ * render the visible bullet; it reads its parent's state from context
+ * and exposes `data-state` for styling.
+ *
+ * Disabled items receive `aria-disabled="true"` and no-op on activation.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.RadioItem value="compact">
+ *   <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *   Compact
+ * </Dropdown.RadioItem>
+ * ```
+ */
+export declare function DropdownRadioItem({ children, onClick, onSelect, disabled, value: itemValue, asChild, ...rest }: DropdownRadioItemProps): ReactElement;
+export declare namespace DropdownRadioItem {
+    var displayName: string;
+}
+/**
+ * The visible mark (usually a checkmark or a bullet) rendered inside a
+ * {@link DropdownCheckboxItem | `Dropdown.CheckboxItem`} or
+ * {@link DropdownRadioItem | `Dropdown.RadioItem`}. Must be a descendant
+ * of one of those; rendering it anywhere else throws a descriptive error.
+ *
+ * Renders a `<span>` by default; pass `asChild` to compose onto any
+ * element (commonly an SVG icon). Exposes `data-state` reflecting the
+ * parent item's live state: `"checked"`, `"unchecked"`, or
+ * `"indeterminate"` — the last being reachable only through a tri-state
+ * `Dropdown.CheckboxItem`.
+ *
+ * By default the indicator unmounts when its parent is unchecked. Pass
+ * {@link DropdownItemIndicatorProps.forceMount | `forceMount`} to keep
+ * the DOM node mounted in both states, which is handy when animating the
+ * indicator in and out via CSS transitions or a React animation library.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.CheckboxItem checked={showBookmarks} onCheckedChange={setShowBookmarks}>
+ *   <Dropdown.ItemIndicator>
+ *     <CheckIcon />
+ *   </Dropdown.ItemIndicator>
+ *   Show bookmarks
+ * </Dropdown.CheckboxItem>
+ * ```
+ */
+export declare function DropdownItemIndicator({ children, asChild, forceMount, ...rest }: DropdownItemIndicatorProps): ReactElement | null;
+export declare namespace DropdownItemIndicator {
+    var displayName: string;
+}
+/**
+ * A submenu boundary. Wrap a {@link DropdownSubTrigger | `Dropdown.SubTrigger`}
+ * and its {@link DropdownSubContent | `Dropdown.SubContent`} in a
+ * `Dropdown.Sub` to establish an independent open state for the nested menu.
+ *
+ * Supports uncontrolled (`defaultOpen`) and controlled (`open` +
+ * `onOpenChange`) modes, discriminated at the type level — same contract
+ * as {@link DropdownRoot | `Dropdown.Root`}.
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Root>
+ *   <Dropdown.Trigger>File</Dropdown.Trigger>
+ *   <Dropdown.Content>
+ *     <Dropdown.Sub>
+ *       <Dropdown.SubTrigger>Open Recent</Dropdown.SubTrigger>
+ *       <Dropdown.SubContent>
+ *         <Dropdown.Item>Project A</Dropdown.Item>
+ *         <Dropdown.Item>Project B</Dropdown.Item>
+ *       </Dropdown.SubContent>
+ *     </Dropdown.Sub>
+ *   </Dropdown.Content>
+ * </Dropdown.Root>
+ * ```
+ */
+export declare function DropdownSub({ defaultOpen, open: controlledOpen, onOpenChange, children, }: DropdownSubProps): ReactElement;
+export declare namespace DropdownSub {
+    var displayName: string;
+}
+/**
+ * The submenu trigger. Must be rendered inside a {@link DropdownSub |
+ * `Dropdown.Sub`}; rendering it outside one throws a descriptive error.
+ *
+ * Renders a `<li role="menuitem">` with `aria-haspopup="menu"`,
+ * `aria-expanded`, and `aria-controls` wiring it to the sibling
+ * {@link DropdownSubContent | `Dropdown.SubContent`}. `asChild` is supported.
+ *
+ * Opens the submenu on click, the inline-forward arrow key, or pointer
+ * hover; all other keys bubble to the parent {@link DropdownContent |
+ * `Dropdown.Content`} so its roving focus and typeahead continue to work
+ * while a submenu is in play. The open key follows the resolved reading
+ * direction — `ArrowRight` in `"ltr"`, `ArrowLeft` in `"rtl"`. Hovering
+ * onto a sibling item in the parent menu closes the submenu — mirroring
+ * the keyboard contract where focus returning to the parent dismisses it.
+ *
+ * Disabled triggers receive `aria-disabled="true"` and ignore both click
+ * and the open arrow key.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Sub>
+ *   <Dropdown.SubTrigger>Share</Dropdown.SubTrigger>
+ *   <Dropdown.SubContent>
+ *     <Dropdown.Item>Email link</Dropdown.Item>
+ *   </Dropdown.SubContent>
+ * </Dropdown.Sub>
+ * ```
+ */
+export declare function DropdownSubTrigger({ children, onClick, onKeyDown, disabled, asChild, ...rest }: DropdownSubTriggerProps): ReactElement;
+export declare namespace DropdownSubTrigger {
+    var displayName: string;
+}
+/**
+ * The submenu panel. Must be rendered inside a {@link DropdownSub |
+ * `Dropdown.Sub`}; rendering it outside one throws a descriptive error.
+ *
+ * Renders a `<menu role="menu" popover="auto">` by default; pass `asChild`
+ * to render any element with menu semantics. When the submenu opens, focus
+ * moves to its first enabled item.
+ *
+ * Presses of the inline-backward arrow key close the submenu and return
+ * focus to the {@link DropdownSubTrigger | `Dropdown.SubTrigger`} —
+ * `ArrowLeft` in `"ltr"`, `ArrowRight` in `"rtl"`. All other keys bubble
+ * to the parent {@link DropdownContent | `Dropdown.Content`} so arrow
+ * navigation and typeahead apply to the submenu's items.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.SubContent>
+ *   <Dropdown.Item>Project A</Dropdown.Item>
+ *   <Dropdown.Item>Project B</Dropdown.Item>
+ * </Dropdown.SubContent>
+ * ```
+ */
+export declare function DropdownSubContent({ children, onKeyDown, asChild, ...rest }: DropdownSubContentProps): ReactElement;
+export declare namespace DropdownSubContent {
+    var displayName: string;
+}
+/** Type of the {@link Dropdown} compound: the root callable plus its attached sub-components. */
+export type TDropdownCompound = typeof DropdownRoot & {
+    Root: typeof DropdownRoot;
+    Trigger: typeof DropdownTrigger;
+    Content: typeof DropdownContent;
+    Item: typeof DropdownItem;
+    Separator: typeof DropdownSeparator;
+    Group: typeof DropdownGroup;
+    Label: typeof DropdownLabel;
+    CheckboxItem: typeof DropdownCheckboxItem;
+    RadioGroup: typeof DropdownRadioGroup;
+    RadioItem: typeof DropdownRadioItem;
+    ItemIndicator: typeof DropdownItemIndicator;
+    Sub: typeof DropdownSub;
+    SubTrigger: typeof DropdownSubTrigger;
+    SubContent: typeof DropdownSubContent;
+};
+/**
+ * Headless, accessible **Dropdown** menu — a compound component implementing the
+ * [WAI-ARIA menu-button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)
+ * with submenus, checkbox and radio items, groups, labels and separators. Zero
+ * styles ship.
+ *
+ * The default export is the `Root`; sub-components are attached as static
+ * properties (`Dropdown.Trigger`, `Dropdown.Content`, ...).
+ */
+declare const DropdownCompound: TDropdownCompound;
+export { DropdownCompound as Dropdown };