@bazza-ui/react 0.1.0-canary.16 → 0.1.0-canary.17

package/dist/index-Cabqj7qI.d.ts

@@ -0,0 +1,2003 @@
+import { B as VirtualItem, L as ListboxStore, M as FilterFn, g as UseListboxItemReturn, h as UseListboxItemParams, q as GroupPositional, z as SearchNormalizer } from "./index-D8OrKThQ.js";
+import { $t as PopupMenuItemState, Et as TreeItemDef, L as DisplayNode, M as DataSurfaceProps, N as DeepSearchConfig, Q as LinkItemDef, Qt as PopupMenuItemProps, a as PopupMenuOpenChangeReason, b as AsyncResultBehavior, c as PopupMenuIdScope, d as AsyncContentMode, f as AsyncLoaderConfig, h as AsyncLoaderResult, j as DataListChildrenState, l as PopupMenuNode, n as HighlightChangeEventDetails, nt as NodeDef, o as RadioValueChangeEventDetails, on as ChangeEventDetails, q as IncludeInDeepSearch, r as PopupMenuHighlightChangeHandler, s as GetResolvedIdFn, t as CheckboxValueChangeEventDetails, u as UnresolvedMenuNode, x as AsyncState } from "./events-DDOsDu4X.js";
+import { n as ComponentRenderFn, t as ComponentProps } from "./types-BbN28E3_.js";
+import * as React from "react";
+import { ReactStore } from "@base-ui/utils/store";
+import { Popover, PopoverArrowProps, PopoverBackdropProps, PopoverPopupProps, PopoverPortalProps, PopoverPositionerProps, PopoverRootProps } from "@base-ui/react/popover";
+//#region src/internal/popup-menu/store/FocusOwnerStore.d.ts
+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, Record<string, never>, 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;
+}
+//#endregion
+//#region src/internal/popup-menu/contexts/focus-owner-context.d.ts
+declare function useFocusOwner(): FocusOwnerStore;
+//#endregion
+//#region src/internal/popup-menu/store/OpenChainStore.d.ts
+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, Record<string, never>, 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;
+}
+//#endregion
+//#region src/internal/popup-menu/contexts/open-chain-context.d.ts
+declare function useOpenChain(): OpenChainStore;
+//#endregion
+//#region src/internal/popup-menu/contexts/popup-menu-context.d.ts
+/**
+ * Virtual anchor for positioning the menu at a specific point.
+ * Used by ContextMenu to position at cursor location.
+ */
+interface VirtualAnchor {
+  getBoundingClientRect(): DOMRect;
+}
+/**
+ * Virtualization configuration passed from Root/Submenu to Surface.
+ */
+interface VirtualizationConfig {
+  /** Whether virtualization mode is enabled */
+  virtualized: boolean;
+  /** Pre-registered items for virtualization */
+  items: VirtualItem[];
+  /**
+   * Callback when highlighted item changes (for scroll sync).
+   * The third parameter contains event details including the reason for the change.
+   */
+  onHighlightChange?: (id: string | null, index: number, eventDetails: HighlightChangeEventDetails) => void;
+}
+/**
+ * Shared context value for popup menus.
+ * Both DropdownMenu.Root and ContextMenu.Root provide this context.
+ */
+interface PopupMenuContextValue {
+  /** The Listbox store instance */
+  store: ListboxStore;
+  /** Whether this menu tree currently ignores user interaction. */
+  disabled: boolean;
+  /** Nesting depth: 0 = root menu, 1+ = submenu */
+  depth: number;
+  /** Close the entire menu tree (deepest submenu to root, sequentially) */
+  closeAll: (reason?: PopupMenuOpenChangeReason, event?: Event) => void;
+  /**
+   * Internal: when true, Surface handles Tab explicitly (close the tree, or
+   * cycle through focus zones). Enabled only by DropdownMenu.Root and
+   * ContextMenu.Root — never Select or Combobox.
+   */
+  explicitTabBehavior: boolean;
+  /**
+   * Internal: what Tab does under `explicitTabBehavior` when the surface (and
+   * its ancestors) have no focus-zone tabbables. `'close'` closes the whole
+   * tree (dropdown/context-menu). `'inert'` swallows the event, keeping focus
+   * where it is (command palette).
+   */
+  tabWithoutZones: 'close' | 'inert';
+  /**
+   * Internal: DOM focus stays on an element outside the popup (Combobox's
+   * input, a suggestion menu's host input) for as long as the menu is open.
+   * The root popup then neither moves focus in on open nor returns it on close.
+   */
+  externalFocus: boolean;
+  /** Register a surface (submenu) for closeAll tracking. Returns unregister function. */
+  registerSurface: (depth: number, setOpen: (open: boolean) => void) => () => void;
+  /** Virtualization configuration (if enabled) */
+  virtualization?: VirtualizationConfig;
+  /**
+   * Virtual anchor for positioning.
+   * Used by ContextMenu to position at cursor location.
+   * DropdownMenu uses the Popover's anchor (trigger button) instead.
+   */
+  virtualAnchor?: VirtualAnchor;
+  /**
+   * Type of menu for positioning logic.
+   * - 'dropdown': positions relative to trigger button
+   * - 'context': positions at cursor with fixed positioning
+   */
+  menuType: 'dropdown' | 'context';
+  /**
+   * 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';
+  /**
+   * Whether shift-click and Shift+Enter perform range selection on checkbox items.
+   * @default true
+   */
+  rangeSelection: boolean;
+  /**
+   * Whether pressing a checkbox item and dragging performs drag selection, and
+   * how rows the pointer moves back over are treated.
+   * @default false
+   */
+  dragSelection: false | 'keep' | 'rubber-band';
+  /**
+   * Text announced to assistive technology after a range or drag selection
+   * changes rows. Defaults to English ("3 items checked").
+   */
+  getAriaSelectionText?: (count: number, checked: boolean) => string;
+}
+declare const PopupMenuContext: React.Context<PopupMenuContextValue | null>;
+/**
+ * Hook to access the popup menu context.
+ * Throws if used outside a popup menu.
+ */
+declare function usePopupMenuContext(): PopupMenuContextValue;
+/**
+ * Hook to optionally access the popup menu context.
+ * Returns null if used outside a popup menu.
+ */
+declare function useMaybePopupMenuContext(): PopupMenuContextValue | null;
+//#endregion
+//#region src/internal/popup-menu/contexts/popup-menu-debug-context.d.ts
+interface PopupMenuSafeTriangleAreaDebugOptions {
+  enabled?: boolean;
+  idleColor?: string;
+  successColor?: string;
+  missColor?: string;
+  triangleFillOpacity?: number;
+  overlayOpacity?: number;
+  showStroke?: boolean;
+  strokeWidth?: number;
+  strokeDasharray?: string;
+  showDots?: boolean;
+  dotRadius?: number;
+  freezeOnPointerLeave?: boolean;
+  persistOnSuccess?: boolean;
+  showMissState?: boolean;
+  missFreezeDuration?: number;
+}
+type PopupMenuSafeTriangleAreaDebugConfig = boolean | PopupMenuSafeTriangleAreaDebugOptions;
+/**
+ * Debug configuration available on popup-menu roots.
+ */
+interface PopupMenuDebugOptions {
+  /**
+   * Shows/configures the safe triangle area used by submenu aim guard.
+   * @default false
+   */
+  showSafeTriangleArea?: PopupMenuSafeTriangleAreaDebugConfig;
+  /**
+   * @deprecated Use `showSafeTriangleArea` instead.
+   */
+  showSubmenuSafeTriangleArea?: boolean;
+  /**
+   * Enables console logging for aim-guard diagnostics.
+   * @default false
+   */
+  logAimGuardEvents?: boolean;
+}
+//#endregion
+//#region src/internal/popup-menu/contexts/popup-surface-id-context.d.ts
+/**
+ * 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>;
+//#endregion
+//#region src/internal/popup-menu/contexts/submenu-context.d.ts
+interface SubmenuContextValue {
+  /** Whether the submenu is open */
+  open: boolean;
+  /** Set the submenu open state */
+  setOpen: (open: boolean) => void;
+  /**
+   * Latch set by explicit close actions (keyboard ArrowLeft/Ctrl+H/Escape-in-submenu,
+   * or clicking the open trigger). While set and the trigger remains highlighted,
+   * pointer/keyboard auto-open is suppressed. Reset when highlight leaves the trigger.
+   */
+  suppressAutoOpenRef: React.MutableRefObject<boolean>;
+  /** Reference to the trigger element */
+  triggerRef: React.RefObject<HTMLElement | null>;
+  /** Reference to the submenu content element (for aim guard rect calculations) */
+  contentRef: React.RefObject<HTMLElement | null>;
+  /** Surface ID of the parent menu (for keyboard navigation back) */
+  parentSurfaceId: string;
+  /** Surface ID of this submenu (for keyboard navigation into) */
+  childSurfaceId: string;
+  /**
+   * Whether pressing Escape in this submenu closes the entire menu from the root.
+   * When true, Escape closes the entire menu tree.
+   * When false, Escape only closes this submenu and moves focus to the parent.
+   * @default true
+   */
+  closeRootOnEsc: boolean;
+}
+declare function useSubmenuContext(): SubmenuContextValue;
+declare function useMaybeSubmenuContext(): SubmenuContextValue | null;
+//#endregion
+//#region src/internal/popup-menu/contexts/subpage-context.d.ts
+interface SubpageContextValue {
+  /** Current page ID. */
+  pageId: string;
+  /** Surface ID for this page. */
+  surfaceId: string;
+  /** Surface ID for the previous page, if available. */
+  parentSurfaceId: string | null;
+  /** Whether this page is currently active. */
+  isActive: boolean;
+  /** Whether Escape should close the entire menu tree from this page. */
+  closeRootOnEsc: boolean;
+  /** Navigate back one page. Returns true when navigation happened. */
+  goBack: () => boolean;
+}
+declare function useSubpageContext(): SubpageContextValue;
+declare function useMaybeSubpageContext(): SubpageContextValue | null;
+//#endregion
+//#region src/internal/popup-menu/contexts/subpage-stack-context.d.ts
+interface SubpageRegistration {
+  pageId: string;
+  surfaceId: string;
+  closeRootOnEsc: boolean;
+}
+interface SubpageStackContextValue {
+  /** Active page ID; `null` when the root surface is active. */
+  activePageId: string | null;
+  /** Surface ID of the root surface. */
+  rootSurfaceId: string;
+  /** Surface ID for the currently active page. */
+  activeSurfaceId: string;
+  /** Whether there is a previous page to navigate back to. */
+  canGoBack: boolean;
+  /** Whether Escape in the active page should close the entire menu tree. */
+  shouldCloseRootOnEsc: boolean;
+  /** Open page IDs, bottom to top; empty at root. */
+  stack: readonly string[];
+  /** Register a page and return an unregister cleanup. */
+  registerPage: (registration: SubpageRegistration) => () => void;
+  /** Push a page onto the stack. Returns true when navigation happened. */
+  openPage: (pageId: string) => boolean;
+  /** Pop one page from the stack. Returns true when navigation happened. */
+  goBack: () => boolean;
+  /** Resolve a surface ID for a page ID. */
+  getSurfaceId: (pageId: string) => string | null;
+}
+declare const SubpageStackContext: React.Context<SubpageStackContextValue | null>;
+declare function useSubpageStack(): SubpageStackContextValue;
+declare function useMaybeSubpageStack(): SubpageStackContextValue | null;
+//#endregion
+//#region src/internal/popup-menu/menu-tree/resolver.d.ts
+/**
+ * Owns the single resolved node tree for one menu root. Content may be
+ * re-supplied at any time (`setContent`) and late defs may be grafted under
+ * an already-resolved parent (`graft`); both reconcile by id with a
+ * reference fast path, so node instances are stable and repeat calls with
+ * identical arguments are no-ops.
+ */
+interface MenuTreeResolver {
+  /** The Resolved ID seam this resolver was created with. */
+  readonly getResolvedId: GetResolvedIdFn;
+  /** Definition Key uniqueness policy, captured when this resolver is created. */
+  readonly idScope: PopupMenuIdScope;
+  /** Current root nodes, in def order. */
+  readonly rootNodes: readonly PopupMenuNode[];
+  /** Re-supply the root def list and reconcile the whole tree. */
+  setContent(defs: readonly NodeDef[]): void;
+  /**
+   * Resolve `defs` under `parent` (the graft point) and reconcile them
+   * against `parent.children`. `defs` is the parent's full child list
+   * from the graft source's perspective (static + late defs).
+   */
+  graft(parent: PopupMenuNode, defs: readonly NodeDef[]): void;
+  /** Node whose current `def` is reference-equal to `def`, if any. */
+  getNodeForDef<D extends NodeDef>(def: D): PopupMenuNode<D> | undefined;
+  /** First registration wins; best-effort when ids collide. */
+  getNodeById(id: string): PopupMenuNode | undefined;
+}
+//#endregion
+//#region src/internal/popup-menu/hooks/use-popup-menu-root.d.ts
+interface UsePopupMenuRootParams {
+  /**
+   * Computes canonical Resolved IDs for data-first content from the Unresolved Menu Node (definitional facts only).
+   * @default explicit `def.id` verbatim, else the joined definition path
+   * Read once when the menu root mounts — later changes have no effect.
+   */
+  getResolvedId?: GetResolvedIdFn;
+  /** Definition Key uniqueness scope. Read once when the menu root mounts. */
+  idScope?: PopupMenuIdScope;
+  /**
+   * 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. `id` is first; `node` is the
+   * resolved menu node enrichment and may be null.
+   * The fourth parameter contains event details including the reason for the change.
+   */
+  onHighlightChange?: PopupMenuHighlightChangeHandler<HighlightChangeEventDetails>;
+  /**
+   * 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';
+  /**
+   * Elements outside the menu that don't dismiss it (e.g. a suggestion menu's
+   * host input): pressing one, or moving focus from the menu to one, is not an
+   * outside press or a focus-out. Read when the event happens, so the returned
+   * elements may change over time.
+   */
+  getDismissExemptElements?: () => ReadonlyArray<Element | null | undefined>;
+  /**
+   * Whether the menu should ignore user interaction.
+   * Can be controlled declaratively via this prop, or imperatively via actionsRef.setDisabled().
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Initial disabled state for imperative usage.
+   * Ignored when `disabled` prop is true.
+   * @default false
+   */
+  defaultDisabled?: boolean;
+}
+interface PopupMenuRootActions {
+  /** Close the menu tree imperatively. */
+  close: () => void;
+  /** Unmount the popup imperatively (when keep-mounted mode is enabled). */
+  unmount: () => void;
+  /** Enable/disable the menu tree imperatively. */
+  setDisabled: (disabled: boolean) => void;
+}
+interface UsePopupMenuRootReturn {
+  /** The menu-tree resolver for this menu root. */
+  menuTreeResolver: MenuTreeResolver;
+  /** 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;
+  /** Whether the menu currently ignores user interaction. */
+  disabled: boolean;
+  /** Update imperative disabled state. */
+  setDisabled: (disabled: boolean) => 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;
+//#endregion
+//#region src/internal/popup-menu/hooks/use-subpage-stack-state.d.ts
+interface UseSubpageStackStateParams {
+  /** Surface ID of the root surface (the popup's own surface). */
+  surfaceId: string;
+  /** Listbox store; used to chain onPopupCloseComplete reset. Null-safe. */
+  store: ListboxStore | null;
+}
+interface UseSubpageStackStateReturn {
+  /** Context value provided to SubpageStackContext consumers. */
+  subpageStackContextValue: SubpageStackContextValue;
+  /** Whether subpage navigation is in its transient animation window. */
+  isSubpageNavigating: boolean;
+  /** Whether any subpage is currently open. */
+  hasOpenSubpage: boolean;
+  /** Active subpage ID, or null when the root surface is active. */
+  subpageId: string | null;
+  /** Ordered stack of open subpage IDs. */
+  openSubpageIds: string[];
+}
+/**
+ * Centralized subpage stack state for popup menu surfaces.
+ */
+declare function useSubpageStackState(params: UseSubpageStackStateParams): UseSubpageStackStateReturn;
+//#endregion
+//#region src/internal/popup-menu/components/arrow/arrow.d.ts
+interface PopupMenuArrowProps extends PopoverArrowProps {}
+/**
+ * An optional arrow element to render alongside the popup menu.
+ * This can be used to help visually link the trigger with the popup.
+ * Must be rendered inside `Popup`.
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuArrow: React.ForwardRefExoticComponent<Omit<PopupMenuArrowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuArrow {
+  type Props = PopupMenuArrowProps;
+  type State = Popover.Arrow.State;
+}
+//#endregion
+//#region src/internal/popup-menu/components/backdrop/backdrop.d.ts
+interface PopupMenuBackdropProps extends PopoverBackdropProps {
+  /**
+   * Controls when the backdrop becomes visible for submenus.
+   * - `"focus"`: Show when the submenu becomes the focus owner (prevents flicker on hover).
+   *   If a deeper submenu is open, the backdrop remains visible.
+   * - `"open"`: Show as soon as the submenu opens, regardless of focus.
+   *
+   * @default "focus" for submenus, "open" for root menu
+   */
+  showOn?: 'focus' | 'open';
+}
+/**
+ * An overlay displayed beneath the popup menu.
+ *
+ * For submenus with `showOn="focus"` (default), the backdrop visibility follows these rules:
+ * - If this submenu is at the end of the open chain (deepest), it must be
+ *   the focus owner to show the backdrop (prevents flicker on hover)
+ * - If this submenu is in the chain but not at the end (has a deeper submenu open),
+ *   the backdrop remains visible
+ *
+ * With `showOn="open"`, the backdrop shows as soon as the submenu opens.
+ *
+ * Renders a `<div>` element with `pointer-events: none`.
+ */
+declare const PopupMenuBackdrop: React.ForwardRefExoticComponent<Omit<PopupMenuBackdropProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuBackdrop {
+  type Props = PopupMenuBackdropProps;
+  type State = Popover.Backdrop.State;
+}
+//#endregion
+//#region src/internal/popup-menu/components/popup/popup.data-attrs.d.ts
+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"
+}
+//#endregion
+//#region src/internal/popup-menu/components/popup/popup.d.ts
+interface PopupMenuPopupState extends Popover.Popup.State {
+  /**
+   * Whether this popup is a submenu (not the root menu).
+   */
+  isSubmenu: boolean;
+  /**
+   * Whether any non-root subpage is currently open.
+   */
+  hasOpenSubpage: boolean;
+  /**
+   * Active subpage ID, or null when the root surface is active.
+   */
+  subpageId: string | null;
+  /**
+   * Ordered stack of open non-root subpage IDs.
+   * For nested subpages this includes each page in open order.
+   */
+  openSubpageIds: string[];
+}
+interface PopupMenuPopupProps extends Omit<PopoverPopupProps, 'className' | 'render'> {
+  /**
+   * CSS class applied to the element, or a function that
+   * returns a class based on the component's state.
+   */
+  className?: string | ((state: PopupMenuPopupState) => string);
+  /**
+   * Allows replacing the popup element with a custom element.
+   * The render state includes popup + subpage navigation state.
+   */
+  render?: React.ReactElement | ComponentRenderFn<React.HTMLAttributes<HTMLElement>, PopupMenuPopupState>;
+}
+/**
+ * A container for the popup menu contents.
+ * Wraps Popover.Popup with:
+ * - Aim guard clearing when pointer enters submenu
+ * - Focus ownership transfer when pointer enters submenu
+ * - Auto-focus disabled for submenus (focus managed by FocusOwner system)
+ *
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuPopup: React.ForwardRefExoticComponent<Omit<PopupMenuPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuPopup {
+  type Props = PopupMenuPopupProps;
+  type State = PopupMenuPopupState;
+}
+//#endregion
+//#region src/internal/popup-menu/components/portal/portal.d.ts
+interface PopupMenuPortalProps extends PopoverPortalProps {}
+/**
+ * A portal element that moves the popup to a different part of the DOM.
+ * By default, the portal element is appended to `<body>`.
+ */
+declare const PopupMenuPortal: import("react").ForwardRefExoticComponent<Omit<PopoverPortalProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuPortal {
+  type Props = PopoverPortalProps;
+  type State = Popover.Portal.State;
+}
+//#endregion
+//#region src/internal/popup-menu/components/positioner/positioner.css-vars.d.ts
+declare enum PopupMenuPositionerCssVars {
+  /**
+   * The available width between the trigger and the edge of the viewport.
+   * @type {number}
+   */
+  availableWidth = "--available-width",
+  /**
+   * The available height between the trigger and the edge of the viewport.
+   * @type {number}
+   */
+  availableHeight = "--available-height",
+  /**
+   * The anchor's width.
+   * @type {number}
+   */
+  anchorWidth = "--anchor-width",
+  /**
+   * The anchor's height.
+   * @type {number}
+   */
+  anchorHeight = "--anchor-height",
+  /**
+   * The coordinates that this element is anchored to. Used for animations and transitions.
+   * @type {string}
+   */
+  transformOrigin = "--transform-origin",
+  /**
+   * The width of the positioner element.
+   * @type {number}
+   */
+  positionerWidth = "--positioner-width",
+  /**
+   * The height of the positioner element.
+   * @type {number}
+   */
+  positionerHeight = "--positioner-height"
+}
+//#endregion
+//#region src/internal/popup-menu/components/positioner/positioner.d.ts
+/**
+ * Extended align options for popup menus.
+ * - 'start' | 'center' | 'end': Standard Base UI alignment
+ * - 'list-start': Align trigger top with the top of the List component (horizontal sides only)
+ */
+type PopupMenuPositionerAlign = PopoverPositionerProps['align'] | 'list-start';
+interface PopupMenuPositionerProps extends Omit<PopoverPositionerProps, 'align' | 'style'> {
+  /**
+   * Override the virtual anchor from context.
+   * Useful for nested menus that need different positioning.
+   */
+  virtualAnchor?: {
+    getBoundingClientRect(): DOMRect;
+  };
+  /**
+   * How to align the popup relative to the specified side.
+   * - 'start': align to start of anchor
+   * - 'center': align to center of anchor
+   * - 'end': align to end of anchor
+   * - 'list-start': align the List component's top with the anchor top (horizontal sides only)
+   * @default 'start' for submenus, 'center' for root dropdowns
+   */
+  align?: PopupMenuPositionerAlign;
+  /**
+   * Custom styles for the positioner.
+   * Note: During list-start alignment measurement, `transition: 'none'` is
+   * temporarily applied to prevent visual flash.
+   */
+  style?: React.CSSProperties;
+}
+/**
+ * Positions the popup menu against its anchor.
+ * Wraps Popover.Positioner with:
+ * - Automatic virtualAnchor from PopupMenuContext (for context menus)
+ * - Smart default positioning based on depth and menu type
+ * - Smart collision avoidance: shift for horizontal menus, flip for vertical
+ * - 'list-start' alignment for horizontal submenus
+ *
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuPositioner: React.ForwardRefExoticComponent<Omit<PopupMenuPositionerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuPositioner {
+  type Props = PopupMenuPositionerProps;
+  type State = Popover.Positioner.State;
+}
+//#endregion
+//#region src/internal/popup-menu/contexts/component-name-context.d.ts
+/**
+ * Component name used for generating bazzaui-* slot attributes.
+ * E.g., 'dropdown-menu', 'context-menu', 'select', 'combobox', 'command-menu'
+ */
+type ComponentName = 'dropdown-menu' | 'context-menu' | 'select' | 'combobox' | 'command-menu' | 'suggestion-menu';
+//#endregion
+//#region src/internal/popup-menu/components/providers.d.ts
+interface PopupMenuProvidersProps {
+  /** Created by `usePopupMenuRoot`, one per menu root. */
+  menuTreeResolver: MenuTreeResolver;
+  /** 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;
+  /**
+   * Internal: when true, Surface handles Tab explicitly (close the tree, or
+   * cycle through focus zones). Enabled only by DropdownMenu.Root and
+   * ContextMenu.Root — never Select or Combobox.
+   */
+  explicitTabBehavior?: boolean;
+  /**
+   * Internal: what Tab does under `explicitTabBehavior` when the surface (and
+   * its ancestors) have no focus-zone tabbables. `'close'` closes the whole
+   * tree (dropdown/context-menu). `'inert'` swallows the event, keeping focus
+   * where it is (command palette).
+   */
+  tabWithoutZones?: 'close' | 'inert';
+  /**
+   * Internal: DOM focus stays on an element outside the popup for as long as
+   * the menu is open, so the root popup neither takes nor returns focus.
+   */
+  externalFocus?: boolean;
+  /** 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';
+  /**
+   * Whether shift-click and Shift+Enter perform range selection on checkbox items.
+   * @default true
+   */
+  rangeSelection?: boolean;
+  /**
+   * Whether pressing a checkbox item and dragging performs drag selection, and
+   * how rows the pointer moves back over are treated.
+   * @default false
+   */
+  dragSelection?: false | 'keep' | 'rubber-band';
+  /**
+   * Text announced to assistive technology after a range or drag selection
+   * changes rows. Defaults to English ("3 items checked").
+   */
+  getAriaSelectionText?: (count: number, checked: boolean) => string;
+  /**
+   * 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.Element;
+//#endregion
+//#region src/internal/popup-menu/hooks/use-popup-menu-keyboard.d.ts
+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;
+//#endregion
+//#region src/internal/popup-menu/hooks/use-forwarded-key-down.d.ts
+/** A key press from an element outside the menu: a DOM event or a React one. */
+type ForwardedKeyboardEvent = KeyboardEvent | React.KeyboardEvent;
+/**
+ * Handles a key press that happened outside the menu. Returns `true` when the
+ * menu used the key (and prevented its default action), `false` when the key
+ * should keep its normal meaning in the element it was pressed in.
+ */
+type ForwardKeyDown = (event: ForwardedKeyboardEvent) => boolean;
+/**
+ * Keyboard params for a forwarded key press. There is no `onKeyDown`: the
+ * member handles its own keys before forwarding the rest.
+ */
+type UseForwardedKeyDownParams = Omit<UsePopupMenuKeyboardParams, 'skipFocusOwnerCheck' | 'enableTypeToSearch' | 'onKeyDown'>;
+/**
+ * Lets an element outside the menu (an editor, a text field) forward its key
+ * presses into the menu's keyboard handling: arrows, Ctrl+N/P, Home/End, Enter
+ * and the rest of the listbox bindings, with the same IME guard. DOM focus
+ * never has to enter the menu.
+ *
+ * A key counts as handled only when the menu acts on it, so the element keeps
+ * its own behaviour otherwise: nothing is handled while the menu is closed,
+ * navigation keys need at least one row, Enter needs a highlighted row it can
+ * activate, and printable characters always belong to the element (they never
+ * trigger item shortcuts).
+ *
+ * Checkbox span selection (Shift+Arrow) needs the Surface's selection context,
+ * so it applies only when the hook is mounted inside a Surface.
+ *
+ * The returned function is stable, so it can be handed to code outside React.
+ * Which keys a member forwards, and what Escape or Tab mean for it, is the
+ * member's policy.
+ */
+declare function useForwardedKeyDown(params: UseForwardedKeyDownParams): ForwardKeyDown;
+//#endregion
+//#region src/internal/popup-menu/hooks/use-popup-menu-item.d.ts
+interface UsePopupMenuItemParams extends Omit<UseListboxItemParams, 'aimGuard' | 'onAfterSelect'> {
+  /**
+   * Whether clicking this item should close the menu.
+   * @default true
+   */
+  closeOnClick?: boolean;
+}
+interface UsePopupMenuItemReturn extends UseListboxItemReturn {
+  /** Whether this item is effectively disabled (item disabled OR menu disabled). */
+  disabled: boolean;
+}
+/**
+ * Hook that provides all shared logic for navigatable/highlightable popup menu items.
+ * This is a thin wrapper around useListboxItem that automatically adds aim-guard
+ * support and handles close-on-click behavior.
+ *
+ * @see useListboxItem for full documentation
+ */
+declare function usePopupMenuItem(params: UsePopupMenuItemParams): UsePopupMenuItemReturn;
+//#endregion
+//#region src/internal/popup-menu/components/icon/icon.d.ts
+interface PopupMenuIconState extends Record<string, unknown> {
+  /**
+   * Whether the popup is currently open.
+   */
+  open: boolean;
+}
+interface PopupMenuIconProps extends ComponentProps<'span', PopupMenuIcon.State> {}
+/**
+ * An icon that indicates the trigger opens a popup.
+ * Typically used inside the trigger to show a chevron or dropdown arrow.
+ * Renders a `<span>` element.
+ */
+declare const PopupMenuIcon: React.ForwardRefExoticComponent<Omit<PopupMenuIcon.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace PopupMenuIcon {
+  type State = PopupMenuIconState;
+  interface Props extends PopupMenuIconProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/empty/empty.d.ts
+interface PopupMenuEmptyState extends Record<string, unknown> {
+  first: boolean;
+  last: boolean;
+}
+interface PopupMenuEmptyProps extends ComponentProps<'div', PopupMenuEmpty.State> {
+  children: React.ReactNode;
+}
+/**
+ * Renders when no items match the current search query.
+ * Only visible when there's an active search with zero results.
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuEmpty: React.ForwardRefExoticComponent<Omit<PopupMenuEmpty.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuEmpty {
+  type State = PopupMenuEmptyState;
+  interface Props extends PopupMenuEmptyProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/input/input.d.ts
+interface PopupMenuInputState extends Record<string, unknown> {
+  /**
+   * Whether the input is active (visible).
+   * Only relevant when `hideUntilActive` is true.
+   */
+  active: boolean;
+}
+interface PopupMenuInputProps extends Omit<ComponentProps<'input', PopupMenuInput.State>, 'value' | 'onChange' | 'type'> {
+  /**
+   * Controlled value for the search input.
+   * If provided, this takes precedence over the Surface's search state.
+   */
+  value?: string;
+  /**
+   * Callback when the input value changes.
+   */
+  onValueChange?: (value: string) => void;
+  /**
+   * When true, the input is not rendered until the user starts typing.
+   * The List receives focus initially, and typing a character activates the input.
+   * Once activated, the input stays visible until the menu closes.
+   * @default false
+   */
+  hideUntilActive?: boolean;
+  /**
+   * When true, Backspace in an empty subpage input navigates back one page.
+   * @default false
+   */
+  backspaceGoesBack?: boolean;
+}
+/**
+ * Search input for filtering popup menu items.
+ * Handles keyboard navigation (Arrow keys, Ctrl+N/P, Enter).
+ * Renders an `<input>` element.
+ */
+declare const PopupMenuInput: React.ForwardRefExoticComponent<Omit<PopupMenuInput.Props, "ref"> & React.RefAttributes<HTMLInputElement>>;
+declare namespace PopupMenuInput {
+  type State = PopupMenuInputState;
+  interface Props extends PopupMenuInputProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/list/list.css-vars.d.ts
+/**
+ * CSS custom properties applied to the List component.
+ */
+declare enum PopupMenuListCssVars {
+  /**
+   * The maximum measured row width.
+   * Applied when `measureRowWidth` is true.
+   * Useful for keeping virtualized lists at a consistent width.
+   * @type {number}
+   */
+  rowWidth = "--row-width"
+}
+//#endregion
+//#region src/internal/popup-menu/components/list/list.d.ts
+/**
+ * State passed to children render function.
+ */
+interface PopupMenuListChildrenState {
+  /** Current search query */
+  search: string;
+  /** Number of items matching the current filter */
+  filteredCount: number;
+}
+interface PopupMenuListState extends Record<string, unknown> {}
+interface PopupMenuListProps extends Omit<ComponentProps<'div', PopupMenuList.State>, 'children' | 'content'> {
+  /**
+   * Content to render inside the list.
+   * Can be a render function that receives the current search state.
+   */
+  children: React.ReactNode | ((state: PopupMenuListChildrenState) => React.ReactNode);
+  /**
+   * Accessible label for the listbox.
+   * @default 'Suggestions'
+   */
+  label?: string;
+  /**
+   * When true, measures row widths and applies `--row-width` CSS variable.
+   * Keeps the list at the maximum width seen while scrolling.
+   * Useful for virtualized lists where content width varies.
+   * @default true
+   */
+  measureRowWidth?: boolean;
+  /**
+   * Maximum width cap for row measurement (in pixels).
+   * Only used when `measureRowWidth` is true.
+   */
+  maxRowWidth?: number;
+  /**
+   * Ref to the element that owns the list's scroll position.
+   * Use when the semantic list is rendered inside another scroll container.
+   */
+  scrollContainerRef?: React.RefObject<HTMLElement | null>;
+  /**
+   * When any value in this array changes, previously-measured row IDs are
+   * cleared so rows re-measure (the sticky max width is kept — it only ever
+   * grows until the menu closes). Use for state that changes row content for
+   * the same IDs, e.g. tree rows that re-render as breadcrumb rows when deep
+   * search toggles. Values are compared with `Object.is`, so pass stable
+   * primitives — an inline object recreated each render would re-trigger
+   * every render.
+   */
+  remeasureDependencies?: React.DependencyList;
+}
+declare const PopupMenuList: React.ForwardRefExoticComponent<Omit<PopupMenuList.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuList {
+  type State = PopupMenuListState;
+  type ChildrenState = PopupMenuListChildrenState;
+  interface Props extends PopupMenuListProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/loading/loading.d.ts
+interface PopupMenuLoadingState extends Record<string, unknown> {
+  first: boolean;
+  last: boolean;
+}
+interface PopupMenuLoadingProps extends ComponentProps<'div', PopupMenuLoading.State> {
+  children: React.ReactNode;
+  /**
+   * Whether to force render the loading indicator regardless of async loading state.
+   * When true, the component always renders, allowing you to control visibility externally.
+   * @default false
+   */
+  forceMount?: boolean;
+}
+/**
+ * Renders when async content is in initial loading.
+ * Only visible during first-load phases (unless `forceMount` is true).
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuLoading: React.ForwardRefExoticComponent<Omit<PopupMenuLoading.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuLoading {
+  type State = PopupMenuLoadingState;
+  interface Props extends PopupMenuLoadingProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/scroll-arrow/scroll-arrow.d.ts
+type Direction = 'up' | 'down';
+interface PopupMenuScrollArrowState extends Record<string, unknown> {
+  /**
+   * The scroll direction this arrow controls.
+   */
+  direction: Direction;
+  /**
+   * Whether there is content to scroll in this direction.
+   */
+  visible: boolean;
+}
+interface PopupMenuScrollArrowProps extends ComponentProps<'div', PopupMenuScrollArrow.State> {
+  /**
+   * The direction to scroll when hovering over this arrow.
+   */
+  direction: Direction;
+  /**
+   * Whether to keep the element mounted when there's nothing to scroll.
+   * When false (default), the element is not rendered.
+   * When true, the element is rendered but can be styled via `data-visible="false"`.
+   * @default false
+   */
+  keepMounted?: boolean;
+  /**
+   * Scroll speed in pixels per frame.
+   * @default 10
+   */
+  scrollSpeed?: number;
+}
+/**
+ * Base scroll arrow component used by ScrollUpArrow and ScrollDownArrow.
+ * Shows when there is content to scroll in the specified direction.
+ * Scrolls the list continuously while pointer is over it.
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuScrollArrow: React.ForwardRefExoticComponent<Omit<PopupMenuScrollArrow.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuScrollArrow {
+  type State = PopupMenuScrollArrowState;
+  interface Props extends PopupMenuScrollArrowProps {}
+}
+interface PopupMenuScrollUpArrowProps extends Omit<PopupMenuScrollArrowProps, 'direction'> {}
+/**
+ * A scroll indicator that appears when there's content above.
+ * Scrolls the list up continuously while pointer is over it.
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuScrollUpArrow: React.ForwardRefExoticComponent<Omit<PopupMenuScrollUpArrow.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuScrollUpArrow {
+  type State = PopupMenuScrollArrowState;
+  interface Props extends PopupMenuScrollUpArrowProps {}
+}
+interface PopupMenuScrollDownArrowProps extends Omit<PopupMenuScrollArrowProps, 'direction'> {}
+/**
+ * A scroll indicator that appears when there's content below.
+ * Scrolls the list down continuously while pointer is over it.
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuScrollDownArrow: React.ForwardRefExoticComponent<Omit<PopupMenuScrollDownArrow.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuScrollDownArrow {
+  type State = PopupMenuScrollArrowState;
+  interface Props extends PopupMenuScrollDownArrowProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/surface/surface.d.ts
+interface PopupMenuSurfaceState extends Record<string, unknown> {}
+interface PopupMenuSurfaceProps extends Omit<ComponentProps<'div', PopupMenuSurface.State>, 'content'>, DataSurfaceProps {
+  /**
+   * Filter function for matching items against search query.
+   * Returns a score between 0 and 1 (0 = no match, > 0 = match).
+   * Pass `false` to disable filtering entirely.
+   * @default commandScore (fuzzy matching)
+   */
+  filter?: FilterFn | false;
+  /**
+   * Transforms search input before filtering and visibility logic.
+   * @default trim whitespace (`search.trim()`)
+   */
+  normalizeSearch?: SearchNormalizer;
+  /**
+   * Controlled search value.
+   */
+  search?: string;
+  /**
+   * Callback when search value changes.
+   */
+  onSearchChange?: (search: string) => void;
+  /**
+   * Default search value for uncontrolled usage.
+   * @default ''
+   */
+  defaultSearch?: string;
+  /**
+   * Whether navigation should loop from last to first item and vice versa.
+   * @default true
+   */
+  loop?: boolean;
+  /**
+   * Controls auto-highlighting behavior when the menu opens.
+   * - `true`: highlight the first item (default)
+   * - `false`: don't auto-highlight any item
+   * - `string`: highlight the item with this specific value
+   * @default true
+   */
+  autoHighlightFirst?: boolean | string;
+  /**
+   * Whether to clear the search query when the menu closes.
+   * - `'after-exit'`: clear after exit animation completes (default)
+   * - `true`: clear immediately when menu closes
+   * - `false`: preserve search when menu closes
+   * @default 'after-exit'
+   */
+  clearSearchOnClose?: boolean | 'after-exit';
+  /**
+   * Whether to reset the list scroll position when the search query changes.
+   * @default true
+   */
+  resetScrollOnSearch?: boolean;
+  /**
+   * Whether to skip auto-focusing the input/list when this surface becomes the focus owner.
+   * Useful for Combobox where the input is outside the popup and should retain focus.
+   * @default false
+   */
+  skipAutoFocus?: boolean;
+  /**
+   * Ordered list of item values when using `filter={false}`.
+   * This tells the store the intended display order for navigation/highlighting.
+   * Required when `filter={false}` - must always be provided with the current visible items.
+   */
+  orderedItems?: string[];
+  children: React.ReactNode;
+}
+/**
+ * Provides search context and manages item registration for popup menu.
+ * Place inside PopupMenu.Popup to enable search functionality.
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuSurface: React.ForwardRefExoticComponent<Omit<PopupMenuSurface.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuSurface {
+  type State = PopupMenuSurfaceState;
+  interface Props extends PopupMenuSurfaceProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/checkbox-group/checkbox-group-value.d.ts
+interface PopupMenuCheckboxGroupValueProps {
+  /**
+   * The controlled array of checked item values.
+   */
+  value: string[];
+  /**
+   * Callback fired when the selected value changes.
+   * The second parameter contains event details including the reason for the change.
+   */
+  onValueChange?: (value: string[], eventDetails: CheckboxValueChangeEventDetails) => void;
+  /**
+   * Stable identifier for this group. Defaults to a generated id.
+   */
+  groupId?: string;
+  /**
+   * Whether all items in this group are disabled.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Children to render within the checkbox group context.
+   */
+  children: React.ReactNode;
+}
+/**
+ * Headless provider for checkbox group state.
+ * Use this when you compose checkbox items yourself and do not want a wrapper element.
+ * Does not render any DOM element - only provides context.
+ *
+ * @example
+ * ```tsx
+ * const [layout, setLayout] = useState(['minimap'])
+ *
+ * <DropdownMenu.CheckboxGroupValue value={layout} onValueChange={setLayout}>
+ *   <DropdownMenu.Surface content={content}>
+ *     ...
+ *   </DropdownMenu.Surface>
+ * </DropdownMenu.CheckboxGroupValue>
+ * ```
+ */
+declare function PopupMenuCheckboxGroupValue(props: PopupMenuCheckboxGroupValueProps): React.JSX.Element;
+declare namespace PopupMenuCheckboxGroupValue {
+  interface Props extends PopupMenuCheckboxGroupValueProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/checkbox-item/checkbox-item-indicator.d.ts
+interface PopupMenuCheckboxItemIndicatorState extends Record<string, unknown> {
+  /**
+   * Whether the parent checkbox item is currently checked.
+   */
+  checked: boolean;
+  /**
+   * Whether the parent checkbox item is currently highlighted.
+   */
+  highlighted: boolean;
+  /**
+   * Whether the parent checkbox item is disabled.
+   */
+  disabled: boolean;
+  /**
+   * Toggle the checked state without triggering closeOnClick.
+   * Useful when you want clicking directly on the indicator to toggle
+   * without closing the menu.
+   */
+  toggle: () => void;
+}
+interface PopupMenuCheckboxItemIndicatorProps extends ComponentProps<'span', PopupMenuCheckboxItemIndicator.State> {
+  /**
+   * Whether to keep the indicator mounted in the DOM when unchecked.
+   * Useful for animations.
+   * @default false
+   */
+  keepMounted?: boolean;
+}
+/**
+ * A visual indicator that shows when a CheckboxItem is checked.
+ * Must be used within a CheckboxItem component.
+ * Renders a `<span>` element with aria-hidden="true".
+ */
+declare const PopupMenuCheckboxItemIndicator: React.ForwardRefExoticComponent<Omit<PopupMenuCheckboxItemIndicator.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace PopupMenuCheckboxItemIndicator {
+  type State = PopupMenuCheckboxItemIndicatorState;
+  interface Props extends PopupMenuCheckboxItemIndicatorProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/radio-group/radio-group-value.d.ts
+interface PopupMenuRadioGroupValueProps {
+  /**
+   * The controlled selected value.
+   */
+  value: string | undefined;
+  /**
+   * Callback fired when the selected value changes.
+   * The second parameter contains event details including the reason for the change.
+   */
+  onValueChange?: (value: string, eventDetails: RadioValueChangeEventDetails) => void;
+  /**
+   * Whether all items in this group are disabled.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Children to render within the radio group context.
+   */
+  children: React.ReactNode;
+}
+/**
+ * Headless provider for radio group state.
+ * Use this to wrap DataSurface when using RadioItems in deep search.
+ * Does not render any DOM element - only provides context.
+ *
+ * @example
+ * ```tsx
+ * const [theme, setTheme] = useState('light')
+ *
+ * <DropdownMenu.RadioGroupValue value={theme} onValueChange={setTheme}>
+ *   <DropdownMenu.Surface content={content}>
+ *     ...
+ *   </DropdownMenu.Surface>
+ * </DropdownMenu.RadioGroupValue>
+ * ```
+ */
+declare function PopupMenuRadioGroupValue(props: PopupMenuRadioGroupValueProps): React.JSX.Element;
+declare namespace PopupMenuRadioGroupValue {
+  interface Props extends PopupMenuRadioGroupValueProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/radio-item/radio-item-indicator.d.ts
+interface PopupMenuRadioItemIndicatorState extends Record<string, unknown> {
+  /**
+   * Whether the parent radio item is currently selected/checked.
+   */
+  checked: boolean;
+  /**
+   * Whether the parent radio item is currently highlighted.
+   */
+  highlighted: boolean;
+  /**
+   * Whether the parent radio item is disabled.
+   */
+  disabled: boolean;
+}
+interface PopupMenuRadioItemIndicatorProps extends ComponentProps<'span', PopupMenuRadioItemIndicator.State> {
+  /**
+   * Whether to keep the indicator mounted in the DOM when unchecked.
+   * Useful for animations.
+   * @default false
+   */
+  keepMounted?: boolean;
+}
+/**
+ * A visual indicator that shows when a RadioItem is selected.
+ * Must be used within a RadioItem component.
+ * Renders a `<span>` element with aria-hidden="true".
+ */
+declare const PopupMenuRadioItemIndicator: React.ForwardRefExoticComponent<Omit<PopupMenuRadioItemIndicator.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace PopupMenuRadioItemIndicator {
+  type State = PopupMenuRadioItemIndicatorState;
+  interface Props extends PopupMenuRadioItemIndicatorProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/focus-zone/focus-zone.d.ts
+/**
+ * Declares its children as tabbable popup content: they join the surface's Tab
+ * cycle instead of Tab closing the menu. A zone with no tabbable children is
+ * treated as absent.
+ */
+interface PopupMenuFocusZoneState extends Record<string, unknown> {}
+interface PopupMenuFocusZoneProps extends ComponentProps<'div', PopupMenuFocusZone.State> {}
+declare const PopupMenuFocusZone: React.ForwardRefExoticComponent<Omit<PopupMenuFocusZone.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuFocusZone {
+  type State = PopupMenuFocusZoneState;
+  interface Props extends PopupMenuFocusZoneProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/footer/footer.d.ts
+/**
+ * Container for tabbable content at the bottom of a menu surface (action rows like Apply/Cancel). Registers as a focus zone: its tabbable children join the surface's Tab cycle.
+ */
+interface PopupMenuFooterState extends Record<string, unknown> {}
+interface PopupMenuFooterProps extends ComponentProps<'div', PopupMenuFooter.State> {}
+declare const PopupMenuFooter: React.ForwardRefExoticComponent<Omit<PopupMenuFooter.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuFooter {
+  type State = PopupMenuFooterState;
+  interface Props extends PopupMenuFooterProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/group/group.d.ts
+interface PopupMenuGroupState extends Record<string, unknown> {
+  /**
+   * Whether the group is hidden due to no matching items.
+   */
+  hidden: boolean;
+  /**
+   * Present when this is the first visible group in the list.
+   */
+  firstGroup: boolean;
+  /**
+   * Present when this is the last visible group in the list.
+   */
+  lastGroup: boolean;
+  first: boolean;
+  last: boolean;
+}
+interface PopupMenuGroupProps extends ComponentProps<'div', PopupMenuGroup.State> {
+  /**
+   * Whether to force render this group regardless of filter results.
+   * @default false
+   */
+  forceMount?: boolean;
+  children: React.ReactNode;
+}
+/**
+ * Groups related popup menu items together.
+ * Hidden when no child items match the current filter.
+ * Renders a `<div>` element with role="group".
+ */
+declare const PopupMenuGroup: React.ForwardRefExoticComponent<Omit<PopupMenuGroup.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuGroup {
+  type State = PopupMenuGroupState;
+  interface Props extends PopupMenuGroupProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/group/group-value.d.ts
+interface PopupMenuGroupValueProps {
+  /** Group id items register under. Omit for ungrouped rows that only need positional flags. */
+  groupId?: string;
+  /** Positional flags for this row; each defined flag overrides the store-derived value. */
+  positional?: GroupPositional;
+  children: React.ReactNode;
+}
+/**
+ * Headless provider for group membership and positional state.
+ * Renders no DOM. Use to wrap individual rows in virtualized lists where
+ * the store cannot derive position from mounted order.
+ */
+declare function PopupMenuGroupValue(props: PopupMenuGroupValueProps): React.JSX.Element;
+declare namespace PopupMenuGroupValue {
+  interface Props extends PopupMenuGroupValueProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/group-label/group-label.d.ts
+interface PopupMenuGroupLabelState extends Record<string, unknown> {
+  /**
+   * Present when this label is the first row in the list.
+   */
+  first: boolean;
+  /**
+   * Present when this label is the last row in the list.
+   */
+  last: boolean;
+  /**
+   * Present when this label's parent group is the first visible group in the list.
+   */
+  firstGroup: boolean;
+  /**
+   * Present when this label's parent group is the last visible group in the list.
+   */
+  lastGroup: boolean;
+}
+interface PopupMenuGroupLabelProps extends ComponentProps<'div', PopupMenuGroupLabel.State> {
+  children: React.ReactNode;
+}
+/**
+ * A label/heading for a group of popup menu items.
+ * Renders a `<div>` element with role="presentation".
+ */
+declare const PopupMenuGroupLabel: React.ForwardRefExoticComponent<Omit<PopupMenuGroupLabel.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuGroupLabel {
+  type State = PopupMenuGroupLabelState;
+  interface Props extends PopupMenuGroupLabelProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/header/header.d.ts
+/**
+ * Container for tabbable content at the top of a menu surface (toolbars, filters). Registers as a focus zone: its tabbable children join the surface's Tab cycle.
+ */
+interface PopupMenuHeaderState extends Record<string, unknown> {}
+interface PopupMenuHeaderProps extends ComponentProps<'div', PopupMenuHeader.State> {}
+declare const PopupMenuHeader: React.ForwardRefExoticComponent<Omit<PopupMenuHeader.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuHeader {
+  type State = PopupMenuHeaderState;
+  interface Props extends PopupMenuHeaderProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/separator/separator.d.ts
+interface PopupMenuSeparatorState extends Record<string, unknown> {
+  first: boolean;
+  last: boolean;
+}
+interface PopupMenuSeparatorProps extends ComponentProps<'div', PopupMenuSeparator.State> {
+  /**
+   * Whether to always render the separator, even during search.
+   * By default, separators are hidden when there's an active search query.
+   * @default false
+   */
+  alwaysRender?: boolean;
+}
+/**
+ * A visual separator between popup menu items.
+ * Hidden during active search unless `alwaysRender` is true.
+ * Renders a `<div>` element with role="separator".
+ */
+declare const PopupMenuSeparator: React.ForwardRefExoticComponent<Omit<PopupMenuSeparator.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuSeparator {
+  type State = PopupMenuSeparatorState;
+  interface Props extends PopupMenuSeparatorProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/shortcut/shortcut.d.ts
+/**
+ * State for the Shortcut component, passed to children render function.
+ */
+interface PopupMenuShortcutState extends Record<string, unknown> {
+  /**
+   * The keyboard shortcut value from the parent Item.
+   */
+  shortcut: string | undefined;
+  /**
+   * Whether the parent item is highlighted.
+   */
+  highlighted: boolean;
+}
+interface PopupMenuShortcutProps extends Omit<ComponentProps<'kbd', PopupMenuShortcut.State>, 'children'> {
+  /**
+   * Content to render inside the shortcut.
+   * Can be a render function that receives the shortcut value.
+   * If not provided, renders the shortcut value from the parent Item.
+   */
+  children?: React.ReactNode | ((state: PopupMenuShortcutState) => React.ReactNode);
+}
+/**
+ * Displays the keyboard shortcut for a menu item.
+ * Must be used within a PopupMenu.Item component.
+ * Renders a `<kbd>` element by default.
+ *
+ * @example
+ * ```tsx
+ * // Auto-renders the shortcut value
+ * <PopupMenu.Item shortcut="1">
+ *   Icebox
+ *   <PopupMenu.Shortcut />
+ * </PopupMenu.Item>
+ *
+ * // Custom rendering with children as function
+ * <PopupMenu.Item shortcut="1">
+ *   Icebox
+ *   <PopupMenu.Shortcut>
+ *     {({ shortcut }) => <span className="key">{shortcut}</span>}
+ *   </PopupMenu.Shortcut>
+ * </PopupMenu.Item>
+ * ```
+ */
+declare const PopupMenuShortcut: React.ForwardRefExoticComponent<Omit<PopupMenuShortcut.Props, "ref"> & React.RefAttributes<HTMLElement>>;
+declare namespace PopupMenuShortcut {
+  type State = PopupMenuShortcutState;
+  interface Props extends PopupMenuShortcutProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/tree/tree.d.ts
+interface PopupMenuTreeState extends Record<string, unknown> {
+  depth: number;
+}
+interface PopupMenuTreeProps extends ComponentProps<'div', PopupMenuTree.State> {
+  children: React.ReactNode;
+}
+declare const PopupMenuTree: React.ForwardRefExoticComponent<Omit<PopupMenuTree.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuTree {
+  type State = PopupMenuTreeState;
+  interface Props extends PopupMenuTreeProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/tree/tree-connector.d.ts
+interface PopupMenuTreeConnectorState extends Record<string, unknown> {
+  depth: number;
+}
+interface PopupMenuTreeConnectorProps extends ComponentProps<'span', PopupMenuTreeConnector.State> {
+  depth?: number;
+}
+declare const PopupMenuTreeConnector: React.ForwardRefExoticComponent<Omit<PopupMenuTreeConnector.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace PopupMenuTreeConnector {
+  type State = PopupMenuTreeConnectorState;
+  interface Props extends PopupMenuTreeConnectorProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/tree/tree-item.d.ts
+interface PopupMenuTreeItemProps extends Omit<PopupMenuItemProps, 'activatable'> {
+  /** Whether this tree item can be activated. @default true */
+  selectable?: boolean;
+  /** Explicit tree depth override. */
+  depth?: number;
+}
+declare const PopupMenuTreeItem: React.ForwardRefExoticComponent<Omit<PopupMenuTreeItem.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuTreeItem {
+  type State = PopupMenuItemState;
+  interface Props extends PopupMenuTreeItemProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/submenu-root/submenu-root.d.ts
+interface PopupMenuSubmenuRootProps extends Omit<PopoverRootProps, 'open' | 'onOpenChange' | 'defaultOpen' | 'actionsRef'> {
+  /**
+   * Whether the submenu is open.
+   * Use for controlled mode.
+   */
+  open?: boolean;
+  /**
+   * Callback when the open state changes.
+   * The second parameter contains event details including the reason for the change.
+   */
+  onOpenChange?: (open: boolean, eventDetails: Popover.Root.ChangeEventDetails) => void;
+  /**
+   * Whether the submenu is initially open.
+   * Use for uncontrolled mode.
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Whether pressing Escape in this submenu closes the entire menu from the root.
+   * When true (default), Escape closes the entire menu tree.
+   * When false, Escape only closes this submenu and moves focus to the parent.
+   * @default true
+   */
+  closeRootOnEsc?: boolean;
+  /**
+   * Whether virtualization mode is enabled for this submenu.
+   * When true, items should provide an explicit `index` prop and
+   * the `items` prop should be provided for navigation to work correctly.
+   * @default false
+   */
+  virtualized?: boolean;
+  /**
+   * Pre-registered items for virtualization.
+   * When provided with `virtualized={true}`, this allows navigation to work
+   * for items that aren't currently mounted in the DOM.
+   */
+  items?: VirtualItem[];
+  /**
+   * Callback when the highlighted item changes. `id` is first; `node` is the
+   * resolved menu node enrichment and may be null.
+   * Useful for synchronizing with a virtualizer (e.g., scrollToIndex).
+   */
+  onHighlightChange?: PopupMenuHighlightChangeHandler<HighlightChangeEventDetails>;
+  /**
+   * Event handler called after any open/close animations have completed.
+   * When `clearSearchOnClose="after-exit"` is set on Surface, the search
+   * will be cleared before this callback is invoked.
+   */
+  onOpenChangeComplete?: (open: boolean) => void;
+  /**
+   * Whether this submenu should ignore user interaction.
+   * Also inherits disabled state from its parent menu.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * A ref to imperative actions.
+   * - `close`: closes the submenu imperatively.
+   * - `unmount`: unmounts the popup imperatively (when keep-mounted mode is enabled).
+   * - `setDisabled`: enables/disables the submenu imperatively.
+   */
+  actionsRef?: React.RefObject<PopupMenuSubmenuRoot.Actions | null>;
+  children: React.ReactNode;
+}
+/**
+ * Groups all parts of a submenu.
+ * Manages open state and provides context to children.
+ * Creates its own ListboxStore independent from the parent menu.
+ * Doesn't render its own HTML element.
+ */
+declare function PopupMenuSubmenuRoot(props: PopupMenuSubmenuRootProps): React.JSX.Element;
+declare namespace PopupMenuSubmenuRoot {
+  interface Props extends PopupMenuSubmenuRootProps {}
+  type ChangeEventDetails = Popover.Root.ChangeEventDetails;
+  type Actions = PopupMenuRootActions;
+}
+//#endregion
+//#region src/internal/popup-menu/components/submenu-trigger/submenu-trigger-indicator.d.ts
+interface PopupMenuSubmenuTriggerIndicatorState extends Record<string, unknown> {
+  /**
+   * Whether the submenu popup is open.
+   */
+  popupOpen: boolean;
+  /**
+   * Whether the submenu owns keyboard focus.
+   */
+  popupFocused: boolean;
+}
+interface PopupMenuSubmenuTriggerIndicatorProps extends ComponentProps<'span', PopupMenuSubmenuTriggerIndicator.State> {}
+/**
+ * An indicator element for submenu triggers that reflects the submenu's open and focus state.
+ * Typically used to render a chevron or arrow icon.
+ * Must be used within PopupMenu.SubmenuTrigger.
+ * Renders a `<span>` element.
+ */
+declare const PopupMenuSubmenuTriggerIndicator: React.ForwardRefExoticComponent<Omit<PopupMenuSubmenuTriggerIndicator.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace PopupMenuSubmenuTriggerIndicator {
+  type State = PopupMenuSubmenuTriggerIndicatorState;
+  interface Props extends PopupMenuSubmenuTriggerIndicatorProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/subpage/subpage.d.ts
+interface PopupMenuSubpageProps {
+  /** Unique page ID for stack navigation. */
+  pageId: string;
+  /**
+   * Whether pressing Escape in this page closes the entire menu tree.
+   * When false (default), Escape navigates back one page.
+   * @default false
+   */
+  closeRootOnEsc?: boolean;
+  children: React.ReactNode;
+}
+/**
+ * Groups all parts of a subpage.
+ * Creates an isolated menu surface that renders in the same popup and
+ * participates in push/pop page stack navigation.
+ * Doesn't render its own HTML element.
+ */
+declare function PopupMenuSubpage(props: PopupMenuSubpageProps): React.JSX.Element;
+declare namespace PopupMenuSubpage {
+  interface Props extends PopupMenuSubpageProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/subpage-back/subpage-back.d.ts
+interface PopupMenuSubpageBackState extends Record<string, unknown> {
+  /** Whether navigating back is currently possible. */
+  canGoBack: boolean;
+  /** Whether the button is disabled. */
+  disabled: boolean;
+}
+interface PopupMenuSubpageBackProps extends ComponentProps<'button', PopupMenuSubpageBack.State> {
+  /** Whether this button is disabled. */
+  disabled?: boolean;
+}
+/**
+ * A button that navigates back one page in the current subpage stack.
+ * Useful for custom headers/toolbars outside of list rows.
+ * Renders a `<button>` element.
+ */
+declare const PopupMenuSubpageBack: React.ForwardRefExoticComponent<Omit<PopupMenuSubpageBack.Props, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+declare namespace PopupMenuSubpageBack {
+  type State = PopupMenuSubpageBackState;
+  interface Props extends PopupMenuSubpageBackProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/subpage-back-item/subpage-back-item.d.ts
+interface PopupMenuSubpageBackItemState extends Record<string, unknown> {
+  /** Whether this is a subpage back item (always true). */
+  subpageBackItem: boolean;
+  /** Whether the item is highlighted. */
+  highlighted: boolean;
+  /** Whether the item is disabled. */
+  disabled: boolean;
+  first: boolean;
+  last: boolean;
+  firstInGroup: boolean;
+  lastInGroup: boolean;
+}
+interface PopupMenuSubpageBackItemProps extends ComponentProps<'div', PopupMenuSubpageBackItem.State> {
+  /** Explicit unique identifier for this item in the store. */
+  id?: string;
+  /** Unique value for this item used for filtering. */
+  value?: string;
+  /** Additional keywords to match against when filtering. */
+  keywords?: string[];
+  /** Whether this item is disabled. */
+  disabled?: boolean;
+  /** Whether to force render this item regardless of filter results. */
+  forceMount?: boolean;
+  /** Callback when this item is selected. */
+  onSelect?: () => void;
+  /**
+   * Async callback when this item is selected.
+   *
+   * When provided, this takes precedence over `onSelect`.
+   * If provided, this callback is awaited before navigating back.
+   * Return `false` to prevent automatic navigation.
+   */
+  onSelectAsync?: (context: PopupMenuSubpageBackItem.OnSelectAsyncContext) => Promise<void | boolean>;
+}
+/**
+ * A list row that navigates back one page in the current subpage stack.
+ * Renders a `<div>` element with role="option".
+ */
+declare const PopupMenuSubpageBackItem: React.ForwardRefExoticComponent<Omit<PopupMenuSubpageBackItem.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuSubpageBackItem {
+  type State = PopupMenuSubpageBackItemState;
+  interface OnSelectAsyncContext {
+    /** Navigate back one page manually. */
+    goBack: () => boolean;
+    /** Aborts when a pending async selection is canceled or unmounted. */
+    signal: AbortSignal;
+  }
+  interface Props extends PopupMenuSubpageBackItemProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/data-first/async-coordinator.d.ts
+/**
+ * State for a registered async loader.
+ */
+interface AsyncMenuState {
+  /** Unique identifier for this async menu */
+  id: string;
+  /** The loader configuration */
+  config: AsyncLoaderConfig;
+  /** Current loader result */
+  result: AsyncLoaderResult<NodeDef[]>;
+}
+interface RootAsyncMenuState {
+  config: AsyncLoaderConfig;
+  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;
+  registerRootLoader: (state: RootAsyncMenuState) => void;
+  unregisterRootLoader: () => void;
+  updateRootLoaderResult: (result: AsyncLoaderResult<NodeDef[]>) => void;
+  /** Current search query from the store */
+  searchQuery: string;
+  /** All registered loaders */
+  loaders: Map<string, AsyncMenuState>;
+  /** The root surface's own `asyncContent` loader; `null` when none is registered. Never present in `loaders`. */
+  root: RootAsyncMenuState | null;
+  /** Any loader is currently in initial loading phase */
+  isAnyLoading: boolean;
+  /** Any loader is currently fetching (initial or background) */
+  isAnyFetching: boolean;
+  /** Any loader is currently in first-load phase */
+  isAnyInitialLoading: boolean;
+  /** Any loader is currently in background refetch phase */
+  isAnyRefetching: boolean;
+  /** All registered loaders are currently in background refetch phase */
+  isAllRefetching: boolean;
+  /** The root loader is currently in initial loading phase */
+  isRootLoading: boolean;
+  /** Static loaders are currently in initial loading phase */
+  isStaticLoading: boolean;
+  /** Static loaders are currently fetching */
+  isStaticFetching: boolean;
+  /** Static loaders in first-load phase */
+  isStaticInitialLoading: boolean;
+  /** Static loaders in background refetch phase */
+  isStaticRefetching: boolean;
+  /** Query loaders are currently in initial loading phase */
+  isQueryLoading: boolean;
+  /** Query loaders are currently fetching */
+  isQueryFetching: boolean;
+  /** Query loaders in first-load phase */
+  isQueryInitialLoading: boolean;
+  /** Query loaders in background refetch phase */
+  isQueryRefetching: boolean;
+  /** All loaders have resolved (not fetching) */
+  allResolved: boolean;
+  /** Every loader with a usable result: the root entry (if any) and one branch entry per Resolved ID. */
+  getAsyncNodes: () => Array<{
+    kind: 'root';
+    nodes: NodeDef[];
+  } | {
+    kind: 'branch';
+    id: string;
+    nodes: NodeDef[];
+  }>;
+  /** Loaders that errored */
+  erroredLoaders: Map<string, Error>;
+  rootError: Error | null;
+  /** Get the aggregate async state for DataList */
+  getAsyncState: () => AsyncState;
+  /**
+   * Whether the root surface's `asyncContent` has settled for the current
+   * search, published by the root data list. `Empty` waits for it; in
+   * `asyncContentReveal: 'block'` mode `Loading` hides once it has settled.
+   */
+  rootReveal: RootRevealState;
+  setRootReveal: (state: RootRevealState) => void;
+}
+interface RootRevealState {
+  /** No root loader is pending for the current search. */
+  settled: boolean;
+  /** The root loader has settled at least once since mounting. */
+  settledOnce: boolean;
+  /** The surface uses `asyncContentReveal: 'block'`. */
+  block: boolean;
+}
+declare function useAsyncMenuCoordinator(): AsyncMenuCoordinatorValue | null;
+declare function useMaybeAsyncMenuCoordinator(): AsyncMenuCoordinatorValue | null;
+//#endregion
+//#region src/internal/popup-menu/data-first/context.d.ts
+interface DataSurfaceContextValue {
+  /** The original node definitions */
+  content: NodeDef[];
+  /** Async content configuration for root-level async loading */
+  asyncContent?: AsyncLoaderConfig;
+  /** How `asyncContent` rows combine with `content` */
+  asyncContentMode: AsyncContentMode;
+  /** When `asyncContent` rows appear */
+  asyncContentReveal: AsyncResultBehavior;
+  /** Deep search configuration */
+  deepSearchConfig: DeepSearchConfig;
+  /** Default submenu inclusion mode for deep search */
+  includeInDeepSearch: IncludeInDeepSearch;
+  /** List element ID for aria-activedescendant */
+  listId: string;
+}
+declare const DataSurfaceContext: React.Context<DataSurfaceContextValue | null>;
+interface ResolvedNodesSlot {
+  nodes: readonly PopupMenuNode[];
+  graftVersion: number;
+  /** The `content` prop the slot was published for; consumers drop a slot whose content the root surface no longer supplies. */
+  content: NodeDef[];
+}
+interface DataPopupContextValue {
+  /** Latest DataSurface context registered within this popup. */
+  dataSurfaceContext: DataSurfaceContextValue | null;
+  /** Registers/clears DataSurface context for sibling consumers. */
+  setDataSurfaceContext: React.Dispatch<React.SetStateAction<DataSurfaceContextValue | null>>;
+  /**
+   * The resolved-nodes slot: the root list's current Menu Nodes plus the
+   * graft version that changes when loader results are grafted under a
+   * branch (which mutates `children` without changing the outer array).
+   * Null until the root list registers. Retained while a subpage is active
+   * and the root list is unmounted; the Menu Tree persists on the resolver.
+   */
+  resolvedNodes: ResolvedNodesSlot | null;
+  setResolvedNodes: React.Dispatch<React.SetStateAction<ResolvedNodesSlot | null>>;
+}
+declare const DataPopupContext: React.Context<DataPopupContextValue | null>;
+declare function useDataSurfaceContext(): DataSurfaceContextValue;
+declare function useMaybeDataSurfaceContext(): DataSurfaceContextValue | null;
+declare const DataListContext: React.Context<DataListChildrenState | null>;
+declare function useDataList(): DataListChildrenState;
+declare function useMaybeDataList(): DataListChildrenState | null;
+type RenderNodeFn = (displayNode: DisplayNode) => React.ReactNode;
+//#endregion
+//#region src/internal/popup-menu/data-first/type-guards.d.ts
+declare function isLinkItemDef(node: NodeDef): node is LinkItemDef;
+declare function isTreeItemDef(node: NodeDef): node is TreeItemDef;
+//#endregion
+//#region src/internal/popup-menu/menu-tree/resolve.d.ts
+declare function isPopupMenuNode(value: unknown): value is PopupMenuNode;
+/** Default Resolved ID, using surface-scoped encoded paths unless menu scope is selected. */
+declare function defaultGetResolvedId(node: UnresolvedMenuNode, idScope?: PopupMenuIdScope): string;
+//#endregion
+export { PopupMenuFocusZoneProps as $, PopupMenuPopupProps as $t, PopupMenuTreeItem as A, useFocusOwner as An, PopupMenuInputState as At, PopupMenuHeaderProps as B, ForwardKeyDown as Bt, PopupMenuSubpage as C, PopupMenuContext as Cn, PopupMenuList as Ct, PopupMenuSubmenuTriggerIndicatorState as D, useMaybePopupMenuContext as Dn, PopupMenuListCssVars as Dt, PopupMenuSubmenuTriggerIndicatorProps as E, VirtualizationConfig as En, PopupMenuListState as Et, PopupMenuShortcutState as F, PopupMenuIconProps as Ft, PopupMenuGroupValue as G, PopupMenuProviders as Gt, PopupMenuGroupLabel as H, UseForwardedKeyDownParams as Ht, PopupMenuSeparator as I, PopupMenuIconState as It, PopupMenuGroupState as J, PopupMenuPositionerProps as Jt, PopupMenuGroup as K, PopupMenuPositioner as Kt, PopupMenuSeparatorProps as L, UsePopupMenuItemParams as Lt, PopupMenuTree as M, PopupMenuEmptyProps as Mt, PopupMenuShortcut as N, PopupMenuEmptyState as Nt, PopupMenuSubmenuRoot as O, usePopupMenuContext as On, PopupMenuInput as Ot, PopupMenuShortcutProps as P, PopupMenuIcon as Pt, PopupMenuFocusZone as Q, PopupMenuPopup as Qt, PopupMenuSeparatorState as R, UsePopupMenuItemReturn as Rt, PopupMenuSubpageBackState as S, PopupMenuDebugOptions as Sn, PopupMenuLoadingState as St, PopupMenuSubmenuTriggerIndicator as T, VirtualAnchor as Tn, PopupMenuListProps as Tt, PopupMenuGroupLabelProps as U, useForwardedKeyDown as Ut, PopupMenuHeaderState as V, ForwardedKeyboardEvent as Vt, PopupMenuGroupLabelState as W, usePopupMenuKeyboard as Wt, PopupMenuFooterProps as X, PopupMenuPortal as Xt, PopupMenuFooter as Y, PopupMenuPositionerCssVars as Yt, PopupMenuFooterState as Z, PopupMenuPortalProps as Zt, PopupMenuSubpageBackItem as _, useSubpageContext as _n, PopupMenuScrollDownArrowProps as _t, DataListContext as a, PopupMenuArrowProps as an, PopupMenuRadioGroupValueProps as at, PopupMenuSubpageBack as b, useSubmenuContext as bn, PopupMenuLoading as bt, DataSurfaceContextValue as c, UsePopupMenuRootParams as cn, PopupMenuCheckboxItemIndicatorState as ct, useDataSurfaceContext as d, SubpageStackContext as dn, PopupMenuSurface as dt, PopupMenuPopupState as en, PopupMenuFocusZoneState as et, useMaybeDataList as f, SubpageStackContextValue as fn, PopupMenuSurfaceProps as ft, useMaybeAsyncMenuCoordinator as g, useMaybeSubpageContext as gn, PopupMenuScrollDownArrow as gt, useAsyncMenuCoordinator as h, SubpageContextValue as hn, PopupMenuScrollArrowState as ht, isTreeItemDef as i, PopupMenuArrow as in, PopupMenuRadioGroupValue as it, PopupMenuTreeConnector as j, FocusOwnerStore as jn, PopupMenuEmpty as jt, PopupMenuSubmenuRootProps as k, useOpenChain as kn, PopupMenuInputProps as kt, RenderNodeFn as l, usePopupMenuRoot as ln, PopupMenuCheckboxGroupValue as lt, AsyncMenuCoordinatorValue as m, useSubpageStack as mn, PopupMenuScrollArrowProps as mt, isPopupMenuNode as n, PopupMenuBackdrop as nn, PopupMenuRadioItemIndicatorProps as nt, DataPopupContext as o, useSubpageStackState as on, PopupMenuCheckboxItemIndicator as ot, useMaybeDataSurfaceContext as p, useMaybeSubpageStack as pn, PopupMenuSurfaceState as pt, PopupMenuGroupProps as q, PopupMenuPositionerAlign as qt, isLinkItemDef as r, PopupMenuBackdropProps as rn, PopupMenuRadioItemIndicatorState as rt, DataSurfaceContext as s, PopupMenuRootActions as sn, PopupMenuCheckboxItemIndicatorProps as st, defaultGetResolvedId as t, PopupMenuPopupDataAttributes as tn, PopupMenuRadioItemIndicator as tt, useDataList as u, MenuTreeResolver as un, PopupMenuCheckboxGroupValueProps as ut, PopupMenuSubpageBackItemProps as v, SubmenuContextValue as vn, PopupMenuScrollUpArrow as vt, PopupMenuSubpageProps as w, PopupMenuContextValue as wn, PopupMenuListChildrenState as wt, PopupMenuSubpageBackProps as x, PopupSurfaceIdContext as xn, PopupMenuLoadingProps as xt, PopupMenuSubpageBackItemState as y, useMaybeSubmenuContext as yn, PopupMenuScrollUpArrowProps as yt, PopupMenuHeader as z, usePopupMenuItem as zt };
+//# sourceMappingURL=index-Cabqj7qI.d.ts.map