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

package/dist/separator-BmbUeeaT.d.cts

@@ -0,0 +1,748 @@
+import * as React from 'react';
+import { P as PopupMenuOpenChangeReason, H as HighlightChangeEventDetails, C as ChangeEventDetails, G as GenericEventDetails } from './events-BPr8sRGH.cjs';
+import { b as ListboxStore, V as VirtualItem, F as FilterFn, S as SearchNormalizer } from './ListboxStore-BtcTXpzi.cjs';
+import { G as GetQualifiedRowIdFn, av as ComponentRenderFn, C as ComponentProps } from './types-9vS1uLIK.cjs';
+import { ReactStore } from '@base-ui/utils/store';
+import { PopoverArrowProps, Popover, PopoverBackdropProps, PopoverPopupProps, PopoverPortalProps } from '@base-ui/react/popover';
+
+interface FocusOwnerState {
+    /** Which surface currently owns focus (surfaceId or null) */
+    ownerId: string | null;
+}
+declare const selectors$1: {
+    ownerId: (state: FocusOwnerState) => string | null;
+    isOwner: (state: FocusOwnerState, surfaceId: string) => boolean;
+};
+/**
+ * Tracks which menu surface owns DOM focus.
+ * Single instance per menu tree (created at root, shared via context).
+ *
+ * Used by: DropdownMenu, ContextMenu
+ * Not used by: Select, CommandMenu (single surface)
+ */
+declare class FocusOwnerStore extends ReactStore<FocusOwnerState, {}, typeof selectors$1> {
+    constructor();
+    /**
+     * Set the owner surface ID.
+     * Call this when focus should transfer to a new surface.
+     */
+    setOwnerId(id: string | null): void;
+    /**
+     * Clear the owner (set to null).
+     * Call this when the menu tree closes.
+     */
+    clearOwner(): void;
+}
+
+interface OpenChainState {
+    /**
+     * Ordered array of surface IDs for submenus that are currently open.
+     * The last element is the most recently opened (deepest in chain).
+     */
+    chain: string[];
+}
+declare const selectors: {
+    isOpen: (state: OpenChainState, surfaceId: string) => boolean;
+    isLast: (state: OpenChainState, surfaceId: string) => boolean;
+    /**
+     * Returns true if there's an open submenu below the given depth.
+     * - Root (depth 0): true if any submenu is open
+     * - Submenu at depth N: true if a deeper submenu is open
+     */
+    hasOpenSubmenu: (state: OpenChainState, depth: number) => boolean;
+};
+/**
+ * Tracks which submenu surfaces are currently open in order.
+ * Used to show backdrops for all open menus in the chain.
+ * Single instance per menu tree (created at root, shared via context).
+ *
+ * Used by: DropdownMenu, ContextMenu
+ * Not used by: Select, CommandMenu (no submenus)
+ */
+declare class OpenChainStore extends ReactStore<OpenChainState, {}, typeof selectors> {
+    constructor();
+    /**
+     * Mark a surface as open (adds to end of chain).
+     */
+    open(surfaceId: string): void;
+    /**
+     * Mark a surface as closed (removes from chain).
+     */
+    close(surfaceId: string): void;
+    /**
+     * Clear all open surfaces (menu tree closed).
+     */
+    clear(): void;
+}
+
+/**
+ * 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;
+    /** 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';
+    /**
+     * Function to generate qualified unique IDs for rows.
+     * Defined once at the root level and applied to all surfaces (root and submenus).
+     * If not provided, uses the default implementation.
+     */
+    getQualifiedRowId?: GetQualifiedRowIdFn;
+}
+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;
+
+interface PopupMenuSafeTriangleAreaDebugSettings {
+    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;
+}
+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;
+declare function resolvePopupMenuSafeTriangleAreaDebugConfig(config?: PopupMenuSafeTriangleAreaDebugConfig, legacyEnabled?: boolean): PopupMenuSafeTriangleAreaDebugSettings;
+/**
+ * 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;
+}
+interface PopupMenuDebugContextValue {
+    showSafeTriangleArea: PopupMenuSafeTriangleAreaDebugSettings;
+    logAimGuardEvents: boolean;
+}
+declare const PopupMenuDebugContext: React.Context<PopupMenuDebugContextValue>;
+declare function usePopupMenuDebug(): PopupMenuDebugContextValue;
+
+interface UsePopupMenuRootParams {
+    /**
+     * Callback when the open state changes.
+     * The second parameter contains event details including the reason for the change.
+     */
+    onOpenChange?: (open: boolean, eventDetails: ChangeEventDetails<string>) => void;
+    /**
+     * Whether the menu is initially open.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Whether virtualization mode is enabled.
+     * @default false
+     */
+    virtualized?: boolean;
+    /**
+     * Pre-registered items for virtualization.
+     */
+    items?: VirtualItem[];
+    /**
+     * Callback when the highlighted item changes.
+     * The third parameter contains event details including the reason for the change.
+     */
+    onHighlightChange?: (id: string | null, index: number, eventDetails: GenericEventDetails<string, {
+        index: number;
+    }>) => void;
+    /**
+     * When to close the menu on outside interactions.
+     * - 'pointerdown': Close immediately when pointer is pressed outside (default)
+     * - 'click': Close when a full click (pointerdown + pointerup) occurs outside
+     * @default 'pointerdown'
+     */
+    closeOnOutsidePress?: 'click' | 'pointerdown';
+    /**
+     * 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 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;
+
+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<PopupMenuArrowProps & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuArrow {
+    type Props = PopupMenuArrowProps;
+    type State = Popover.Arrow.State;
+}
+
+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<PopupMenuBackdropProps & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuBackdrop {
+    type Props = PopupMenuBackdropProps;
+    type State = Popover.Backdrop.State;
+}
+
+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 only the root page is open.
+     */
+    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<PopupMenuPopupProps & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuPopup {
+    type Props = PopupMenuPopupProps;
+    type State = PopupMenuPopupState;
+}
+
+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: React.ForwardRefExoticComponent<PopoverPortalProps & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuPortal {
+    type Props = PopoverPortalProps;
+    type State = Popover.Portal.State;
+}
+
+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"
+}
+
+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 {
+    }
+}
+
+interface PopupMenuEmptyState extends Record<string, unknown> {
+}
+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 {
+    }
+}
+
+/**
+ * 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"
+}
+
+/**
+ * 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 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;
+}
+/**
+ * Container for popup menu items.
+ * Supports render props for accessing search state.
+ * Renders a `<div>` element with role="listbox".
+ */
+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 {
+    }
+}
+
+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 {
+    }
+}
+
+interface PopupMenuSurfaceState extends Record<string, unknown> {
+}
+interface PopupMenuSurfaceProps extends ComponentProps<'div', PopupMenuSurface.State> {
+    /**
+     * 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.
+     * - `true`: clear immediately when menu closes (default)
+     * - `false`: preserve search when menu closes
+     * - `'after-exit'`: clear after exit animation completes
+     * @default true
+     */
+    clearSearchOnClose?: boolean | 'after-exit';
+    /**
+     * 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 {
+    }
+}
+
+interface PopupMenuGroupState extends Record<string, unknown> {
+    /**
+     * Whether the group is hidden due to no matching items.
+     */
+    hidden: 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 {
+    }
+}
+
+interface PopupMenuGroupLabelState extends Record<string, unknown> {
+}
+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 {
+    }
+}
+
+interface PopupMenuSeparatorState extends Record<string, unknown> {
+}
+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 {
+    }
+}
+
+export { PopupMenuDebugContext as $, type PopupMenuListState as A, type PopupMenuPopupProps as B, type PopupMenuPortalProps as C, type PopupMenuScrollArrowProps as D, type PopupMenuScrollArrowState as E, type PopupMenuScrollDownArrowProps as F, type PopupMenuScrollUpArrowProps as G, type PopupMenuSeparatorProps as H, type PopupMenuSeparatorState as I, type PopupMenuSurfaceProps as J, type PopupMenuSurfaceState as K, PopupMenuListCssVars as L, PopupMenuPositionerCssVars as M, type PopupMenuContextValue as N, useMaybePopupMenuContext as O, type PopupMenuDebugOptions as P, usePopupMenuContext as Q, type PopupMenuPopupState as R, FocusOwnerStore as S, OpenChainStore as T, type VirtualAnchor as U, type VirtualizationConfig as V, PopupMenuContext as W, type PopupMenuDebugContextValue as X, type PopupMenuSafeTriangleAreaDebugConfig as Y, type PopupMenuSafeTriangleAreaDebugOptions as Z, type PopupMenuSafeTriangleAreaDebugSettings as _, type PopupMenuRootActions as a, resolvePopupMenuSafeTriangleAreaDebugConfig as a0, usePopupMenuDebug as a1, type FocusOwnerState as a2, type OpenChainState as a3, type UsePopupMenuRootParams as a4, type UsePopupMenuRootReturn as a5, usePopupMenuRoot as a6, PopupMenuScrollArrow as a7, PopupMenuArrow as b, PopupMenuBackdrop as c, PopupMenuEmpty as d, PopupMenuGroup as e, PopupMenuGroupLabel as f, PopupMenuIcon as g, PopupMenuList as h, PopupMenuPopup as i, PopupMenuPortal as j, PopupMenuScrollDownArrow as k, PopupMenuScrollUpArrow as l, PopupMenuSeparator as m, PopupMenuSurface as n, type PopupMenuArrowProps as o, type PopupMenuBackdropProps as p, type PopupMenuEmptyProps as q, type PopupMenuEmptyState as r, type PopupMenuGroupLabelProps as s, type PopupMenuGroupLabelState as t, type PopupMenuGroupProps as u, type PopupMenuGroupState as v, type PopupMenuIconProps as w, type PopupMenuIconState as x, type PopupMenuListChildrenState as y, type PopupMenuListProps as z };