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

package/dist/events-DPsuhBln.d.cts

@@ -0,0 +1,1776 @@
+import * as React from 'react';
+import { C as ComponentProps } from './types-DT4FOOa2.cjs';
+
+declare const triggerPress: "trigger-press";
+declare const triggerHover: "trigger-hover";
+declare const triggerFocus: "trigger-focus";
+declare const triggerContextMenu: "trigger-context-menu";
+declare const escapeKey: "escape-key";
+declare const outsidePress: "outside-press";
+declare const focusOut: "focus-out";
+declare const itemPress: "item-press";
+declare const itemKeyboardSelect: "item-keyboard-select";
+declare const closePress: "close-press";
+declare const inputChange: "input-change";
+declare const inputClear: "input-clear";
+declare const clearPress: "clear-press";
+declare const listNavigation: "list-navigation";
+declare const submenuTrigger: "submenu-trigger";
+declare const siblingOpen: "sibling-open";
+declare const pointer: "pointer";
+declare const keyboard: "keyboard";
+declare const auto: "auto";
+declare const imperativeAction: "imperative-action";
+declare const none: "none";
+
+/**
+ * Maps event reason strings to their corresponding native DOM event types.
+ * This provides type-safe access to the native event based on the reason.
+ */
+interface ReasonToEventMap {
+    [none]: Event;
+    [triggerPress]: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent;
+    [triggerHover]: MouseEvent | PointerEvent;
+    [triggerFocus]: FocusEvent;
+    [triggerContextMenu]: MouseEvent;
+    [escapeKey]: KeyboardEvent;
+    [outsidePress]: MouseEvent | PointerEvent | TouchEvent;
+    [focusOut]: FocusEvent | KeyboardEvent;
+    [itemPress]: MouseEvent | PointerEvent | KeyboardEvent;
+    [itemKeyboardSelect]: KeyboardEvent;
+    [closePress]: MouseEvent | PointerEvent | KeyboardEvent;
+    [inputChange]: InputEvent | Event;
+    [inputClear]: InputEvent | FocusEvent | Event;
+    [clearPress]: MouseEvent | PointerEvent | KeyboardEvent;
+    [listNavigation]: KeyboardEvent;
+    [submenuTrigger]: MouseEvent | PointerEvent | KeyboardEvent;
+    [siblingOpen]: Event;
+    [pointer]: MouseEvent | PointerEvent;
+    [keyboard]: KeyboardEvent;
+    [imperativeAction]: Event;
+}
+/**
+ * Maps a reason string to the corresponding native event type.
+ * Falls back to `Event` for unknown reasons.
+ */
+type ReasonToEvent<Reason extends string> = Reason extends keyof ReasonToEventMap ? ReasonToEventMap[Reason] : Event;
+/**
+ * Details object passed to change event handlers (onOpenChange, onValueChange, etc.)
+ *
+ * @template Reason - The union of allowed reason strings for this event
+ * @template CustomProperties - Additional component-specific properties
+ */
+interface ChangeEventDetails<Reason extends string, _CustomProperties extends object = Record<string, never>> {
+    /**
+     * The reason why this state change occurred.
+     * Use this to conditionally handle different scenarios.
+     *
+     * @example
+     * ```tsx
+     * onOpenChange={(open, details) => {
+     *   if (details.reason === 'escape-key') {
+     *     // Handle escape key differently
+     *   }
+     * }}
+     * ```
+     */
+    reason: Reason;
+    /**
+     * The native DOM event that triggered this change.
+     * May be a synthetic event in some cases.
+     */
+    event: ReasonToEvent<Reason>;
+    /**
+     * Cancels the state change.
+     * When called, the component's internal state will not update.
+     *
+     * @example
+     * ```tsx
+     * onOpenChange={(open, details) => {
+     *   if (!open && details.reason === 'outside-press') {
+     *     details.cancel() // Prevent closing on outside press
+     *   }
+     * }}
+     * ```
+     */
+    cancel: () => void;
+    /**
+     * Allows the native event to propagate.
+     * By default, some events (like Escape key) stop propagation
+     * to prevent parent popups from closing simultaneously.
+     */
+    allowPropagation: () => void;
+    /**
+     * Whether `cancel()` has been called.
+     */
+    readonly isCanceled: boolean;
+    /**
+     * Whether `allowPropagation()` has been called.
+     */
+    readonly isPropagationAllowed: boolean;
+    /**
+     * The element that triggered this event, if applicable.
+     */
+    trigger: Element | undefined;
+}
+/**
+ * Details object for generic events that don't support cancellation.
+ * Used for events like onHighlightChange where cancellation doesn't make sense.
+ *
+ * @template Reason - The union of allowed reason strings for this event
+ * @template CustomProperties - Additional component-specific properties
+ */
+interface GenericEventDetails<Reason extends string, _CustomProperties extends object = Record<string, never>> {
+    /**
+     * The reason why this event occurred.
+     */
+    reason: Reason;
+    /**
+     * The native DOM event that triggered this event.
+     */
+    event: ReasonToEvent<Reason>;
+}
+
+interface PopupMenuCheckboxItemState extends Record<string, unknown> {
+    /**
+     * Whether the item is highlighted (via keyboard or pointer).
+     */
+    highlighted: boolean;
+    /**
+     * Whether the item is disabled.
+     */
+    disabled: boolean;
+    /**
+     * Whether the item is currently checked.
+     */
+    checked: boolean;
+    first: boolean;
+    last: boolean;
+    firstInGroup: boolean;
+    lastInGroup: boolean;
+}
+interface PopupMenuCheckboxItemProps extends ComponentProps<'div', PopupMenuCheckboxItem.State> {
+    /**
+     * The controlled checked state.
+     */
+    checked?: boolean;
+    /**
+     * The default checked state for uncontrolled mode.
+     * @default false
+     */
+    defaultChecked?: boolean;
+    /**
+     * Callback fired when the checked state changes.
+     * The second parameter contains event details including the reason for the change.
+     */
+    onCheckedChange?: (checked: boolean, eventDetails: CheckedChangeEventDetails) => void;
+    /**
+     * Unique value for this item used for filtering.
+     * If not provided, will be inferred from textContent.
+     */
+    value?: string;
+    /**
+     * Additional keywords to match against when filtering.
+     * Useful for aliases or synonyms.
+     */
+    keywords?: string[];
+    /**
+     * Whether this item is disabled.
+     * Disabled items are not selectable and are skipped during keyboard navigation.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Callback when this item is selected (via click or Enter key).
+     */
+    onSelect?: () => void;
+    /**
+     * Whether to force render this item regardless of filter results.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Whether clicking this item should close the menu.
+     * @default false
+     */
+    closeOnClick?: boolean;
+    /**
+     * Keyboard shortcut to trigger this item.
+     * When the menu is focused and the user presses this key, the item will be selected.
+     * Should be a single character (e.g., "1", "a", etc.).
+     */
+    shortcut?: string;
+    /**
+     * Forces this row's relative order during score-based sorting.
+     * Lower values appear earlier.
+     * @default 0
+     */
+    forceOrder?: number;
+    /**
+     * Overrides this row's computed fuzzy-match score.
+     */
+    forceScore?: number;
+}
+/**
+ * A selectable checkbox item within a popup menu.
+ * Manages its own checked state independently.
+ * Renders a `<div>` element with role="menuitemcheckbox".
+ */
+declare const PopupMenuCheckboxItem: React.ForwardRefExoticComponent<Omit<PopupMenuCheckboxItem.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuCheckboxItem {
+    type State = PopupMenuCheckboxItemState;
+    interface Props extends PopupMenuCheckboxItemProps {
+    }
+}
+
+interface PopupMenuItemState extends Record<string, unknown> {
+    /**
+     * Whether the item is highlighted (via keyboard or pointer).
+     */
+    highlighted: boolean;
+    /**
+     * Whether the item is disabled.
+     */
+    disabled: boolean;
+    first: boolean;
+    last: boolean;
+    firstInGroup: boolean;
+    lastInGroup: boolean;
+}
+interface PopupMenuItemProps extends ComponentProps<'div', PopupMenuItem.State> {
+    /**
+     * Unique value for this item used for filtering.
+     * If not provided, will be inferred from textContent.
+     */
+    value?: string;
+    /**
+     * Additional keywords to match against when filtering.
+     * Useful for aliases or synonyms.
+     */
+    keywords?: string[];
+    /**
+     * Whether this item is disabled.
+     * Disabled items are not selectable and are skipped during keyboard navigation.
+     */
+    disabled?: boolean;
+    /**
+     * Whether this item can be activated via Enter or click.
+     * Non-activatable items are still highlightable via keyboard/pointer.
+     * @default true
+     */
+    activatable?: boolean;
+    /**
+     * Callback when this item is selected (via click or Enter key).
+     */
+    onSelect?: () => void;
+    /**
+     * Whether to force render this item regardless of filter results.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Whether clicking this item should close the menu.
+     * @default true
+     */
+    closeOnClick?: boolean;
+    /**
+     * Keyboard shortcut to trigger this item.
+     * When the menu is focused and the user presses this key, the item will be selected.
+     * Should be a single character (e.g., "1", "a", etc.).
+     */
+    shortcut?: string;
+    /**
+     * Forces this row's relative order during score-based sorting.
+     * Lower values appear earlier.
+     * @default 0
+     */
+    forceOrder?: number;
+    /**
+     * Overrides this row's computed fuzzy-match score.
+     */
+    forceScore?: number;
+}
+/**
+ * A selectable item in the popup menu.
+ * Renders a `<div>` element with role="option".
+ */
+declare const PopupMenuItem: React.ForwardRefExoticComponent<Omit<PopupMenuItem.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuItem {
+    type State = PopupMenuItemState;
+    interface Props extends PopupMenuItemProps {
+    }
+}
+
+interface PopupMenuRadioGroupState extends Record<string, unknown> {
+    /**
+     * Whether the radio group is disabled.
+     */
+    disabled: 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 PopupMenuRadioGroupProps extends ComponentProps<'div', PopupMenuRadioGroup.State> {
+    /**
+     * The controlled selected value.
+     */
+    value?: string;
+    /**
+     * The default value for uncontrolled mode.
+     */
+    defaultValue?: string;
+    /**
+     * 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;
+    /**
+     * Whether to force render this group regardless of filter results.
+     * @default false
+     */
+    forceMount?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Groups radio items together and manages the selected value.
+ * Only one item can be selected at a time within a radio group.
+ * Renders a `<div>` element with role="group".
+ */
+declare const PopupMenuRadioGroup: React.ForwardRefExoticComponent<Omit<PopupMenuRadioGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuRadioGroup {
+    type State = PopupMenuRadioGroupState;
+    interface Props extends PopupMenuRadioGroupProps {
+    }
+}
+
+interface PopupMenuRadioItemState extends Record<string, unknown> {
+    /**
+     * Whether the item is highlighted (via keyboard or pointer).
+     */
+    highlighted: boolean;
+    /**
+     * Whether the item is disabled.
+     */
+    disabled: boolean;
+    /**
+     * Whether the item is currently selected/checked.
+     */
+    checked: boolean;
+    first: boolean;
+    last: boolean;
+    firstInGroup: boolean;
+    lastInGroup: boolean;
+}
+interface PopupMenuRadioItemProps extends ComponentProps<'div', PopupMenuRadioItem.State> {
+    /**
+     * The value to set when this item is selected.
+     * This is required and must be unique within the RadioGroup.
+     */
+    value: string;
+    /**
+     * Additional keywords to match against when filtering.
+     * Useful for aliases or synonyms.
+     */
+    keywords?: string[];
+    /**
+     * Whether this item is disabled.
+     * Disabled items are not selectable and are skipped during keyboard navigation.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Callback when this item is selected.
+     */
+    onSelect?: () => void;
+    /**
+     * Whether to force render this item regardless of filter results.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Whether clicking this item should close the menu.
+     * @default false
+     */
+    closeOnClick?: boolean;
+    /**
+     * Keyboard shortcut to trigger this item.
+     * When the menu is focused and the user presses this key, the item will be selected.
+     * Should be a single character (e.g., "1", "a", etc.).
+     */
+    shortcut?: string;
+    /**
+     * Forces this row's relative order during score-based sorting.
+     * Lower values appear earlier.
+     * @default 0
+     */
+    forceOrder?: number;
+    /**
+     * Overrides this row's computed fuzzy-match score.
+     */
+    forceScore?: number;
+}
+/**
+ * A selectable radio item within a RadioGroup.
+ * Only one RadioItem can be selected at a time within a RadioGroup.
+ * Renders a `<div>` element with role="menuitemradio".
+ */
+declare const PopupMenuRadioItem: React.ForwardRefExoticComponent<Omit<PopupMenuRadioItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuRadioItem {
+    type State = PopupMenuRadioItemState;
+    interface Props extends PopupMenuRadioItemProps {
+    }
+}
+
+interface PopupMenuSubmenuTriggerState extends Record<string, unknown> {
+    /**
+     * Whether this is a submenu trigger (always true).
+     */
+    submenuTrigger: boolean;
+    /**
+     * Whether the submenu popup is open.
+     */
+    popupOpen: boolean;
+    /**
+     * Whether the submenu owns keyboard focus.
+     */
+    popupFocused: boolean;
+    /**
+     * Whether the item is highlighted.
+     */
+    highlighted: boolean;
+    /**
+     * Whether the item is disabled.
+     */
+    disabled: boolean;
+    first: boolean;
+    last: boolean;
+    firstInGroup: boolean;
+    lastInGroup: boolean;
+}
+interface PopupMenuSubmenuTriggerProps extends ComponentProps<'div', PopupMenuSubmenuTrigger.State> {
+    /**
+     * Explicit unique identifier for this item in the store.
+     * When provided (e.g., from data-first API's computed composite ID),
+     * this takes priority over `value` for store registration.
+     */
+    id?: string;
+    /**
+     * Unique value for this item used for filtering.
+     * If not provided, will be inferred from textContent.
+     */
+    value?: string;
+    /**
+     * Additional keywords to match against when filtering.
+     * Useful for aliases or synonyms.
+     */
+    keywords?: string[];
+    /**
+     * Whether this item is disabled.
+     * Disabled items are not selectable and are skipped during keyboard navigation.
+     */
+    disabled?: boolean;
+    /**
+     * Whether to force render this item regardless of filter results.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Whether the submenu opens when this trigger is highlighted.
+     * @default true
+     */
+    openOnHighlight?: boolean;
+    /**
+     * Delay before opening the submenu (in milliseconds).
+     * Can be a number (applies to both pointer and keyboard) or an object
+     * with separate `pointer` and `keyboard` values.
+     * @default { pointer: 0, keyboard: 150 }
+     */
+    delay?: number | {
+        pointer?: number;
+        keyboard?: number;
+    };
+    /**
+     * Delay before closing the submenu when pointer leaves (in milliseconds).
+     * @default 0
+     */
+    closeDelay?: number;
+    /**
+     * Whether the submenu closes when the pointer leaves the trigger without aiming at the submenu popup.
+     * When `false`, the submenu stays open until closed by another path (sibling highlight, keyboard, outside click, etc.).
+     * @default true
+     */
+    closeOnPointerLeave?: boolean;
+    /**
+     * Forces this row's relative order during score-based sorting.
+     * Lower values appear earlier.
+     * @default 0
+     */
+    forceOrder?: number;
+    /**
+     * Overrides this row's computed fuzzy-match score.
+     */
+    forceScore?: number;
+}
+/**
+ * A menu item that opens a submenu when hovered.
+ * Must be used within PopupMenu.Submenu.
+ * Renders a `<div>` element with role="menuitem" wrapped in Popover.Trigger.
+ */
+declare const PopupMenuSubmenuTrigger: React.ForwardRefExoticComponent<Omit<PopupMenuSubmenuTrigger.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuSubmenuTrigger {
+    type State = PopupMenuSubmenuTriggerState;
+    interface Props extends PopupMenuSubmenuTriggerProps {
+    }
+}
+
+interface PopupMenuSubpageTriggerState extends Record<string, unknown> {
+    /** Whether this is a subpage trigger (always true). */
+    subpageTrigger: boolean;
+    /** Whether the target page is active. */
+    popupOpen: boolean;
+    /** Whether the target page owns keyboard focus. */
+    popupFocused: boolean;
+    /** Whether the item is highlighted. */
+    highlighted: boolean;
+    /** Whether the item is disabled. */
+    disabled: boolean;
+    first: boolean;
+    last: boolean;
+    firstInGroup: boolean;
+    lastInGroup: boolean;
+}
+interface PopupMenuSubpageTriggerProps extends ComponentProps<'div', PopupMenuSubpageTrigger.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;
+    /**
+     * Forces this row's relative order during score-based sorting.
+     * Lower values appear earlier.
+     * @default 0
+     */
+    forceOrder?: number;
+    /**
+     * Overrides this row's computed fuzzy-match score.
+     */
+    forceScore?: number;
+    /** Target page ID to open when this trigger is selected. */
+    targetPageId: string;
+}
+/**
+ * A menu item that pushes a new page in the same popup.
+ * Renders a `<div>` element with role="menuitem".
+ */
+declare const PopupMenuSubpageTrigger: React.ForwardRefExoticComponent<Omit<PopupMenuSubpageTrigger.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuSubpageTrigger {
+    type State = PopupMenuSubpageTriggerState;
+    interface Props extends PopupMenuSubpageTriggerProps {
+    }
+}
+
+/**
+ * Library-agnostic result from an async loader.
+ * Compatible with TanStack Query, SWR, and custom loaders.
+ */
+type AsyncLoaderSource = 'tanstack-query' | 'swr' | 'vanilla' | 'custom';
+/**
+ * Canonical async loader status.
+ * - 'idle': no request has been executed yet
+ * - 'pending': request in progress and no successful data yet
+ * - 'success': last resolved state has data
+ * - 'error': last resolved state errored
+ */
+type AsyncLoaderStatus = 'idle' | 'pending' | 'success' | 'error';
+/**
+ * Canonical fetch status.
+ */
+type AsyncLoaderFetchStatus = 'idle' | 'fetching' | 'paused';
+/**
+ * Loading phase for distinguishing first-load from background revalidation.
+ */
+type AsyncLoaderLoadingPhase = 'none' | 'initial' | 'background';
+interface AsyncLoaderResult<TData, TRaw = unknown> {
+    /** The loaded data, undefined while loading or on error */
+    data: TData | undefined;
+    /** Raw result object returned by the underlying data library */
+    raw?: TRaw;
+    /** Source data library backing this result */
+    source?: AsyncLoaderSource;
+    /** Error if the load failed, null otherwise */
+    error: Error | null;
+    /** Canonical status state */
+    status: AsyncLoaderStatus;
+    /** Canonical fetch state */
+    fetchStatus: AsyncLoaderFetchStatus;
+    /** Distinguishes initial load vs background fetch */
+    loadingPhase: AsyncLoaderLoadingPhase;
+    /** True during the initial loading phase (TanStack-aligned semantics) */
+    isLoading: boolean;
+    /** Whether any fetch is currently in-flight */
+    isFetching: boolean;
+    /** Alias of `isLoading` for explicit phase naming */
+    isInitialLoading: boolean;
+    /** True when background re-fetch is in-flight */
+    isRefetching: boolean;
+    /** Whether query state is pending */
+    isPending: boolean;
+    /** Whether query state is successful */
+    isSuccess: boolean;
+    /** Whether the loader encountered an error */
+    isError: boolean;
+    /** Whether fetching is paused */
+    isPaused: boolean;
+    /** Whether data is currently available */
+    hasData: boolean;
+    /** Whether any fetch has completed at least once */
+    hasFetched: boolean;
+    /** Optional function to refetch the data */
+    refetch?: () => unknown;
+}
+/**
+ * Props passed to loader components.
+ * The component should call hooks internally and pass the result to children.
+ */
+interface LoaderComponentProps {
+    /** Search query (for query loaders) */
+    query: string;
+    /** Whether the loader should execute its fetch/query hook */
+    enabled?: boolean;
+    /** Render function receiving loader state */
+    children: (state: AsyncLoaderResult<NodeDef[]>) => React.ReactNode;
+}
+/**
+ * Controls query-loader behavior before users type an active query.
+ */
+interface InitialQueryBehavior {
+    /**
+     * Query value used before user input reaches minQueryLength.
+     * Defaults to '' (top/default results).
+     * @default ''
+     */
+    value?: string;
+    /**
+     * When the initial query should load.
+     * - 'needed': when submenu is explicitly opened or needed for deep-search execution
+     * - 'parent-open': eagerly when direct parent opens
+     * @default 'needed'
+     */
+    loadWhen?: 'needed' | 'parent-open';
+}
+/**
+ * Static loader configuration.
+ * Loads data once, then filters client-side.
+ */
+interface StaticLoaderConfig {
+    type: 'static';
+    /**
+     * Component that calls hooks and provides loader state.
+     * This component pattern allows hooks to be called legally within React's rules.
+     */
+    Loader: React.ComponentType<LoaderComponentProps>;
+    /**
+     * When to trigger the loader:
+     * - 'eager': Load when menu opens (good for deep search)
+     * - 'lazy': Load when submenu opens (default)
+     * @default 'lazy'
+     */
+    loadStrategy?: 'eager' | 'lazy';
+}
+/**
+ * Query loader configuration.
+ * Refetches based on search query - server does the filtering.
+ */
+interface QueryLoaderConfig {
+    type: 'query';
+    /**
+     * Component that calls hooks and provides loader state.
+     * Receives the current search query as a prop.
+     */
+    Loader: React.ComponentType<LoaderComponentProps>;
+    /**
+     * Minimum query length before fetching.
+     * @default 1
+     */
+    minQueryLength?: number;
+    /**
+     * Defines behavior before user query reaches minQueryLength.
+     * - object: executes query loader with the configured initial value (default behavior)
+     * - false: disables initial fetch until query reaches minQueryLength
+     * @default { value: '', loadWhen: 'needed' }
+     */
+    initialQueryBehavior?: InitialQueryBehavior | false;
+    /**
+     * @deprecated Use `initialQueryBehavior` instead.
+     */
+    initialQuery?: string;
+    /**
+     * When to trigger the loader:
+     * - 'eager': Load when root menu opens (good for deep search)
+     * - 'lazy': Load when submenu opens (default)
+     * @default 'lazy'
+     */
+    loadStrategy?: 'eager' | 'lazy';
+    /**
+     * What to show when query is below minQueryLength.
+     * - 'empty': Show nothing
+     * - 'placeholder': Show placeholderNodes
+     * @default 'empty'
+     */
+    belowMinBehavior?: 'empty' | 'placeholder';
+    /**
+     * Placeholder nodes shown when query is below minQueryLength.
+     */
+    placeholderNodes?: NodeDef[];
+}
+/**
+ * Controls how submenu content participates in ancestor deep search results.
+ * - `true`: include submenu trigger and descendants
+ * - `'trigger-only'`: include submenu trigger only
+ * - `false`: exclude submenu trigger and descendants
+ */
+type IncludeInDeepSearch = true | 'trigger-only' | false;
+/**
+ * Union of all async loader configurations.
+ */
+type AsyncLoaderConfig = StaticLoaderConfig | QueryLoaderConfig;
+/**
+ * Static async nodes configuration for submenus.
+ */
+type StaticAsyncNodesConfig = StaticLoaderConfig;
+/**
+ * Query async nodes configuration for submenus.
+ */
+type QueryAsyncNodesConfig = QueryLoaderConfig;
+/**
+ * Async nodes configuration for submenus.
+ * Union of static and query loader configs.
+ */
+type AsyncNodesConfig = StaticAsyncNodesConfig | QueryAsyncNodesConfig;
+/**
+ * Async state exposed to submenu render functions.
+ */
+interface AsyncRenderState {
+    /** Canonical status state */
+    status: AsyncLoaderStatus;
+    /** Canonical fetch state */
+    fetchStatus: AsyncLoaderFetchStatus;
+    /** Distinguishes initial load vs background fetch */
+    loadingPhase: AsyncLoaderLoadingPhase;
+    /** True during the initial loading phase */
+    isLoading: boolean;
+    /** Whether any fetch is currently in-flight */
+    isFetching: boolean;
+    /** Alias of `isLoading` for explicit phase naming */
+    isInitialLoading: boolean;
+    /** True when background re-fetch is in-flight */
+    isRefetching: boolean;
+    /** Whether the loader encountered an error */
+    isError: boolean;
+    /** The error if any */
+    error: Error | null;
+    /** For query loaders: whether query is below minQueryLength */
+    isBelowMinLength?: boolean;
+}
+/**
+ * Aggregate async state exposed to DataList children.
+ */
+interface AsyncState {
+    /** Any loader is currently in initial loading phase */
+    isLoading: boolean;
+    /** Any loader is currently fetching */
+    isFetching: boolean;
+    /** Any loader is in first-load phase */
+    isInitialLoading: boolean;
+    /** Any loader is in background refetch phase */
+    isRefetching: boolean;
+    /** All registered loaders are in background refetch phase */
+    isAllRefetching: boolean;
+    /** Static loaders specifically are loading */
+    isStaticLoading: boolean;
+    /** Static loaders in first-load phase */
+    isStaticInitialLoading: boolean;
+    /** Static loaders in background refetch phase */
+    isStaticRefetching: boolean;
+    /** Query loaders specifically are loading */
+    isQueryLoading: boolean;
+    /** Query loaders in first-load phase */
+    isQueryInitialLoading: boolean;
+    /** Query loaders in background refetch phase */
+    isQueryRefetching: boolean;
+    /** Menus that failed (skipped from results) */
+    skippedMenus: Array<{
+        kind: 'root';
+        reason: 'error';
+    } | {
+        kind: 'branch';
+        id: string;
+        reason: 'error';
+    }>;
+}
+/**
+ * Branch node info passed in breadcrumbs context.
+ * Contains the full submenu/subpage definition for maximum flexibility.
+ */
+interface BreadcrumbNode {
+    /** The branch node definition */
+    node: SubmenuDef | SubpageDef | TreeItemDef;
+    /** The branch Menu Node. `node`, `value`, and `id` mirror its def for compatibility. */
+    menuNode: PopupMenuNode<SubmenuDef | SubpageDef | TreeItemDef>;
+    /** The branch node's value */
+    value: string;
+    /** The branch node's explicit id (if provided) */
+    id?: string;
+}
+/**
+ * Context passed to item, submenu, and subpage render functions.
+ * Provides information about the current rendering context (search, breadcrumbs, state).
+ */
+interface RowRenderContext {
+    /**
+     * Search context - the query in the menu where this row is being rendered.
+     * `null` if no active search (browsing mode).
+     */
+    search: {
+        /** Current search query */
+        query: string;
+        /** Match score for this row (higher = better match). */
+        score: number;
+    } | null;
+    /**
+     * Full path of branch nodes from root to this row's parent.
+     * Contains the full submenu/subpage node definitions for maximum flexibility.
+     * Empty array [] for items directly in root menu.
+     */
+    breadcrumbs: BreadcrumbNode[];
+    /**
+     * True if this row is being rendered outside its "home" menu
+     * (surfaced via deep search from an ancestor menu).
+     */
+    isDeepSearchResult: boolean;
+    /** Whether this row is currently highlighted/focused */
+    highlighted: boolean;
+    /** Whether this row is disabled */
+    disabled: boolean;
+    /**
+     * The group this item belongs to, if any.
+     * `null` if the item is not inside a group.
+     */
+    group: {
+        id: string;
+        label?: string;
+    } | null;
+    /** Tree rendering context, or null for non-tree and search rows. */
+    tree: {
+        depth: number;
+        hasChildren: boolean;
+        isLastChild: boolean;
+        ancestorsLast: boolean[];
+        header: boolean;
+    } | null;
+}
+/**
+ * Props to spread onto the Item component.
+ * Derived from PopupMenuItemProps.
+ */
+type ItemRenderProps = {
+    /**
+     * Canonical Resolved ID for the item, generated by the root policy: the
+     * encoded surface Definition Path by default, or the Definition Key in
+     * menu scope.
+     * Must be passed to the rendered component for navigation to work.
+     */
+    id: string;
+    /**
+     * The original value from the node definition.
+     * Use this for display, search matching, or any logic that needs the raw value.
+     */
+    value: string;
+} & Required<Pick<PopupMenuItemProps, 'disabled'>> & Pick<PopupMenuItemProps, 'closeOnClick' | 'onSelect' | 'shortcut' | 'forceOrder' | 'forceScore'>;
+/**
+ * Parameters passed to item render functions.
+ */
+interface ItemRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props to spread onto the Item component */
+    props: ItemRenderProps;
+    /** Context for conditional rendering (includes props values for convenience) */
+    context: RowRenderContext & {
+        /** The node's value (ItemDef.value) */
+        value: string;
+        disabled: boolean;
+    };
+}
+/** Props to spread onto a TreeItem component. */
+type TreeItemRenderProps = Omit<ItemRenderProps, 'shortcut'> & {
+    /** Whether this row can be selected. */
+    selectable: boolean;
+};
+/** Parameters passed to tree item render functions. */
+interface TreeItemRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    props: TreeItemRenderProps;
+    context: RowRenderContext & {
+        value: string;
+        disabled: boolean;
+    };
+}
+/**
+ * Props to spread onto the RadioItem component.
+ * Derived from PopupMenuRadioItemProps.
+ */
+type RadioItemRenderProps = {
+    /**
+     * Qualified unique ID for the radio item.
+     * Must be passed to the rendered component for navigation to work.
+     */
+    id: string;
+} & Required<Pick<PopupMenuRadioItemProps, 'value' | 'disabled'>> & Pick<PopupMenuRadioItemProps, 'closeOnClick' | 'onSelect' | 'shortcut' | 'forceOrder' | 'forceScore'>;
+/**
+ * Parameters passed to radio item render functions.
+ */
+interface RadioItemRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props to spread onto the RadioItem component */
+    props: RadioItemRenderProps;
+    /** Context for conditional rendering (includes props values for convenience) */
+    context: RowRenderContext & {
+        /** The node's value (RadioItemDef.value) */
+        value: string;
+        disabled: boolean;
+    };
+}
+/**
+ * Props to spread onto the SubmenuTrigger component.
+ * Derived from PopupMenuSubmenuTriggerProps.
+ */
+type SubmenuRenderProps = {
+    /**
+     * Qualified unique ID for the submenu trigger.
+     * Must be passed to the rendered component for navigation to work.
+     */
+    id: string;
+    /**
+     * The original value from the node definition.
+     */
+    value: string;
+} & Required<Pick<PopupMenuSubmenuTriggerProps, 'disabled'>> & Pick<PopupMenuSubmenuTriggerProps, 'forceOrder' | 'forceScore'>;
+/**
+ * Parameters passed to submenu render functions.
+ * Includes context plus the submenu's child nodes and render function.
+ */
+interface SubmenuRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props to spread onto the SubmenuTrigger */
+    props: SubmenuRenderProps;
+    /** Context for conditional rendering (includes props values for convenience) */
+    context: RowRenderContext & {
+        /** The node's value (SubmenuDef.value) */
+        value: string;
+        disabled: boolean;
+        /** Async loading state (if asyncNodes configured) */
+        async?: AsyncRenderState;
+    };
+    /** The branch's resolved static child Menu Nodes, in def order. Loader results are grafted as children of `node` but are not included here — use `asyncContent` to load them. Authored fields are on `child.def`. */
+    nodes: PopupMenuNode[];
+    /**
+     * Async content configuration for this submenu.
+     * Pass this to the submenu's DataSurface to enable async loading
+     * with the submenu's own search query (independent of parent search).
+     */
+    asyncContent?: AsyncNodesConfig;
+    /** Render one child Menu Node from `nodes`. */
+    renderNode: (node: PopupMenuNode) => React.ReactNode;
+}
+/**
+ * Props to spread onto the SubpageTrigger component.
+ * Derived from PopupMenuSubpageTriggerProps.
+ */
+type SubpageTriggerRenderProps = {
+    /**
+     * Qualified unique ID for the subpage trigger.
+     * Must be passed to the rendered component for navigation to work.
+     */
+    id: string;
+    /**
+     * The original value from the node definition.
+     */
+    value: string;
+    /**
+     * Computed page ID for the associated Subpage content.
+     * Must be passed to `targetPageId` on SubpageTrigger.
+     */
+    targetPageId: string;
+} & Required<Pick<PopupMenuSubpageTriggerProps, 'disabled'>>;
+/**
+ * Parameters passed to subpage trigger render functions.
+ */
+interface SubpageTriggerRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props to spread onto the SubpageTrigger */
+    props: SubpageTriggerRenderProps;
+    /** Context for conditional rendering (includes props values for convenience) */
+    context: RowRenderContext & {
+        /** The node's value (SubpageDef.value) */
+        value: string;
+        disabled: boolean;
+        /** Async loading state (if asyncNodes configured) */
+        async?: AsyncRenderState;
+    };
+}
+/**
+ * Parameters passed to subpage content render functions.
+ * The returned JSX should include a `<PopupMenu.Subpage pageId={pageId}>` wrapper.
+ */
+interface SubpageContentRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** The subpage's Resolved ID (`node.id`); pass it to `<Subpage pageId>`. */
+    pageId: string;
+    /** Context for conditional rendering */
+    context: RowRenderContext & {
+        /** The node's value (SubpageDef.value) */
+        value: string;
+        disabled: boolean;
+        /** Async loading state (if asyncNodes configured) */
+        async?: AsyncRenderState;
+    };
+    /** The branch's resolved static child Menu Nodes, in def order. Loader results are grafted as children of `node` but are not included here — use `asyncContent` to load them. Authored fields are on `child.def`. */
+    nodes: PopupMenuNode[];
+    /**
+     * Async content configuration for this subpage.
+     * Pass this to the subpage's DataSurface to enable async loading
+     * with the subpage's own search query (independent of parent search).
+     */
+    asyncContent?: AsyncNodesConfig;
+    /** Render one child Menu Node from `nodes`. */
+    renderNode: (node: PopupMenuNode) => React.ReactNode;
+}
+/**
+ * Context passed to group render functions.
+ * Contains information about the group's state during search.
+ */
+interface GroupRenderContext {
+    /**
+     * Search context with the best match score among items in this group.
+     * `null` if no active search (browsing mode).
+     */
+    search: {
+        /** Current search query */
+        query: string;
+        /** Best match score among items in this group (higher = better match). */
+        bestScore: number;
+    } | null;
+    /** Number of matching items in this group */
+    matchCount: number;
+    /**
+     * Breadcrumb nodes if this group is from a surfaced submenu.
+     * Empty array [] for groups in the root menu.
+     */
+    breadcrumbs: BreadcrumbNode[];
+    /** Whether this group is from deep search (surfaced from a submenu) */
+    isDeepSearchResult: boolean;
+}
+/**
+ * Parameters passed to group render functions.
+ */
+interface GroupRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props (empty for groups, but consistent structure) */
+    props: Record<string, never>;
+    /** Context for conditional rendering (includes label for convenience) */
+    context: GroupRenderContext & {
+        /** The group's label */
+        label?: string;
+    };
+    /** Pre-rendered matching children */
+    children: React.ReactNode;
+}
+/**
+ * Parameters passed to group label render functions.
+ */
+interface GroupLabelRenderParams {
+    /** The resolved menu node for this group — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props to spread onto the label element (stable id for aria wiring) */
+    props: {
+        id: string;
+    };
+    /** Context for conditional rendering (includes label for convenience) */
+    context: GroupRenderContext & {
+        /** The group's label */
+        label?: string;
+    };
+}
+/**
+ * Props to spread onto the CheckboxItem component.
+ * Derived from PopupMenuCheckboxItemProps.
+ */
+type CheckboxItemRenderProps = {
+    /**
+     * Qualified unique ID for the checkbox item.
+     * Must be passed to the rendered component for navigation to work.
+     */
+    id: string;
+    /**
+     * The original value from the node definition.
+     */
+    value: string;
+} & Required<Pick<PopupMenuCheckboxItemProps, 'disabled'>> & Pick<PopupMenuCheckboxItemProps, 'checked' | 'onCheckedChange' | 'closeOnClick' | 'forceOrder' | 'forceScore'>;
+/**
+ * Parameters passed to checkbox item render functions.
+ */
+interface CheckboxItemRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props to spread onto the CheckboxItem component */
+    props: CheckboxItemRenderProps;
+    /** Context for conditional rendering (includes props values for convenience) */
+    context: RowRenderContext & {
+        /** The node's value (CheckboxItemDef.value) */
+        value: string;
+        checked?: boolean;
+        disabled: boolean;
+    };
+}
+/**
+ * Props to spread onto the RadioGroup component.
+ * Derived from PopupMenuRadioGroupProps.
+ */
+type RadioGroupRenderProps = Required<Pick<PopupMenuRadioGroupProps, 'disabled'>> & Pick<PopupMenuRadioGroupProps, 'value' | 'onValueChange'>;
+/**
+ * Parameters passed to radio group render functions.
+ */
+interface RadioGroupRenderParams {
+    /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props to spread onto the RadioGroup component */
+    props: RadioGroupRenderProps;
+    /** Context for conditional rendering */
+    context: GroupRenderContext & {
+        /** The radio group's label */
+        label?: string;
+        /** Current selected value */
+        value?: string;
+        /** Whether the radio group is disabled */
+        disabled: boolean;
+    };
+    /** Pre-rendered radio items */
+    children: React.ReactNode;
+}
+/**
+ * Parameters passed to radio group label render functions.
+ */
+interface RadioGroupLabelRenderParams {
+    /** The resolved menu node for this group — canonical identity (`node.id`), definition path, and tree links */
+    node: PopupMenuNode;
+    /** Props to spread onto the label element (stable id for aria wiring) */
+    props: {
+        id: string;
+    };
+    /** Context for conditional rendering (includes label for convenience) */
+    context: GroupRenderContext & {
+        /** The radio group's label */
+        label?: string;
+        /** Current selected value */
+        value?: string;
+        /** Whether the radio group is disabled */
+        disabled: boolean;
+    };
+}
+/**
+ * Base properties shared by all node types.
+ */
+interface BaseNodeDef {
+    /**
+     * Unique identifier for this node.
+     * If provided, it contributes the Definition Key and encoded surface path;
+     * Resolved ID generation otherwise follows the root policy or its
+     * `getResolvedId` seam.
+     */
+    id?: string;
+    /** Whether this node is hidden */
+    hidden?: boolean;
+}
+/**
+ * Item node definition.
+ * Represents a selectable menu item.
+ * Props derived from PopupMenuItemProps.
+ */
+interface ItemDef extends BaseNodeDef, Required<Pick<PopupMenuItemProps, 'value'>>, Pick<PopupMenuItemProps, 'keywords' | 'disabled' | 'onSelect' | 'closeOnClick' | 'shortcut' | 'forceOrder' | 'forceScore'> {
+    kind: 'item';
+    /**
+     * Render function for this item row.
+     * Returns the JSX for the item.
+     */
+    render: (params: ItemRenderParams) => React.ReactNode;
+}
+/** Tree item node definition. */
+interface TreeItemDef extends BaseNodeDef, Required<Pick<PopupMenuItemProps, 'value'>>, Pick<PopupMenuItemProps, 'keywords' | 'disabled' | 'onSelect' | 'closeOnClick' | 'forceOrder' | 'forceScore'> {
+    kind: 'tree-item';
+    /** Whether this row itself can be selected. */
+    selectable?: boolean;
+    /** Inline children rendered in the same list. */
+    nodes?: NodeDef[];
+    /** Whether descendants surface in deep search results. */
+    deepSearch?: boolean;
+    /** Render function for this row. */
+    render: (params: TreeItemRenderParams) => React.ReactNode;
+}
+/**
+ * Radio item node definition.
+ * Represents a selectable radio menu item for use within RadioGroupDef.
+ * Props derived from PopupMenuRadioItemProps.
+ */
+interface RadioItemDef extends BaseNodeDef, Required<Pick<PopupMenuRadioItemProps, 'value'>>, Pick<PopupMenuRadioItemProps, 'keywords' | 'disabled' | 'onSelect' | 'closeOnClick' | 'shortcut' | 'forceOrder' | 'forceScore'> {
+    kind: 'radio-item';
+    /**
+     * Render function for this radio item row.
+     * Returns the JSX for the radio item.
+     */
+    render: (params: RadioItemRenderParams) => React.ReactNode;
+}
+/**
+ * Checkbox item node definition.
+ * Represents a toggleable checkbox menu item.
+ * Props derived from PopupMenuCheckboxItemProps.
+ */
+interface CheckboxItemDef extends BaseNodeDef, Pick<PopupMenuCheckboxItemProps, 'keywords' | 'disabled' | 'checked' | 'onCheckedChange' | 'closeOnClick' | 'forceOrder' | 'forceScore'> {
+    kind: 'checkbox-item';
+    /**
+     * Primary identifier and search text for this checkbox item.
+     * Used for search matching and as the default identifier.
+     */
+    value: string;
+    /**
+     * Render function for this checkbox item row.
+     * Returns the JSX for the checkbox item.
+     */
+    render: (params: CheckboxItemRenderParams) => React.ReactNode;
+}
+/**
+ * Submenu node definition.
+ * Represents a submenu trigger that opens a nested menu.
+ * Props derived from PopupMenuSubmenuTriggerProps.
+ */
+interface SubmenuDef extends BaseNodeDef, Required<Pick<PopupMenuSubmenuTriggerProps, 'value'>>, Pick<PopupMenuSubmenuTriggerProps, 'keywords' | 'disabled' | 'forceOrder' | 'forceScore'> {
+    kind: 'submenu';
+    /** Static child nodes */
+    nodes?: NodeDef[];
+    /**
+     * Async child nodes configuration.
+     * When provided, the Loader component will be rendered to fetch async data.
+     * Async nodes are merged with static nodes.
+     */
+    asyncNodes?: AsyncNodesConfig;
+    /**
+     * Whether to include this submenu's descendants in deep search.
+     * @default true
+     */
+    deepSearch?: boolean;
+    /**
+     * Whether this submenu is included in ancestor deep search results.
+     * - `true`: include submenu trigger and descendants
+     * - `'trigger-only'`: include submenu trigger only
+     * - `false`: exclude submenu trigger and descendants
+     * @default true
+     */
+    includeInDeepSearch?: IncludeInDeepSearch;
+    /**
+     * Render function for the entire submenu structure.
+     * Should return the complete submenu: trigger, portal, positioner, popup, surface, list.
+     */
+    render: (params: SubmenuRenderParams) => React.ReactNode;
+}
+/**
+ * Subpage node definition.
+ * Represents a trigger row that opens a page in the same popup.
+ * Props derived from PopupMenuSubpageTriggerProps.
+ */
+interface SubpageDef extends BaseNodeDef, Required<Pick<PopupMenuSubpageTriggerProps, 'value'>>, Pick<PopupMenuSubpageTriggerProps, 'keywords' | 'disabled' | 'forceOrder' | 'forceScore'> {
+    kind: 'subpage';
+    /** Static child nodes */
+    nodes?: NodeDef[];
+    /**
+     * Async child nodes configuration.
+     * When provided, the Loader component will be rendered to fetch async data.
+     * Async nodes are merged with static nodes.
+     */
+    asyncNodes?: AsyncNodesConfig;
+    /**
+     * Whether to include this subpage's descendants in deep search.
+     * @default true
+     */
+    deepSearch?: boolean;
+    /**
+     * Whether this subpage is included in ancestor deep search results.
+     * - `true`: include subpage trigger and descendants
+     * - `'trigger-only'`: include subpage trigger only
+     * - `false`: exclude subpage trigger and descendants
+     * @default true
+     */
+    includeInDeepSearch?: IncludeInDeepSearch;
+    /**
+     * Render function for the trigger row.
+     * Should return a `SubpageTrigger`.
+     */
+    renderTrigger: (params: SubpageTriggerRenderParams) => React.ReactNode;
+    /**
+     * Render function for the subpage content.
+     * Should return a `Subpage` rendered alongside the root Surface in Popup.
+     */
+    renderContent: (params: SubpageContentRenderParams) => React.ReactNode;
+}
+/**
+ * Render params for separator nodes.
+ */
+interface SeparatorRenderParams {
+    /** Props to spread on the separator element */
+    props: {
+        /** Unique identifier */
+        id?: string;
+    };
+}
+/**
+ * Separator node definition.
+ * Represents a visual separator between items.
+ */
+interface SeparatorDef {
+    kind: 'separator';
+    /** Unique identifier */
+    id: string;
+    /** Optional render function for custom separator rendering */
+    render?: (params: SeparatorRenderParams) => React.ReactNode;
+}
+/**
+ * Group node definition.
+ * Represents a group of items with an optional label.
+ */
+interface GroupDef {
+    kind: 'group';
+    /** Unique identifier for this group */
+    id: string;
+    /** Optional group heading/label */
+    label?: string;
+    /** Child nodes in this group */
+    nodes: NodeDef[];
+    /** Optional render function for the group container */
+    render?: (params: GroupRenderParams) => React.ReactNode;
+    /**
+     * Optional render function for the group's label row.
+     * Used by the default group container when no `render` is provided, and by
+     * virtualized lists (which ignore `render` and use only the label row).
+     * Precedence: `render` > `renderLabel` > `label`.
+     */
+    renderLabel?: (params: GroupLabelRenderParams) => React.ReactNode;
+}
+/**
+ * Radio group node definition.
+ * Represents a group of radio items where only one can be selected.
+ * Props derived from PopupMenuRadioGroupProps.
+ */
+interface RadioGroupDef extends Pick<PopupMenuRadioGroupProps, 'value' | 'onValueChange' | 'disabled'> {
+    kind: 'radio-group';
+    /** Unique identifier for this radio group */
+    id: string;
+    /** Optional group heading/label */
+    label?: string;
+    /** Whether the radio group is hidden */
+    hidden?: boolean;
+    /** Child nodes in this radio group - must be RadioItemDef nodes */
+    nodes: RadioItemDef[];
+    /** Optional render function for the radio group container */
+    render?: (params: RadioGroupRenderParams) => React.ReactNode;
+    /**
+     * Optional render function for the radio group's label row.
+     * Used by the default radio group container when no `render` is provided, and by
+     * virtualized lists (which ignore `render` and use only the label row).
+     * Precedence: `render` > `renderLabel` > `label`.
+     */
+    renderLabel?: (params: RadioGroupLabelRenderParams) => React.ReactNode;
+}
+/**
+ * Helper function to create a radio group definition with proper typing.
+ */
+declare function defineRadioGroup(def: RadioGroupDef): RadioGroupDef;
+/**
+ * Union of all node definition types.
+ */
+type NodeDef = ItemDef | TreeItemDef | RadioItemDef | CheckboxItemDef | SubmenuDef | SubpageDef | SeparatorDef | GroupDef | RadioGroupDef;
+/**
+ * A node with its search score and breadcrumb path.
+ * Used internally during filtering and scoring.
+ */
+interface ScoredNode {
+    /** The row's Menu Node; its authored definition is `node.def`. */
+    node: PopupMenuNode<RowNodeDef>;
+    /** Search match score (higher = better match). */
+    score: number;
+    /**
+     * Breadcrumb nodes leading to this node.
+     * Contains the full submenu definitions for maximum flexibility.
+     */
+    breadcrumbs: BreadcrumbNode[];
+    /** The group this node belongs to, if any */
+    group: {
+        id: string;
+        label?: string;
+        groupDef: GroupDef;
+        menuNode: PopupMenuNode<GroupDef>;
+    } | null;
+    /** The radio group this node belongs to, if any */
+    radioGroup: {
+        id: string;
+        label?: string;
+        radioGroupDef: RadioGroupDef;
+        menuNode: PopupMenuNode<RadioGroupDef>;
+    } | null;
+}
+type RowNodeDef = ItemDef | RadioItemDef | CheckboxItemDef | SubmenuDef | SubpageDef | TreeItemDef;
+/**
+ * A row node ready for display with its render context.
+ * Used for items, radio items, checkbox items, and submenu triggers.
+ */
+interface DisplayRowNode {
+    kind: 'row';
+    /** The resolved menu node; its authored definition is `node.def`. */
+    node: PopupMenuNode<RowNodeDef>;
+    /** Pre-computed render context for this node */
+    context: RowRenderContext;
+    /** Radio group this node belongs to, if rendering inside one */
+    radioGroup?: {
+        id: string;
+        label?: string;
+    };
+}
+/**
+ * A subpage content node ready for display with its render context.
+ * Used by DataSubpages to render subpage content alongside the root Surface.
+ */
+interface DisplaySubpageNode {
+    /** The resolved node for this subpage. The authored def is `node.def`. */
+    node: PopupMenuNode<SubpageDef>;
+    /** Pre-computed render context for this subpage trigger/content */
+    context: RowRenderContext;
+    /** Computed page ID for this subpage */
+    pageId: string;
+}
+/**
+ * A group node ready for display with its render context.
+ * Contains the group definition and its matching items.
+ */
+interface DisplayGroupNode {
+    kind: 'group';
+    /** The resolved node; authored def at node.def. */
+    node: PopupMenuNode<GroupDef>;
+    /** Pre-computed render context for this group */
+    context: GroupRenderContext;
+    /** Display nodes for items within this group */
+    items: DisplayRowNode[];
+    /** Best match score among items in this group */
+    bestScore: number;
+}
+/**
+ * A radio group node ready for display with its render context.
+ * Contains the radio group definition and its items.
+ */
+interface DisplayRadioGroupNode {
+    kind: 'radio-group';
+    /** The resolved node; authored def at node.def. */
+    node: PopupMenuNode<RadioGroupDef>;
+    /** Pre-computed render context for this radio group */
+    context: GroupRenderContext;
+    /** Display nodes for items within this radio group */
+    items: DisplayRowNode[];
+    /** Best match score among items in this radio group */
+    bestScore: number;
+}
+/**
+ * A separator node ready for display.
+ */
+interface DisplaySeparatorNode {
+    kind: 'separator';
+    /** The resolved node; authored def at node.def. */
+    node: PopupMenuNode<SeparatorDef>;
+}
+/**
+ * Union of all display node types.
+ * Can be a row node (item/submenu/subpage), group node, radio group node, or separator.
+ */
+type DisplayNode = DisplayRowNode | DisplayGroupNode | DisplayRadioGroupNode | DisplaySeparatorNode;
+/**
+ * Type guard for DisplayGroupNode.
+ */
+declare function isDisplayGroupNode(node: DisplayNode): node is DisplayGroupNode;
+/**
+ * Type guard for DisplayRadioGroupNode.
+ */
+declare function isDisplayRadioGroupNode(node: DisplayNode): node is DisplayRadioGroupNode;
+/**
+ * Type guard for DisplaySeparatorNode.
+ */
+declare function isDisplaySeparatorNode(node: DisplayNode): node is DisplaySeparatorNode;
+/**
+ * Type guard for DisplayRowNode (items, checkbox items, submenus, subpages).
+ */
+declare function isDisplayRowNode(node: DisplayNode): node is DisplayRowNode;
+/**
+ * Defines how groups behave during deep search.
+ * - 'flatten': Groups become invisible, items shown in flat list by score.
+ * - 'preserve': Groups are shown as containers with their matching items.
+ * Note: Radio groups are ALWAYS preserved regardless of this setting.
+ */
+type GroupBehavior = 'flatten' | 'preserve';
+/**
+ * Defines how radio groups behave during deep search.
+ * - 'flatten': Radio group items are shown individually in the flat list (not recommended).
+ * - 'preserve': Radio group is shown with only matching items visible.
+ * - 'preserve-show-all': Radio group is shown with ALL items visible when any item matches.
+ *   This is useful when you want users to see all options in a radio group.
+ */
+type RadioGroupBehavior = 'flatten' | 'preserve' | 'preserve-show-all';
+/**
+ * Defines how deep-search async results are revealed.
+ * - 'stream': show available results immediately and append new async batches as they resolve.
+ * - 'block': hide all deep-search rows until every participating async loader resolves.
+ */
+type AsyncResultBehavior = 'stream' | 'block';
+/**
+ * Configuration for deep search behavior.
+ */
+interface DeepSearchConfig {
+    /** Whether deep search is enabled */
+    enabled?: boolean;
+    /** Minimum query length before deep search activates */
+    minLength?: number;
+    /**
+     * How groups behave during search results.
+     * Only affects search mode - groups are always shown in browse mode.
+     * Note: Radio groups have their own behavior controlled by radioGroupSearchBehavior.
+     * @default 'preserve'
+     */
+    groupSearchBehavior?: GroupBehavior;
+    /**
+     * How radio groups behave during search results.
+     * - 'flatten': Radio items shown individually (not recommended).
+     * - 'preserve': Only matching radio items are shown (default).
+     * - 'preserve-show-all': All radio items are shown when any item matches.
+     * @default 'preserve'
+     */
+    radioGroupSearchBehavior?: RadioGroupBehavior;
+    /**
+     * Whether to sort groups by their best-matching item's score.
+     * Only applies when groupSearchBehavior: 'preserve'.
+     * @default true
+     */
+    sortGroups?: boolean;
+    /**
+     * How async deep-search results are revealed.
+     * - 'stream': emit available results immediately, append later async batches (default)
+     * - 'block': show loading state only until all loaders resolve, then render once
+     * @default 'stream'
+     */
+    asyncResultBehavior?: AsyncResultBehavior;
+}
+/**
+ * Props for the DataSurface component.
+ */
+interface DataSurfaceProps {
+    /**
+     * The menu content (node definitions with render functions). Resolved nodes
+     * are accepted anywhere defs are; they are unwrapped to their defs, and
+     * re-supplying the same nodes preserves identity.
+     */
+    content?: NodeDef[] | PopupMenuNode[];
+    /**
+     * Async content configuration for root-level async loading.
+     * When provided, the Loader component will be rendered to fetch async data.
+     * Async content is merged with static content.
+     */
+    asyncContent?: AsyncLoaderConfig;
+    /** Deep search configuration */
+    deepSearch?: DeepSearchConfig | boolean;
+    /**
+     * Default inclusion mode for descendant branch nodes in deep search results.
+     * Submenus/subpages can override via `includeInDeepSearch`.
+     * @default true
+     */
+    includeInDeepSearch?: IncludeInDeepSearch;
+    /** Filter function or false to disable filtering */
+    filter?: ((value: string, search: string, keywords?: string[]) => number) | false;
+    /**
+     * Transforms search input before filtering and visibility logic.
+     * @default trim whitespace (`search.trim()`)
+     */
+    normalizeSearch?: (search: string) => string;
+    /** Controlled search value */
+    search?: string;
+    /** Callback when search value changes */
+    onSearchChange?: (search: string) => void;
+    /** Default search value for uncontrolled usage */
+    defaultSearch?: string;
+    /** Whether navigation should loop */
+    loop?: boolean;
+    /** Auto-highlight behavior when menu opens */
+    autoHighlightFirst?: boolean | string;
+    /**
+     * Whether to clear search on close.
+     * - `true`: clear immediately when menu closes (default)
+     * - `false`: preserve search when menu closes
+     * - `'after-exit'`: clear after exit animation completes
+     */
+    clearSearchOnClose?: boolean | 'after-exit';
+    /**
+     * Whether to reset the list scroll position when the search query changes.
+     * @default true
+     */
+    resetScrollOnSearch?: boolean;
+    /** Children (Input, List, etc.) */
+    children: React.ReactNode;
+}
+/**
+ * State passed to the DataList render function.
+ */
+interface DataListChildrenState {
+    /** Current search query (empty string if browsing) */
+    search: string;
+    /**
+     * Display nodes (filtered and scored if searching).
+     * Can include groups (DisplayGroupNode) or radio groups (DisplayRadioGroupNode)
+     * when groupSearchBehavior: 'preserve'.
+     */
+    nodes: DisplayNode[];
+    /**
+     * Function to render a node.
+     * Handles items, submenus, groups, and radio groups, calling their render functions with context.
+     */
+    renderNode: (displayNode: DisplayNode) => React.ReactNode;
+    /** Number of visible items (counting items inside groups) */
+    count: number;
+    /** Whether deep search is active (query length >= minLength) */
+    isDeepSearching: boolean;
+    /** Aggregate async loading state across all menus */
+    async: AsyncState;
+}
+
+type PopupMenuIdScope = 'menu' | 'surface';
+/**
+ * A menu node: the library-created, resolved instance of a node def.
+ * Exactly one per logical row per menu root, in every render context —
+ * object identity is Resolved ID identity, and `id` is its serialization.
+ * Created by resolution at the root or by grafting; instances are stable
+ * across content re-supplies (reconciliation swaps `def` in place).
+ * The type parameter narrows `def`/`kind` for callers that know the def kind
+ * statically. Narrowing is a lookup-time snapshot: reconcile may replace `def`
+ * in place with another def of the same resolved id, so a long-held narrowed
+ * reference sees the current def, not necessarily the exact object/type it was
+ * looked up with.
+ */
+interface PopupMenuNode<D extends NodeDef = NodeDef> {
+    /** The originating def. Replaced in place when content is re-supplied. */
+    def: D;
+    /** Mirror of `def.kind`, stable for the node's lifetime. */
+    kind: D['kind'];
+    /**
+     * This node's path component: explicit `def.id` verbatim when present,
+     * otherwise the slugified `value` (kinds without a display value use
+     * their required `id`).
+     */
+    definitionKey: string;
+    /**
+     * Definition Path: Definition Keys from the menu root to this node,
+     * including its own key, root-first. Only submenu and subpage ancestors
+     * contribute keys (groups, radio-groups, and tree-items are path-transparent).
+     */
+    definitionPath: string[];
+    /** Resolved ID selected by the root's identity policy. */
+    id: string;
+    parent: PopupMenuNode | null;
+    children: PopupMenuNode[];
+    /** Def-tree depth counting every node kind; roots are 0. */
+    depth: number;
+    /** Sibling index in the def tree (position within `parent.children`). */
+    index: number;
+}
+/**
+ * A menu node before its resolved ID is assigned — the argument to `GetResolvedIdFn`.
+ * Carries definitional facts only (`def`, `definitionKey`, `definitionPath`, resolved
+ * `parent`, `depth`, def-tree sibling `index`). Contextual facts (search
+ * state, deep-search flags, display position) are deliberately absent:
+ * a context-dependent Resolved ID is inexpressible by construction.
+ */
+type UnresolvedMenuNode = Omit<PopupMenuNode, 'id'>;
+/**
+ * Computes a node's Resolved ID from definitional facts. The ID must be unique
+ * per menu root; it is the identity persistent state, registration, and
+ * highlight key off.
+ *
+ * Contract: the id may read the node's own facts (including its own sibling
+ * `index`) and may walk `parent` for lineage (as the default definition-path
+ * rule does), but it must not depend on an *ancestor's* sibling `index` —
+ * reconciliation invalidates ids by def identity and definition path, not by
+ * ancestor reordering, so ancestor-index-dependent ids would go stale. The
+ * seam must also not mutate its argument.
+ */
+type GetResolvedIdFn = (node: UnresolvedMenuNode) => string;
+
+/**
+ * Reasons why a popup menu's open state changed.
+ */
+type PopupMenuOpenChangeReason = typeof triggerPress | typeof triggerHover | typeof triggerFocus | typeof triggerContextMenu | typeof escapeKey | typeof outsidePress | typeof focusOut | typeof itemPress | typeof closePress | typeof listNavigation | typeof submenuTrigger | typeof siblingOpen | typeof imperativeAction | typeof none;
+/**
+ * Event details for popup menu open state changes.
+ */
+type PopupMenuOpenChangeEventDetails = ChangeEventDetails<PopupMenuOpenChangeReason>;
+/**
+ * Reasons why highlight changed.
+ */
+type HighlightChangeReason = typeof pointer | typeof keyboard | typeof auto | typeof none;
+/**
+ * Event details for highlight changes.
+ */
+type HighlightChangeEventDetails = GenericEventDetails<HighlightChangeReason, {
+    index: number;
+}>;
+type PopupMenuHighlightChangeHandler<EventDetails = HighlightChangeEventDetails> = (id: string | null, node: PopupMenuNode | null, index: number, eventDetails: EventDetails) => void;
+/**
+ * Reasons why a checkbox item's checked state changed.
+ */
+type CheckedChangeReason = typeof itemPress | typeof itemKeyboardSelect;
+/**
+ * Event details for checkbox item checked state changes.
+ */
+type CheckedChangeEventDetails = ChangeEventDetails<CheckedChangeReason>;
+/**
+ * Reasons why a radio group's value changed.
+ */
+type RadioValueChangeReason = typeof itemPress | typeof itemKeyboardSelect;
+/**
+ * Event details for radio group value changes.
+ */
+type RadioValueChangeEventDetails = ChangeEventDetails<RadioValueChangeReason>;
+
+export { type CheckboxItemRenderProps as $, type PopupMenuItemProps as A, type PopupMenuItemState as B, type ChangeEventDetails as C, type PopupMenuRadioGroupProps as D, type PopupMenuRadioGroupState as E, type PopupMenuRadioItemProps as F, type GenericEventDetails as G, type PopupMenuRadioItemState as H, type PopupMenuSubmenuTriggerProps as I, type PopupMenuSubmenuTriggerState as J, type PopupMenuSubpageTriggerProps as K, type PopupMenuSubpageTriggerState as L, type AsyncLoaderConfig as M, type NodeDef as N, type AsyncLoaderFetchStatus as O, type PopupMenuHighlightChangeHandler as P, type AsyncLoaderLoadingPhase as Q, type AsyncLoaderResult as R, type AsyncLoaderSource as S, type AsyncLoaderStatus as T, type AsyncNodesConfig as U, type AsyncRenderState as V, type AsyncResultBehavior as W, type AsyncState as X, type BreadcrumbNode as Y, type CheckboxItemDef as Z, type CheckboxItemRenderParams as _, triggerHover as a, type DataListChildrenState as a0, type DeepSearchConfig as a1, type DisplayGroupNode as a2, type DisplayNode as a3, type DisplayRadioGroupNode as a4, type DisplayRowNode as a5, type DisplaySeparatorNode as a6, type DisplaySubpageNode as a7, type GroupBehavior as a8, type GroupDef as a9, type SubmenuRenderParams as aA, type SubmenuRenderProps as aB, type SubpageContentRenderParams as aC, type SubpageDef as aD, type SubpageTriggerRenderParams as aE, type SubpageTriggerRenderProps as aF, type TreeItemDef as aG, type TreeItemRenderParams as aH, type TreeItemRenderProps as aI, type UnresolvedMenuNode as aJ, defineRadioGroup as aK, isDisplayGroupNode as aL, isDisplayRadioGroupNode as aM, isDisplayRowNode as aN, isDisplaySeparatorNode as aO, inputChange as aP, inputClear as aQ, triggerContextMenu as aR, type HighlightChangeEventDetails as aS, type RadioValueChangeEventDetails as aT, type PopupMenuOpenChangeReason as aU, type DataSurfaceProps as aV, type PopupMenuOpenChangeEventDetails as aW, type GroupLabelRenderParams as aa, type GroupRenderContext as ab, type GroupRenderParams as ac, type IncludeInDeepSearch as ad, type InitialQueryBehavior as ae, type ItemDef as af, type ItemRenderParams as ag, type ItemRenderProps as ah, type LoaderComponentProps as ai, type QueryAsyncNodesConfig as aj, type QueryLoaderConfig as ak, type RadioGroupBehavior as al, type RadioGroupDef as am, type RadioGroupLabelRenderParams as an, type RadioGroupRenderParams as ao, type RadioGroupRenderProps as ap, type RadioItemDef as aq, type RadioItemRenderParams as ar, type RadioItemRenderProps as as, type RowRenderContext as at, type ScoredNode as au, type SeparatorDef as av, type SeparatorRenderParams as aw, type StaticAsyncNodesConfig as ax, type StaticLoaderConfig as ay, type SubmenuDef as az, triggerFocus as b, closePress as c, siblingOpen as d, escapeKey as e, focusOut as f, imperativeAction as g, type GetResolvedIdFn as h, itemPress as i, type PopupMenuIdScope as j, keyboard as k, listNavigation as l, PopupMenuCheckboxItem as m, none as n, outsidePress as o, pointer as p, PopupMenuItem as q, type PopupMenuNode as r, submenuTrigger as s, triggerPress as t, PopupMenuRadioGroup as u, PopupMenuRadioItem as v, PopupMenuSubmenuTrigger as w, PopupMenuSubpageTrigger as x, type PopupMenuCheckboxItemProps as y, type PopupMenuCheckboxItemState as z };