@bazza-ui/react 0.0.0 → 0.1.0-canary.2

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

@@ -0,0 +1,846 @@
+import * as React from 'react';
+import { S as FocusOwnerStore, T as OpenChainStore, V as VirtualizationConfig, P as PopupMenuDebugOptions, U as VirtualAnchor } from '../../separator-B4Ot84B0.js';
+export { a2 as FocusOwnerState, a3 as OpenChainState, b as PopupMenuArrow, o as PopupMenuArrowProps, c as PopupMenuBackdrop, p as PopupMenuBackdropProps, W as PopupMenuContext, N as PopupMenuContextValue, $ as PopupMenuDebugContext, X as PopupMenuDebugContextValue, d as PopupMenuEmpty, q as PopupMenuEmptyProps, r as PopupMenuEmptyState, e as PopupMenuGroup, f as PopupMenuGroupLabel, s as PopupMenuGroupLabelProps, t as PopupMenuGroupLabelState, u as PopupMenuGroupProps, v as PopupMenuGroupState, g as PopupMenuIcon, w as PopupMenuIconProps, x as PopupMenuIconState, h as PopupMenuList, y as PopupMenuListChildrenState, L as PopupMenuListCssVars, z as PopupMenuListProps, A as PopupMenuListState, i as PopupMenuPopup, B as PopupMenuPopupProps, R as PopupMenuPopupState, j as PopupMenuPortal, C as PopupMenuPortalProps, M as PopupMenuPositionerCssVars, a as PopupMenuRootActions, Y as PopupMenuSafeTriangleAreaDebugConfig, Z as PopupMenuSafeTriangleAreaDebugOptions, _ as PopupMenuSafeTriangleAreaDebugSettings, a7 as PopupMenuScrollArrow, D as PopupMenuScrollArrowProps, E as PopupMenuScrollArrowState, k as PopupMenuScrollDownArrow, F as PopupMenuScrollDownArrowProps, l as PopupMenuScrollUpArrow, G as PopupMenuScrollUpArrowProps, m as PopupMenuSeparator, H as PopupMenuSeparatorProps, I as PopupMenuSeparatorState, n as PopupMenuSurface, J as PopupMenuSurfaceProps, K as PopupMenuSurfaceState, a4 as UsePopupMenuRootParams, a5 as UsePopupMenuRootReturn, a0 as resolvePopupMenuSafeTriangleAreaDebugConfig, O as useMaybePopupMenuContext, Q as usePopupMenuContext, a1 as usePopupMenuDebug, a6 as usePopupMenuRoot } from '../../separator-B4Ot84B0.js';
+import { S as SubmenuContextValue, E as SubpageContextValue } from '../../data-surface-D1OilMDu.js';
+export { a5 as AsyncMenuCoordinatorContext, a6 as AsyncMenuCoordinatorProvider, O as AsyncMenuCoordinatorValue, a4 as AsyncMenuState, a8 as DataPopupContext, a7 as DataPopupContextValue, Y as DataSurfaceContext, Q as DataSurfaceContextValue, P as PopupMenuCheckboxItemIndicator, n as PopupMenuCheckboxItemIndicatorProps, o as PopupMenuCheckboxItemIndicatorState, a as PopupMenuDataList, R as PopupMenuDataListProps, b as PopupMenuDataSubpages, T as PopupMenuDataSubpagesProps, c as PopupMenuDataSurface, V as PopupMenuDataSurfaceProps, d as PopupMenuPositioner, p as PopupMenuPositionerAlign, q as PopupMenuPositionerProps, e as PopupMenuRadioGroupValue, W as PopupMenuRadioGroupValueProps, f as PopupMenuRadioItemIndicator, r as PopupMenuRadioItemIndicatorProps, s as PopupMenuRadioItemIndicatorState, g as PopupMenuShortcut, t as PopupMenuShortcutProps, v as PopupMenuShortcutState, h as PopupMenuSubmenuRoot, w as PopupMenuSubmenuRootProps, i as PopupMenuSubmenuTriggerIndicator, x as PopupMenuSubmenuTriggerIndicatorProps, y as PopupMenuSubmenuTriggerIndicatorState, j as PopupMenuSubpage, k as PopupMenuSubpageBack, l as PopupMenuSubpageBackItem, z as PopupMenuSubpageBackItemProps, A as PopupMenuSubpageBackItemState, B as PopupMenuSubpageBackProps, C as PopupMenuSubpageBackState, D as PopupMenuSubpageProps, a2 as ROOT_SUBPAGE_ID, X as RenderNodeFn, $ as SubmenuContext, a0 as SubpageContext, a1 as SubpageRegistration, a3 as SubpageStackContext, F as SubpageStackContextValue, U as UsePopupMenuItemParams, M as UsePopupMenuItemReturn, u as useAsyncMenuCoordinator, a9 as useDataPopupContext, Z as useDataSurfaceContext, m as useMaybeAsyncMenuCoordinator, aa as useMaybeDataPopupContext, _ as useMaybeDataSurfaceContext, G as useMaybeSubmenuContext, H as useMaybeSubpageContext, I as useMaybeSubpageStack, N as usePopupMenuItem, J as useSubmenuContext, K as useSubpageContext, L as useSubpageStack } from '../../data-surface-D1OilMDu.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { b as ListboxStore } from '../../ListboxStore-DPqpLlAL.js';
+export { V as VirtualItem } from '../../ListboxStore-DPqpLlAL.js';
+import { G as GetQualifiedRowIdFn, ai as SubmenuDef, am as SubpageDef, w as AsyncNodesConfig, a2 as NodeDef, Y as IncludeInDeepSearch, U as GroupBehavior, a5 as RadioGroupBehavior, ad as ScoredNode, R as DisplayRowNode, au as GetQualifiedRowIdContext, O as DisplayNode, B as BreadcrumbNode, V as GroupDef, a6 as RadioGroupDef, _ as ItemDef, a9 as RadioItemDef, D as CheckboxItemDef } from '../../types-lQCIvWW8.js';
+export { A as AsyncLoaderConfig, r as AsyncLoaderFetchStatus, s as AsyncLoaderLoadingPhase, t as AsyncLoaderResult, u as AsyncLoaderSource, v as AsyncLoaderStatus, x as AsyncRenderState, y as AsyncResultBehavior, z as AsyncState, E as CheckboxItemRenderParams, F as CheckboxItemRenderProps, H as DataListChildrenState, I as DataListProps, J as DataSubpagesChildrenState, K as DataSubpagesProps, L as DataSurfaceProps, M as DeepSearchConfig, N as DisplayGroupNode, Q as DisplayRadioGroupNode, S as DisplaySeparatorNode, T as DisplaySubpageNode, W as GroupRenderContext, X as GroupRenderParams, Z as InitialQueryBehavior, $ as ItemRenderParams, a0 as ItemRenderProps, a1 as LoaderComponentProps, P as PopupMenuCheckboxItem, f as PopupMenuCheckboxItemProps, g as PopupMenuCheckboxItemState, a as PopupMenuItem, h as PopupMenuItemProps, i as PopupMenuItemState, b as PopupMenuRadioGroup, j as PopupMenuRadioGroupProps, k as PopupMenuRadioGroupState, c as PopupMenuRadioItem, l as PopupMenuRadioItemProps, m as PopupMenuRadioItemState, d as PopupMenuSubmenuTrigger, n as PopupMenuSubmenuTriggerProps, o as PopupMenuSubmenuTriggerState, e as PopupMenuSubpageTrigger, p as PopupMenuSubpageTriggerProps, q as PopupMenuSubpageTriggerState, a3 as QueryAsyncNodesConfig, a4 as QueryDependentLoaderConfig, a7 as RadioGroupRenderParams, a8 as RadioGroupRenderProps, aa as RadioItemRenderParams, ab as RadioItemRenderProps, ac as RowRenderContext, ae as SeparatorDef, af as SeparatorRenderParams, ag as StaticAsyncNodesConfig, ah as StaticLoaderConfig, aj as SubmenuRenderParams, ak as SubmenuRenderProps, al as SubpageContentRenderParams, an as SubpageTriggerRenderParams, ao as SubpageTriggerRenderProps, ap as defineRadioGroup, aq as isDisplayGroupNode, ar as isDisplayRadioGroupNode, as as isDisplayRowNode, at as isDisplaySeparatorNode } from '../../types-lQCIvWW8.js';
+export { P as PopupMenuDataInput, a as PopupMenuDataInputProps, P as PopupMenuInput, a as PopupMenuInputProps, b as PopupMenuInputState } from '../../input-DF7D8YzW.js';
+export { P as PopupMenuLoading, a as PopupMenuLoadingProps, b as PopupMenuLoadingState } from '../../loading-TsgH6v92.js';
+import { I as ItemContextValue } from '../../use-listbox-item-BIi4eRPI.js';
+import { q as CheckedChangeReason, R as RadioValueChangeReason } from '../../events-BPr8sRGH.js';
+import '@base-ui/utils/store';
+import '@base-ui/react/popover';
+
+/**
+ * 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;
+
+declare const FocusOwnerContext: React.Context<FocusOwnerStore | null>;
+declare function useFocusOwner(): FocusOwnerStore;
+declare function useMaybeFocusOwner(): FocusOwnerStore | null;
+
+declare const OpenChainContext: React.Context<OpenChainStore | null>;
+declare function useOpenChain(): OpenChainStore;
+declare function useMaybeOpenChain(): OpenChainStore | null;
+
+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"
+}
+
+declare enum PopupMenuSubpageTriggerDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-subpage-trigger' | 'bazzaui-context-menu-subpage-trigger'}
+     */
+    slot = "bazzaui-[component]-subpage-trigger",
+    /**
+     * Present on subpage trigger elements.
+     */
+    subpageTrigger = "data-subpage-trigger",
+    /**
+     * Present when the target page is active.
+     */
+    popupOpen = "data-popup-open",
+    /**
+     * Present when the target page 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"
+}
+
+/**
+ * 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' | 'top' | 'bottom';
+/**
+ * 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, my?: 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;
+
+type MousePoint = [number, number];
+/**
+ * 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<MousePoint[]>;
+
+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",
+    /**
+     * Present while navigating between subpages in this popup.
+     * Useful for temporary transition adjustments during subpage focus handoff.
+     */
+    navigating = "data-navigating"
+}
+
+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;
+    /** Whether this menu tree currently ignores user interaction */
+    disabled: boolean;
+    /** 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;
+    /** Debug visualization flags. */
+    debug?: PopupMenuDebugOptions;
+    /**
+     * 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:
+ * - PopupMenuDebugContext (debug visualization flags)
+ * - 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;
+    /** Subpage context for back-stack navigation */
+    subpageContext?: SubpageContextValue | null;
+    /** Whether keyboard handling is enabled */
+    enabled: boolean;
+    /** Whether the menu currently ignores user interaction. */
+    disabled?: 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"
+}
+
+declare enum PopupMenuSubpageBackDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-subpage-back' | 'bazzaui-context-menu-subpage-back'}
+     */
+    slot = "bazzaui-[component]-subpage-back",
+    /**
+     * Present when navigating back is available.
+     */
+    canGoBack = "data-can-go-back",
+    /**
+     * Present when the button is disabled.
+     */
+    disabled = "data-disabled"
+}
+
+declare enum PopupMenuSubpageBackItemDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-dropdown-menu-subpage-back-item' | 'bazzaui-context-menu-subpage-back-item'}
+     */
+    slot = "bazzaui-[component]-subpage-back-item",
+    /**
+     * Present on subpage back item elements.
+     */
+    subpageBackItem = "data-subpage-back-item",
+    /**
+     * Present when the item is highlighted.
+     */
+    highlighted = "data-highlighted",
+    /**
+     * Present when the item is disabled.
+     */
+    disabled = "data-disabled"
+}
+
+/**
+ * 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;
+/**
+ * Computes a deterministic page ID for a subpage node.
+ *
+ * Priority:
+ * - explicit `node.pageId`
+ * - derived from breadcrumb ids/values + node id/value (slugified)
+ */
+declare function getSubpagePageId(node: SubpageDef, breadcrumbs: BreadcrumbNode[]): 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 isSubpageDef(node: NodeDef): node is SubpageDef;
+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 branch nodes (submenu/subpage) */
+    deep?: boolean;
+    /** Default include mode for descendant branch nodes */
+    includeInDeepSearch?: IncludeInDeepSearch;
+    /** Whether ancestors allow this subtree to participate in deep search */
+    descendantsIncluded?: boolean;
+    /** Parent breadcrumb nodes (branch 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 | SubpageDef;
+    /** Breadcrumb nodes (branch 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 branch nodes 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, normalizeQuery?: (query: string) => string): ScoredNode[];
+/**
+ * Sorts scored nodes by forced order, then score (descending).
+ */
+declare function sortByScore(nodes: ScoredNode[]): ScoredNode[];
+/**
+ * Partitions nodes by forced order bucket, then kind.
+ * Within each forceOrder bucket, items are shown before submenu/subpage triggers.
+ */
+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;
+    /** Optional query normalizer. Defaults to trimming whitespace. */
+    normalizeQuery?: (query: string) => string;
+    /** The node definitions to filter */
+    nodes: NodeDef[];
+    /** Currently highlighted node ID */
+    highlightedId: string | null;
+    /** Whether deep search is enabled */
+    deepSearch?: boolean;
+    /** Default include mode for descendant submenus during deep search */
+    includeInDeepSearch?: IncludeInDeepSearch;
+    /** 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 branch node (submenu/subpage) for registration.
+ */
+interface AsyncSubmenuInfo {
+    /** Unique identifier (uses node value and breadcrumbs) */
+    id: string;
+    /** Breadcrumbs path to this branch node */
+    breadcrumbs: string[];
+    /** The branch node definition */
+    node: SubmenuDef | SubpageDef;
+    /** The async configuration */
+    config: AsyncNodesConfig;
+}
+/**
+ * Collects all async branch nodes from a node tree.
+ * Recursively traverses groups and branches to find all async configurations.
+ */
+declare function collectAsyncSubmenus(nodes: NodeDef[], breadcrumbs?: string[], includeInDeepSearch?: IncludeInDeepSearch, descendantsIncluded?: boolean): 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 a submenu should appear in deep search results.
+ * `trigger-only` still includes the submenu trigger row.
+ */
+declare function shouldIncludeInDeepSearch(includeInDeepSearch: IncludeInDeepSearch | undefined): boolean;
+/**
+ * Checks if submenu descendants (rows inside submenu) should be included.
+ * `trigger-only` excludes descendants.
+ */
+declare function shouldIncludeSubmenuRowsInDeepSearch(includeInDeepSearch: IncludeInDeepSearch | undefined): 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, AsyncNodesConfig, type AsyncSubmenuInfo, BreadcrumbNode, CheckboxItemContext, type CheckboxItemContextValue, CheckboxItemDef, type ComponentName, ComponentNameContext, DisplayNode, DisplayRowNode, type FilterNodesOptions, FocusOwnerContext, FocusOwnerStore, GroupBehavior, GroupDef, IncludeInDeepSearch, ItemDef, NodeDef, OpenChainContext, OpenChainStore, PopupMenuArrowDataAttributes, PopupMenuBackdropDataAttributes, PopupMenuCheckboxItemDataAttributes, PopupMenuDebugOptions, PopupMenuIconDataAttributes, PopupMenuItemDataAttributes, PopupMenuListDataAttributes, PopupMenuPopupDataAttributes, PopupMenuPositionerDataAttributes, PopupMenuProviders, type PopupMenuProvidersProps, PopupMenuRadioGroupDataAttributes, PopupMenuRadioItemDataAttributes, PopupMenuScrollArrowDataAttributes, PopupMenuShortcutDataAttributes, PopupMenuSubmenuTriggerDataAttributes, PopupMenuSubpageBackDataAttributes, PopupMenuSubpageBackItemDataAttributes, PopupMenuSubpageTriggerDataAttributes, PopupSurfaceIdContext, RadioGroupBehavior, RadioGroupContext, type RadioGroupContextValue, RadioGroupDef, RadioItemContext, type RadioItemContextValue, RadioItemDef, ScoredNode, SubmenuContextValue, SubmenuDef, SubpageContextValue, SubpageDef, type UsePopupMenuKeyboardParams, type UsePopupMenuKeyboardReturn, VirtualAnchor, VirtualizationConfig, buildDisplayRowNodes, collectAsyncSubmenus, deduplicateNodes, defaultGetQualifiedRowId, filterNodes, flattenNodes, getBrowseNodesFlatten, getBrowseNodesPreserve, getFirstNavigableId, getNavigableIds, getSlotAttribute, getSmoothedHeading, getSubpagePageId, isCheckboxItemDef, isGroupDef, isItemDef, isRadioGroupDef, isRadioItemDef, isSeparatorDef, isSubmenuDef, isSubpageDef, mergeAsyncNodesIntoTree, mergeSubmenuNodes, partitionByKind, resolveAnchorSide, scoreNodes, shouldIncludeInDeepSearch, shouldIncludeSubmenuRowsInDeepSearch, shouldLoadEagerly, sortByScore, useAimGuard, useCheckboxItemContext, useComponentName, useFocusOwner, useMaybeComponentName, useMaybeFocusOwner, useMaybeOpenChain, useMouseTrail, useOpenChain, usePopupMenuKeyboard, usePopupSurfaceId, useRadioGroupContext, useRadioItemContext, willHitSubmenu };