@bazza-ui/react 0.0.0-snapshot-20260205122957

package/dist/internal/popup-menu/index.d.ts

@@ -0,0 +1,925 @@
+import * as React from 'react';
+import { ReactStore } from '@base-ui/utils/store';
+import { bs as VirtualizationConfig, bt as VirtualAnchor, G as GetQualifiedRowIdFn, av as SubmenuContextValue, be as AsyncLoaderConfig, A as AsyncLoaderResult, N as NodeDef, bh as AsyncState, b4 as SubmenuDef, bf as AsyncNodesConfig, aP as GroupBehavior, bl as RadioGroupBehavior, b2 as ScoredNode, aO as DisplayRowNode, bu as GetQualifiedRowIdContext, aM as DisplayNode, bi as BreadcrumbNode, aQ as GroupDef, aZ as RadioGroupDef, aT as ItemDef, bm as RadioItemDef, aD as CheckboxItemDef } from '../../data-surface-Dki7544r.js';
+export { bg as AsyncRenderState, aE as CheckboxItemRenderParams, aF as CheckboxItemRenderProps, aG as DataListChildrenState, aH as DataListProps, b7 as DataSurfaceContext, aI as DataSurfaceContextValue, aJ as DataSurfaceProps, aK as DeepSearchConfig, aL as DisplayGroupNode, aN as DisplayRadioGroupNode, bj as DisplaySeparatorNode, aR as GroupRenderContext, aS as GroupRenderParams, aU as ItemRenderParams, aV as ItemRenderProps, L as LoaderComponentProps, b as PopupMenuArrow, F as PopupMenuArrowProps, c as PopupMenuBackdrop, H as PopupMenuBackdropProps, n as PopupMenuCheckboxItem, o as PopupMenuCheckboxItemIndicator, a7 as PopupMenuCheckboxItemIndicatorProps, a8 as PopupMenuCheckboxItemIndicatorState, a9 as PopupMenuCheckboxItemProps, aa as PopupMenuCheckboxItemState, bv as PopupMenuContext, au as PopupMenuContextValue, p as PopupMenuDataInput, ab as PopupMenuDataInputProps, q as PopupMenuDataList, aW as PopupMenuDataListProps, r as PopupMenuDataSurface, aX as PopupMenuDataSurfaceProps, d as PopupMenuEmpty, I as PopupMenuEmptyProps, J as PopupMenuEmptyState, e as PopupMenuGroup, f as PopupMenuGroupLabel, K as PopupMenuGroupLabelProps, M as PopupMenuGroupLabelState, O as PopupMenuGroupProps, R as PopupMenuGroupState, g as PopupMenuIcon, T as PopupMenuIconProps, U as PopupMenuIconState, p as PopupMenuInput, ab as PopupMenuInputProps, ac as PopupMenuInputState, s as PopupMenuItem, ad as PopupMenuItemProps, ae as PopupMenuItemState, h as PopupMenuList, V as PopupMenuListChildrenState, a5 as PopupMenuListCssVars, W as PopupMenuListProps, X as PopupMenuListState, i as PopupMenuPopup, Y as PopupMenuPopupProps, E as PopupMenuPopupState, j as PopupMenuPortal, Z as PopupMenuPortalProps, t as PopupMenuPositioner, af as PopupMenuPositionerAlign, a6 as PopupMenuPositionerCssVars, ag as PopupMenuPositionerProps, u as PopupMenuRadioGroup, ah as PopupMenuRadioGroupProps, ai as PopupMenuRadioGroupState, v as PopupMenuRadioGroupValue, aY as PopupMenuRadioGroupValueProps, w as PopupMenuRadioItem, x as PopupMenuRadioItemIndicator, aj as PopupMenuRadioItemIndicatorProps, ak as PopupMenuRadioItemIndicatorState, al as PopupMenuRadioItemProps, am as PopupMenuRadioItemState, bx as PopupMenuScrollArrow, _ as PopupMenuScrollArrowProps, $ as PopupMenuScrollArrowState, k as PopupMenuScrollDownArrow, a0 as PopupMenuScrollDownArrowProps, l as PopupMenuScrollUpArrow, a1 as PopupMenuScrollUpArrowProps, m as PopupMenuSeparator, a2 as PopupMenuSeparatorProps, a3 as PopupMenuSeparatorState, y as PopupMenuShortcut, an as PopupMenuShortcutProps, ao as PopupMenuShortcutState, z as PopupMenuSubmenuRoot, ap as PopupMenuSubmenuRootProps, B as PopupMenuSubmenuTrigger, D as PopupMenuSubmenuTriggerIndicator, aq as PopupMenuSubmenuTriggerIndicatorProps, ar as PopupMenuSubmenuTriggerIndicatorState, as as PopupMenuSubmenuTriggerProps, at as PopupMenuSubmenuTriggerState, P as PopupMenuSurface, a as PopupMenuSurfaceProps, a4 as PopupMenuSurfaceState, bk as QueryAsyncNodesConfig, Q as QueryDependentLoaderConfig, a_ as RadioGroupRenderParams, a$ as RadioGroupRenderProps, bn as RadioItemRenderParams, bo as RadioItemRenderProps, b0 as RenderNodeFn, b1 as RowRenderContext, b3 as SeparatorDef, bp as SeparatorRenderParams, bq as StaticAsyncNodesConfig, S as StaticLoaderConfig, bw as SubmenuContext, b5 as SubmenuRenderParams, b6 as SubmenuRenderProps, aA as UsePopupMenuItemParams, aB as UsePopupMenuItemReturn, b8 as defineRadioGroup, b9 as isDisplayGroupNode, ba as isDisplayRadioGroupNode, bb as isDisplayRowNode, br as isDisplaySeparatorNode, bc as useDataSurfaceContext, bd as useMaybeDataSurfaceContext, aw as useMaybePopupMenuContext, ax as useMaybeSubmenuContext, ay as usePopupMenuContext, aC as usePopupMenuItem, az as useSubmenuContext } from '../../data-surface-Dki7544r.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { C as ChangeEventDetails, V as VirtualItem, G as GenericEventDetails, r as ListboxStore, P as PopupMenuOpenChangeReason, u as ItemContextValue, E as CheckedChangeReason, R as RadioValueChangeReason } from '../../use-listbox-item-bi01_uzf.js';
+import '@base-ui/react/popover';
+
+declare enum PopupMenuCheckboxItemDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-checkbox-item' | 'bazzaui-context-menu-checkbox-item'}
+     */
+    slot = "bazzaui-[component]-checkbox-item",
+    /**
+     * Present when the checkbox item is checked.
+     */
+    checked = "data-checked",
+    /**
+     * Present when the checkbox item is unchecked.
+     */
+    unchecked = "data-unchecked",
+    /**
+     * Present when the item is highlighted (via keyboard or pointer).
+     */
+    highlighted = "data-highlighted",
+    /**
+     * Present when the item is disabled.
+     */
+    disabled = "data-disabled"
+}
+
+declare enum PopupMenuItemDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-item' | 'bazzaui-context-menu-item' | 'bazzaui-select-item' | 'bazzaui-combobox-item'}
+     */
+    slot = "bazzaui-[component]-item",
+    /**
+     * Present when the item is highlighted (via keyboard or pointer).
+     */
+    highlighted = "data-highlighted",
+    /**
+     * Present when the item is disabled.
+     */
+    disabled = "data-disabled"
+}
+
+declare enum PopupMenuRadioGroupDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-radio-group' | 'bazzaui-context-menu-radio-group'}
+     */
+    slot = "bazzaui-[component]-radio-group",
+    /**
+     * Present when the radio group is disabled.
+     */
+    disabled = "data-disabled"
+}
+
+declare enum PopupMenuRadioItemDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-radio-item' | 'bazzaui-context-menu-radio-item'}
+     */
+    slot = "bazzaui-[component]-radio-item",
+    /**
+     * Present when the radio item is checked/selected.
+     */
+    checked = "data-checked",
+    /**
+     * Present when the radio item is unchecked.
+     */
+    unchecked = "data-unchecked",
+    /**
+     * Present when the item is highlighted (via keyboard or pointer).
+     */
+    highlighted = "data-highlighted",
+    /**
+     * Present when the item is disabled.
+     */
+    disabled = "data-disabled"
+}
+
+/**
+ * Component name used for generating bazzaui-* slot attributes.
+ * E.g., 'dropdown-menu', 'context-menu', 'select', 'combobox'
+ */
+type ComponentName = 'dropdown-menu' | 'context-menu' | 'select' | 'combobox';
+declare const ComponentNameContext: React.Context<ComponentName | null>;
+/**
+ * Returns the component name from context.
+ * Throws if used outside of a component that provides the context.
+ */
+declare function useComponentName(): ComponentName;
+/**
+ * Returns the component name from context, or null if not available.
+ * Useful for internal components that may be used outside the popup-menu context.
+ */
+declare function useMaybeComponentName(): ComponentName | null;
+/**
+ * Helper to generate a bazzaui slot attribute value.
+ * @param componentName The component name (e.g., 'dropdown-menu')
+ * @param partName The part name (e.g., 'trigger', 'item')
+ * @returns The slot attribute value (e.g., 'bazzaui-dropdown-menu-trigger')
+ */
+declare function getSlotAttribute(componentName: ComponentName | null, partName: string): string | undefined;
+
+interface FocusOwnerState {
+    /** Which surface currently owns focus (surfaceId or null) */
+    ownerId: string | null;
+}
+declare const selectors$1: {
+    ownerId: (state: FocusOwnerState) => string | null;
+    isOwner: (state: FocusOwnerState, surfaceId: string) => boolean;
+};
+/**
+ * Tracks which menu surface owns DOM focus.
+ * Single instance per menu tree (created at root, shared via context).
+ *
+ * Used by: DropdownMenu, ContextMenu
+ * Not used by: Select, CommandMenu (single surface)
+ */
+declare class FocusOwnerStore extends ReactStore<FocusOwnerState, {}, typeof selectors$1> {
+    constructor();
+    /**
+     * Set the owner surface ID.
+     * Call this when focus should transfer to a new surface.
+     */
+    setOwnerId(id: string | null): void;
+    /**
+     * Clear the owner (set to null).
+     * Call this when the menu tree closes.
+     */
+    clearOwner(): void;
+}
+
+declare const FocusOwnerContext: React.Context<FocusOwnerStore | null>;
+declare function useFocusOwner(): FocusOwnerStore;
+declare function useMaybeFocusOwner(): FocusOwnerStore | null;
+
+interface OpenChainState {
+    /**
+     * Ordered array of surface IDs for submenus that are currently open.
+     * The last element is the most recently opened (deepest in chain).
+     */
+    chain: string[];
+}
+declare const selectors: {
+    isOpen: (state: OpenChainState, surfaceId: string) => boolean;
+    isLast: (state: OpenChainState, surfaceId: string) => boolean;
+    /**
+     * Returns true if there's an open submenu below the given depth.
+     * - Root (depth 0): true if any submenu is open
+     * - Submenu at depth N: true if a deeper submenu is open
+     */
+    hasOpenSubmenu: (state: OpenChainState, depth: number) => boolean;
+};
+/**
+ * Tracks which submenu surfaces are currently open in order.
+ * Used to show backdrops for all open menus in the chain.
+ * Single instance per menu tree (created at root, shared via context).
+ *
+ * Used by: DropdownMenu, ContextMenu
+ * Not used by: Select, CommandMenu (no submenus)
+ */
+declare class OpenChainStore extends ReactStore<OpenChainState, {}, typeof selectors> {
+    constructor();
+    /**
+     * Mark a surface as open (adds to end of chain).
+     */
+    open(surfaceId: string): void;
+    /**
+     * Mark a surface as closed (removes from chain).
+     */
+    close(surfaceId: string): void;
+    /**
+     * Clear all open surfaces (menu tree closed).
+     */
+    clear(): void;
+}
+
+declare const OpenChainContext: React.Context<OpenChainStore | null>;
+declare function useOpenChain(): OpenChainStore;
+declare function useMaybeOpenChain(): OpenChainStore | null;
+
+/**
+ * Context for passing surfaceId from Popup to Surface.
+ * This ensures Popup and Surface share the same ID for data attribute tracking.
+ *
+ * For root menus, Popup generates the ID and provides it via this context.
+ * For submenus, the ID comes from SubmenuContext.childSurfaceId instead.
+ */
+declare const PopupSurfaceIdContext: React.Context<string | null>;
+declare function usePopupSurfaceId(): string | null;
+
+interface AimGuardContextValue {
+    aimGuardActive: boolean;
+    guardedTriggerId: string | null;
+    guardedDepth: number | null;
+    guardedSubmenuSurfaceId: string | null;
+    activateAimGuard: (triggerId: string, depth: number, submenuSurfaceId: string, timeoutMs?: number) => void;
+    clearAimGuard: () => void;
+    aimGuardActiveRef: React.RefObject<boolean>;
+    guardedTriggerIdRef: React.RefObject<string | null>;
+    guardedDepthRef: React.RefObject<number | null>;
+    guardedSubmenuSurfaceIdRef: React.RefObject<string | null>;
+    isGuardBlocking: (rowId: string) => boolean;
+}
+declare const AimGuardCtx: React.Context<AimGuardContextValue>;
+declare const useAimGuard: () => AimGuardContextValue;
+interface AimGuardProviderProps {
+    children: React.ReactNode;
+}
+/**
+ * Provides aim guard for safe polygon navigation.
+ * Prevents accidental submenu closures when users move diagonally toward an open submenu.
+ */
+declare function AimGuardProvider({ children }: AimGuardProviderProps): react_jsx_runtime.JSX.Element;
+
+type AnchorSide = 'left' | 'right';
+/**
+ * Determines which side of the submenu the trigger is anchored to.
+ * Used to know which direction the user should be moving toward.
+ */
+declare function resolveAnchorSide(rect: DOMRect, tRect: DOMRect | null, mx: number): AnchorSide;
+/**
+ * Calculates a smoothed heading vector from the mouse trail.
+ * If movement is too slow, infers direction toward the submenu center.
+ */
+declare function getSmoothedHeading(trail: [number, number][], exitX: number, exitY: number, anchor: AnchorSide, tRect: DOMRect | null, rect: DOMRect): {
+    dx: number;
+    dy: number;
+};
+/**
+ * Tests if the user's trajectory will intersect the submenu's safe zone.
+ * Returns true if the user is aiming toward the submenu.
+ */
+declare function willHitSubmenu(exitX: number, exitY: number, heading: {
+    dx: number;
+    dy: number;
+}, rect: DOMRect, anchor: AnchorSide, triggerRect: DOMRect | null): boolean;
+
+/**
+ * Keeps track of the last N mouse positions without causing re-renders.
+ * Used for calculating mouse trajectory in aim guard.
+ */
+declare function useMouseTrail(n?: number): React.RefObject<[number, number][]>;
+
+interface UsePopupMenuRootParams {
+    /**
+     * Callback when the open state changes.
+     * The second parameter contains event details including the reason for the change.
+     */
+    onOpenChange?: (open: boolean, eventDetails: ChangeEventDetails<string>) => void;
+    /**
+     * Whether the menu is initially open.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Whether virtualization mode is enabled.
+     * @default false
+     */
+    virtualized?: boolean;
+    /**
+     * Pre-registered items for virtualization.
+     */
+    items?: VirtualItem[];
+    /**
+     * Callback when the highlighted item changes.
+     * The third parameter contains event details including the reason for the change.
+     */
+    onHighlightChange?: (id: string | null, index: number, eventDetails: GenericEventDetails<string, {
+        index: number;
+    }>) => void;
+    /**
+     * When to close the menu on outside interactions.
+     * - 'pointerdown': Close immediately when pointer is pressed outside (default)
+     * - 'click': Close when a full click (pointerdown + pointerup) occurs outside
+     * @default 'pointerdown'
+     */
+    closeOnOutsidePress?: 'click' | 'pointerdown';
+}
+interface UsePopupMenuRootReturn {
+    /** The Listbox store instance */
+    store: ListboxStore;
+    /** The FocusOwner store instance */
+    focusOwnerStore: FocusOwnerStore;
+    /** The OpenChain store instance */
+    openChainStore: OpenChainStore;
+    /** Register a surface (submenu) for closeAll tracking */
+    registerSurface: (depth: number, setOpen: (open: boolean) => void) => () => void;
+    /** Close the entire menu tree */
+    closeAll: (reason?: PopupMenuOpenChangeReason, event?: Event) => void;
+    /** Virtualization configuration (if enabled) */
+    virtualization: VirtualizationConfig | undefined;
+    /** Handle open state change (updates store and clears stores on close) */
+    handleOpenChange: (open: boolean, reason?: PopupMenuOpenChangeReason, event?: Event) => void;
+}
+/**
+ * Hook that creates and manages the core stores and utilities for popup menus.
+ * Used by both DropdownMenu.Root and ContextMenu.Root.
+ *
+ * Provides:
+ * - ListboxStore for item management
+ * - FocusOwnerStore for focus tracking across submenus
+ * - OpenChainStore for tracking open submenu chain
+ * - Surface registry for closeAll functionality
+ */
+declare function usePopupMenuRoot(params?: UsePopupMenuRootParams): UsePopupMenuRootReturn;
+
+declare enum PopupMenuArrowDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-arrow' | 'bazzaui-context-menu-arrow' | 'bazzaui-select-arrow' | 'bazzaui-combobox-arrow'}
+     */
+    slot = "bazzaui-[component]-arrow",
+    /**
+     * Present when the popup menu is open.
+     */
+    open = "data-open",
+    /**
+     * Present when the popup menu is closed.
+     */
+    closed = "data-closed",
+    /**
+     * Indicates which side the popup is positioned relative to the trigger.
+     * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'}
+     */
+    side = "data-side",
+    /**
+     * Indicates how the popup is aligned relative to specified side.
+     * @type {'start' | 'center' | 'end'}
+     */
+    align = "data-align",
+    /**
+     * Present when the arrow is not centered due to collision avoidance.
+     */
+    uncentered = "data-uncentered"
+}
+
+declare enum PopupMenuBackdropDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-backdrop' | 'bazzaui-context-menu-backdrop' | 'bazzaui-select-backdrop' | 'bazzaui-combobox-backdrop'}
+     */
+    slot = "bazzaui-[component]-backdrop",
+    /**
+     * Present when the popup menu is open.
+     */
+    open = "data-open",
+    /**
+     * Present when the popup menu is closed.
+     */
+    closed = "data-closed",
+    /**
+     * Present when the popup menu is animating in.
+     */
+    startingStyle = "data-starting-style",
+    /**
+     * Present when the popup menu is animating out.
+     */
+    endingStyle = "data-ending-style"
+}
+
+declare enum PopupMenuPopupDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-popup' | 'bazzaui-context-menu-popup' | 'bazzaui-select-popup' | 'bazzaui-combobox-popup'}
+     */
+    slot = "bazzaui-[component]-popup",
+    /**
+     * Present when the popup menu is open.
+     */
+    open = "data-open",
+    /**
+     * Present when the popup menu is closed.
+     */
+    closed = "data-closed",
+    /**
+     * Indicates which side the popup is positioned relative to the trigger.
+     * @type {'top' | 'bottom' | 'left' | 'right'}
+     */
+    side = "data-side",
+    /**
+     * Indicates how the popup is aligned relative to specified side.
+     * @type {'start' | 'center' | 'end'}
+     */
+    align = "data-align",
+    /**
+     * Present when the popup is animating in.
+     */
+    startingStyle = "data-starting-style",
+    /**
+     * Present when the popup is animating out.
+     */
+    endingStyle = "data-ending-style",
+    /**
+     * Present if animations should be instant.
+     * @type {'click' | 'dismiss'}
+     */
+    instant = "data-instant",
+    /**
+     * Present when this popup's surface is the focus owner.
+     * Useful for styling the currently focused menu in a submenu chain.
+     */
+    focused = "data-focused",
+    /**
+     * Present when this popup has an open submenu below it in the menu tree.
+     * Useful for styling all parent menus in an open submenu chain.
+     */
+    hasOpenSubmenu = "data-has-open-submenu",
+    /**
+     * Present when this popup is a submenu (not the root menu).
+     * Useful for applying different styles to submenus vs root menus.
+     */
+    submenu = "data-submenu"
+}
+
+declare enum PopupMenuPositionerDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-positioner' | 'bazzaui-context-menu-positioner' | 'bazzaui-select-positioner' | 'bazzaui-combobox-positioner'}
+     */
+    slot = "bazzaui-[component]-positioner",
+    /**
+     * Present when the popup menu is open.
+     */
+    open = "data-open",
+    /**
+     * Present when the popup menu is closed.
+     */
+    closed = "data-closed",
+    /**
+     * Present when the anchor is hidden.
+     */
+    anchorHidden = "data-anchor-hidden",
+    /**
+     * Indicates which side the popup is positioned relative to the trigger.
+     * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'}
+     */
+    side = "data-side",
+    /**
+     * Indicates how the popup is aligned relative to specified side.
+     * @type {'start' | 'center' | 'end' | 'list-start'}
+     */
+    align = "data-align"
+}
+
+interface PopupMenuProvidersProps {
+    /** The Listbox store instance */
+    store: ListboxStore;
+    /** The FocusOwner store instance */
+    focusOwnerStore: FocusOwnerStore;
+    /** The OpenChain store instance */
+    openChainStore: OpenChainStore;
+    /** Nesting depth: 0 = root menu */
+    depth: number;
+    /** Close the entire menu tree */
+    closeAll: () => void;
+    /** Register a surface for closeAll tracking */
+    registerSurface: (depth: number, setOpen: (open: boolean) => void) => () => void;
+    /** Virtualization configuration */
+    virtualization?: VirtualizationConfig;
+    /**
+     * Virtual anchor for positioning (used by ContextMenu).
+     * DropdownMenu uses Popover's anchor (trigger button) instead.
+     */
+    virtualAnchor?: VirtualAnchor;
+    /**
+     * Type of menu for positioning logic.
+     * @default 'dropdown'
+     */
+    menuType?: 'dropdown' | 'context';
+    /**
+     * When to close the menu on outside interactions.
+     * @default 'pointerdown'
+     */
+    closeOnOutsidePress?: 'click' | 'pointerdown';
+    /**
+     * Function to generate qualified unique IDs for rows.
+     * Defined once at the root level and applied to all surfaces (root and submenus).
+     */
+    getQualifiedRowId?: GetQualifiedRowIdFn;
+    /**
+     * Component name for generating bazzaui-* slot attributes.
+     * E.g., 'dropdown-menu', 'context-menu', 'select', 'combobox'
+     */
+    componentName: ComponentName;
+    children: React.ReactNode;
+}
+/**
+ * Provides all shared context providers for popup menus.
+ * Wraps children with:
+ * - PopupMenuContext (menu-specific state)
+ * - ListboxContextProvider (for compatibility with listbox components)
+ * - AimGuardProvider (for submenu aim detection)
+ * - FocusOwnerContext (for focus tracking across submenus)
+ * - OpenChainContext (for tracking open submenu chain)
+ */
+declare function PopupMenuProviders(props: PopupMenuProvidersProps): react_jsx_runtime.JSX.Element;
+
+interface UsePopupMenuKeyboardParams {
+    /** The Listbox store instance */
+    store: ListboxStore;
+    /** Unique identifier for this surface */
+    surfaceId: string;
+    /** The FocusOwner store for managing focus ownership */
+    focusOwnerStore: FocusOwnerStore;
+    /** Menu depth (0 for root, >0 for submenus) */
+    depth: number;
+    /** Submenu context for ArrowLeft navigation back to parent */
+    submenuContext: SubmenuContextValue | null;
+    /** Whether keyboard handling is enabled */
+    enabled: boolean;
+    /**
+     * Whether to enable type-to-search behavior.
+     * When true, printable characters will activate the input and set pending search.
+     * Used by List when hideUntilActive is enabled and input is not yet active.
+     * @default false
+     */
+    enableTypeToSearch?: boolean;
+    /** User's onKeyDown handler to compose with */
+    onKeyDown?: React.KeyboardEventHandler;
+    /**
+     * Callback to close the entire menu tree from the root.
+     * Used when Escape is pressed and closeRootOnEsc is true (default).
+     */
+    closeAll: () => void;
+    /**
+     * Whether to skip the focus owner check.
+     * When true, keyboard handling will work based on `enabled` prop alone,
+     * ignoring focus ownership. Useful for Combobox where the input is outside
+     * the Surface but should still handle keyboard navigation.
+     * @default false
+     */
+    skipFocusOwnerCheck?: boolean;
+}
+interface UsePopupMenuKeyboardReturn {
+    /** Keyboard event handler to attach to the element */
+    handleKeyDown: React.KeyboardEventHandler;
+}
+/**
+ * Centralized keyboard navigation hook for popup menus.
+ * Handles arrow navigation, vim bindings, submenu open/close, and selection.
+ */
+declare function usePopupMenuKeyboard(params: UsePopupMenuKeyboardParams): UsePopupMenuKeyboardReturn;
+
+declare const PopupMenuIconDataAttributes: {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-icon' | 'bazzaui-context-menu-icon' | 'bazzaui-select-icon' | 'bazzaui-combobox-icon'}
+     */
+    readonly slot: "bazzaui-[component]-icon";
+    /** Present when the popup is open. */
+    readonly open: "data-popup-open";
+};
+
+declare enum PopupMenuListDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-list' | 'bazzaui-context-menu-list' | 'bazzaui-select-list' | 'bazzaui-combobox-list'}
+     */
+    slot = "bazzaui-[component]-list",
+    /**
+     * Always present on the list element.
+     * Used for styling and by useStickyRowWidth to find the list container.
+     */
+    list = "data-popup-menu-list"
+}
+
+declare const PopupMenuScrollArrowDataAttributes: {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-scroll-up-arrow' | 'bazzaui-dropdown-menu-scroll-down-arrow' | 'bazzaui-context-menu-scroll-up-arrow' | 'bazzaui-context-menu-scroll-down-arrow' | 'bazzaui-select-scroll-up-arrow' | 'bazzaui-select-scroll-down-arrow' | 'bazzaui-combobox-scroll-up-arrow' | 'bazzaui-combobox-scroll-down-arrow'}
+     */
+    readonly slot: "bazzaui-[component]-scroll-[up|down]-arrow";
+    /** @type {'up' | 'down'} */
+    readonly direction: "data-direction";
+    /** @type {'top' | 'bottom' | 'left' | 'right'} */
+    readonly side: "data-side";
+};
+
+/**
+ * Context value for checkbox menu items.
+ * Extends ItemContextValue with checkbox-specific state.
+ */
+interface CheckboxItemContextValue extends ItemContextValue {
+    /** Whether this checkbox item is currently checked */
+    checked: boolean;
+    /**
+     * Toggle the checked state.
+     * @param reason - The reason for the change (default: 'item-press')
+     * @param event - The native DOM event that triggered the change
+     */
+    toggle: (reason?: CheckedChangeReason, event?: Event) => void;
+}
+declare const CheckboxItemContext: React.Context<CheckboxItemContextValue | null>;
+declare function useCheckboxItemContext(): CheckboxItemContextValue;
+
+interface RadioGroupContextValue {
+    /** Current selected value */
+    value: string | undefined;
+    /**
+     * Function to update the selected value.
+     * @param value - The new value to select
+     * @param reason - The reason for the change (default: 'item-press')
+     * @param event - The native DOM event that triggered the change
+     */
+    setValue: (value: string, reason?: RadioValueChangeReason, event?: Event) => void;
+    /** Whether all items in the group are disabled */
+    disabled: boolean;
+}
+declare const RadioGroupContext: React.Context<RadioGroupContextValue | null>;
+declare function useRadioGroupContext(): RadioGroupContextValue;
+
+/**
+ * Context value for radio menu items.
+ * Extends ItemContextValue with radio-specific state.
+ */
+interface RadioItemContextValue extends ItemContextValue {
+    /** Whether this radio item is currently selected */
+    checked: boolean;
+}
+declare const RadioItemContext: React.Context<RadioItemContextValue | null>;
+declare function useRadioItemContext(): RadioItemContextValue;
+
+declare enum PopupMenuShortcutDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-shortcut' | 'bazzaui-context-menu-shortcut'}
+     */
+    slot = "bazzaui-[component]-shortcut",
+    /**
+     * Present when the parent item is highlighted.
+     */
+    highlighted = "data-highlighted"
+}
+
+declare enum PopupMenuSubmenuTriggerDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-submenu-trigger' | 'bazzaui-context-menu-submenu-trigger'}
+     */
+    slot = "bazzaui-[component]-submenu-trigger",
+    /**
+     * Present on submenu trigger elements.
+     */
+    submenuTrigger = "data-submenu-trigger",
+    /**
+     * Present when the submenu popup is open.
+     */
+    popupOpen = "data-popup-open",
+    /**
+     * Present when the submenu owns keyboard focus.
+     */
+    popupFocused = "data-popup-focused",
+    /**
+     * Present when the item is highlighted.
+     */
+    highlighted = "data-highlighted",
+    /**
+     * Present when the item is disabled.
+     */
+    disabled = "data-disabled"
+}
+
+/**
+ * State for a registered async loader.
+ */
+interface AsyncMenuState {
+    /** Unique identifier for this async menu */
+    id: string;
+    /** Breadcrumbs path to this menu (for merging into tree) */
+    breadcrumbs: string[];
+    /** The loader configuration */
+    config: AsyncLoaderConfig;
+    /** Current loader result */
+    result: AsyncLoaderResult<NodeDef[]>;
+}
+/**
+ * Context value for the async menu coordinator.
+ */
+interface AsyncMenuCoordinatorValue {
+    /** Register a new async loader */
+    registerLoader: (state: AsyncMenuState) => void;
+    /** Unregister an async loader */
+    unregisterLoader: (id: string) => void;
+    /** Update loader result */
+    updateLoaderResult: (id: string, result: AsyncLoaderResult<NodeDef[]>) => void;
+    /** Current search query from the store */
+    searchQuery: string;
+    /** All registered loaders */
+    loaders: Map<string, AsyncMenuState>;
+    /** Any loader is currently loading */
+    isAnyLoading: boolean;
+    /** Static loaders are loading */
+    isStaticLoading: boolean;
+    /** Query loaders are loading */
+    isQueryLoading: boolean;
+    /** All loaders have resolved (not loading, no pending) */
+    allResolved: boolean;
+    /** Get all resolved async nodes with their breadcrumbs */
+    getAsyncNodes: () => Array<{
+        id: string;
+        breadcrumbs: string[];
+        nodes: NodeDef[];
+    }>;
+    /** Loaders that errored */
+    erroredLoaders: Map<string, Error>;
+    /** Get the aggregate async state for DataList */
+    getAsyncState: () => AsyncState;
+}
+declare const AsyncMenuCoordinatorContext: React.Context<AsyncMenuCoordinatorValue | null>;
+declare function useAsyncMenuCoordinator(): AsyncMenuCoordinatorValue | null;
+declare function useMaybeAsyncMenuCoordinator(): AsyncMenuCoordinatorValue | null;
+interface AsyncMenuCoordinatorProviderProps {
+    /** Children to render */
+    children: React.ReactNode;
+    /** Current search query from the store */
+    searchQuery: string;
+}
+declare function AsyncMenuCoordinatorProvider(props: AsyncMenuCoordinatorProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Default function to generate qualified unique IDs for rows.
+ *
+ * Logic:
+ * - If node.id is provided, use it as-is (treat as globally unique)
+ * - Otherwise, when deep searching, qualify with breadcrumb path + value
+ * - When not deep searching, just use the slugified value
+ *
+ * @example
+ * // With explicit id:
+ * // { id: 'my-unique-id', value: 'In Progress' }
+ * // => 'my-unique-id'
+ *
+ * // Without id, deep searching in "Status" submenu:
+ * // { value: 'In Progress' } in Status submenu
+ * // => 'status.in-progress'
+ *
+ * // Without id, not deep searching:
+ * // { value: 'In Progress' }
+ * // => 'in-progress'
+ */
+declare function defaultGetQualifiedRowId(ctx: GetQualifiedRowIdContext): string;
+declare function isItemDef(node: NodeDef): node is ItemDef;
+declare function isRadioItemDef(node: NodeDef): node is RadioItemDef;
+declare function isCheckboxItemDef(node: NodeDef): node is CheckboxItemDef;
+declare function isSubmenuDef(node: NodeDef): node is SubmenuDef;
+declare function isGroupDef(node: NodeDef): node is GroupDef;
+declare function isRadioGroupDef(node: NodeDef): node is RadioGroupDef;
+declare function isSeparatorDef(node: NodeDef): node is {
+    kind: 'separator';
+    id?: string;
+};
+interface FlattenOptions {
+    /** Whether to include children of submenus (deep search) */
+    deep?: boolean;
+    /** Parent breadcrumb nodes (submenu nodes from root to parent) */
+    breadcrumbs?: BreadcrumbNode[];
+    /** Current group context (nested groups not supported) */
+    group?: {
+        id: string;
+        label?: string;
+        groupDef: GroupDef;
+    } | null;
+    /** Current radio group context */
+    radioGroup?: {
+        id: string;
+        label?: string;
+        radioGroupDef: RadioGroupDef;
+    } | null;
+}
+interface FlattenedNode {
+    node: ItemDef | RadioItemDef | CheckboxItemDef | SubmenuDef;
+    /** Breadcrumb nodes (submenu nodes from root to parent) */
+    breadcrumbs: BreadcrumbNode[];
+    /** The group this node belongs to, if any */
+    group: {
+        id: string;
+        label?: string;
+        groupDef: GroupDef;
+    } | null;
+    /** The radio group this node belongs to, if any */
+    radioGroup: {
+        id: string;
+        label?: string;
+        radioGroupDef: RadioGroupDef;
+    } | null;
+}
+/**
+ * Flattens a tree of node definitions into a flat array.
+ * When deep=true, includes children of submenus with their breadcrumb paths.
+ * Tracks group and radio group membership for each node.
+ */
+declare function flattenNodes(nodes: NodeDef[], options?: FlattenOptions): FlattenedNode[];
+/**
+ * Scores nodes against a search query.
+ * Returns only nodes with a score > 0.
+ */
+declare function scoreNodes(flattenedNodes: FlattenedNode[], query: string): ScoredNode[];
+/**
+ * Sorts scored nodes by score (descending).
+ */
+declare function sortByScore(nodes: ScoredNode[]): ScoredNode[];
+/**
+ * Partitions nodes: items first, then submenu triggers.
+ * This ensures items appear before submenu triggers in search results.
+ */
+declare function partitionByKind(nodes: ScoredNode[]): ScoredNode[];
+/**
+ * Deduplicates nodes by their composite ID (breadcrumbs + node.value).
+ * This handles the case where the same node appears multiple times in the tree.
+ * Values are normalized (trimmed) for consistent deduplication.
+ */
+declare function deduplicateNodes(nodes: ScoredNode[]): ScoredNode[];
+/**
+ * Converts scored nodes to display row nodes with render context.
+ * Used for flatten mode where groups are invisible.
+ */
+declare function buildDisplayRowNodes(scoredNodes: ScoredNode[], query: string, highlightedId: string | null): DisplayRowNode[];
+/**
+ * Gets nodes for browse mode (no search) with flatten behavior.
+ * Returns only top-level items and submenu triggers, flattening groups.
+ */
+declare function getBrowseNodesFlatten(nodes: NodeDef[], highlightedId: string | null, group?: {
+    id: string;
+    label?: string;
+} | null): DisplayRowNode[];
+/**
+ * Gets nodes for browse mode (no search) with preserve behavior.
+ * Keeps group structure intact, showing group containers with their items.
+ */
+declare function getBrowseNodesPreserve(nodes: NodeDef[], highlightedId: string | null): DisplayNode[];
+interface FilterNodesOptions {
+    /** The search query */
+    query: string;
+    /** The node definitions to filter */
+    nodes: NodeDef[];
+    /** Currently highlighted node ID */
+    highlightedId: string | null;
+    /** Whether deep search is enabled */
+    deepSearch?: boolean;
+    /** Minimum query length for deep search */
+    minLength?: number;
+    /** How groups behave during search (only applies when searching, not browse mode) */
+    groupSearchBehavior?: GroupBehavior;
+    /** How radio groups behave during search */
+    radioGroupSearchBehavior?: RadioGroupBehavior;
+    /** Whether to sort groups by best score */
+    sortGroups?: boolean;
+}
+/**
+ * Main filtering pipeline.
+ * Handles both browse mode and search mode (shallow and deep).
+ * Respects groupSearchBehavior configuration (only applies during search).
+ * Note: Radio groups are ALWAYS preserved regardless of groupSearchBehavior.
+ */
+declare function filterNodes(options: FilterNodesOptions): {
+    displayNodes: DisplayNode[];
+    isDeepSearching: boolean;
+};
+/**
+ * Gets the IDs of all navigable (non-disabled) nodes.
+ * Handles row nodes, group nodes, and radio group nodes (extracts item IDs).
+ * Separators are skipped as they're not navigable.
+ * Used for keyboard navigation.
+ *
+ * Note: Uses `node.id ?? node.value` as the identifier. For proper ID handling
+ * with custom getItemId functions, use `getOrderedItemIds` from DataList instead.
+ */
+declare function getNavigableIds(displayNodes: DisplayNode[]): string[];
+/**
+ * Gets the first navigable node ID.
+ */
+declare function getFirstNavigableId(displayNodes: DisplayNode[]): string | null;
+/**
+ * Info about an async submenu for registration with coordinator.
+ */
+interface AsyncSubmenuInfo {
+    /** Unique identifier (uses node value and breadcrumbs) */
+    id: string;
+    /** Breadcrumbs path to this submenu */
+    breadcrumbs: string[];
+    /** The submenu node definition */
+    node: SubmenuDef;
+    /** The async configuration */
+    config: AsyncNodesConfig;
+}
+/**
+ * Collects all async submenus from a node tree.
+ * Recursively traverses groups and submenus to find all async configurations.
+ */
+declare function collectAsyncSubmenus(nodes: NodeDef[], breadcrumbs?: string[]): AsyncSubmenuInfo[];
+/**
+ * Merges async nodes into a submenu's node list.
+ * Static nodes come first, async nodes are appended.
+ */
+declare function mergeSubmenuNodes(staticNodes: NodeDef[] | undefined, asyncNodes: NodeDef[] | undefined): NodeDef[];
+/**
+ * Async data from the coordinator ready for merging.
+ */
+interface AsyncNodeData {
+    id: string;
+    breadcrumbs: string[];
+    nodes: NodeDef[];
+}
+/**
+ * Creates a merged content tree with async nodes injected at their proper locations.
+ * This function modifies the tree to include async nodes where they belong.
+ */
+declare function mergeAsyncNodesIntoTree(staticContent: NodeDef[], asyncData: AsyncNodeData[]): NodeDef[];
+/**
+ * Checks if deep search should include this async config.
+ */
+declare function shouldIncludeInDeepSearch(config: AsyncNodesConfig): boolean;
+/**
+ * Checks if an async loader should be rendered eagerly.
+ * Eager loaders mount when the root menu opens (before their submenu is opened).
+ */
+declare function shouldLoadEagerly(config: AsyncNodesConfig): boolean;
+
+export { type AimGuardContextValue, AimGuardCtx, AimGuardProvider, type AimGuardProviderProps, type AnchorSide, AsyncLoaderConfig, AsyncLoaderResult, AsyncMenuCoordinatorContext, AsyncMenuCoordinatorProvider, type AsyncMenuCoordinatorValue, type AsyncMenuState, AsyncNodesConfig, AsyncState, type AsyncSubmenuInfo, BreadcrumbNode, CheckboxItemContext, type CheckboxItemContextValue, CheckboxItemDef, type ComponentName, ComponentNameContext, DisplayNode, DisplayRowNode, type FilterNodesOptions, FocusOwnerContext, type FocusOwnerState, FocusOwnerStore, GroupBehavior, GroupDef, ItemDef, NodeDef, OpenChainContext, type OpenChainState, OpenChainStore, PopupMenuArrowDataAttributes, PopupMenuBackdropDataAttributes, PopupMenuCheckboxItemDataAttributes, PopupMenuIconDataAttributes, PopupMenuItemDataAttributes, PopupMenuListDataAttributes, PopupMenuPopupDataAttributes, PopupMenuPositionerDataAttributes, PopupMenuProviders, type PopupMenuProvidersProps, PopupMenuRadioGroupDataAttributes, PopupMenuRadioItemDataAttributes, PopupMenuScrollArrowDataAttributes, PopupMenuShortcutDataAttributes, PopupMenuSubmenuTriggerDataAttributes, PopupSurfaceIdContext, RadioGroupBehavior, RadioGroupContext, type RadioGroupContextValue, RadioGroupDef, RadioItemContext, type RadioItemContextValue, RadioItemDef, ScoredNode, SubmenuContextValue, SubmenuDef, type UsePopupMenuKeyboardParams, type UsePopupMenuKeyboardReturn, type UsePopupMenuRootParams, type UsePopupMenuRootReturn, VirtualAnchor, VirtualItem, VirtualizationConfig, buildDisplayRowNodes, collectAsyncSubmenus, deduplicateNodes, defaultGetQualifiedRowId, filterNodes, flattenNodes, getBrowseNodesFlatten, getBrowseNodesPreserve, getFirstNavigableId, getNavigableIds, getSlotAttribute, getSmoothedHeading, isCheckboxItemDef, isGroupDef, isItemDef, isRadioGroupDef, isRadioItemDef, isSeparatorDef, isSubmenuDef, mergeAsyncNodesIntoTree, mergeSubmenuNodes, partitionByKind, resolveAnchorSide, scoreNodes, shouldIncludeInDeepSearch, shouldLoadEagerly, sortByScore, useAimGuard, useAsyncMenuCoordinator, useCheckboxItemContext, useComponentName, useFocusOwner, useMaybeAsyncMenuCoordinator, useMaybeComponentName, useMaybeFocusOwner, useMaybeOpenChain, useMouseTrail, useOpenChain, usePopupMenuKeyboard, usePopupMenuRoot, usePopupSurfaceId, useRadioGroupContext, useRadioItemContext, willHitSubmenu };