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

package/dist/types-lQCIvWW8.d.ts

@@ -0,0 +1,1557 @@
+import * as React from 'react';
+import { u as CheckedChangeEventDetails, r as RadioValueChangeEventDetails } from './events-BPr8sRGH.js';
+
+/**
+ * Render function that receives props and state, returns a React element.
+ */
+type ComponentRenderFn<Props, State> = (props: Props, state: State) => React.ReactElement<unknown>;
+/**
+ * HTML props with ref support.
+ */
+type HTMLProps<T = any> = React.HTMLAttributes<T> & {
+    ref?: React.Ref<T> | undefined;
+};
+/**
+ * Props shared by all Bazza UI components.
+ * Includes className (string or state-based function), render prop, and style (object or state-based function).
+ */
+type ComponentProps<ElementType extends React.ElementType, State, RenderFunctionProps = HTMLProps> = Omit<React.ComponentPropsWithRef<ElementType>, 'className' | 'color' | 'defaultValue' | 'defaultChecked'> & {
+    /**
+     * CSS class applied to the element, or a function that
+     * returns a class based on the component's state.
+     */
+    className?: string | ((state: State) => string | undefined);
+    /**
+     * Allows you to replace the component's HTML element
+     * with a different tag, or compose it with another component.
+     *
+     * Accepts a `ReactElement` or a function that returns the element to render.
+     */
+    render?: ComponentRenderFn<RenderFunctionProps, State> | React.ReactElement;
+    /**
+     * Style applied to the element, or a function that
+     * returns a style object based on the component's state.
+     */
+    style?: React.CSSProperties | ((state: State) => React.CSSProperties | undefined);
+};
+
+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;
+}
+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;
+    /**
+     * 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;
+}
+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;
+    /**
+     * 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;
+}
+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;
+}
+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;
+}
+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;
+    /**
+     * 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;
+}
+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-dependent 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-dependent loader configuration.
+ * Refetches based on search query - server does the filtering.
+ */
+interface QueryDependentLoaderConfig {
+    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 | QueryDependentLoaderConfig;
+/**
+ * Static async nodes configuration for submenus.
+ */
+type StaticAsyncNodesConfig = StaticLoaderConfig;
+/**
+ * Query-dependent async nodes configuration for submenus.
+ */
+type QueryAsyncNodesConfig = QueryDependentLoaderConfig;
+/**
+ * Async nodes configuration for submenus.
+ * Union of static and query-dependent 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<{
+        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;
+    /** The branch node's value */
+    value: string;
+    /** The branch node's explicit id (if provided) */
+    id?: string;
+}
+/**
+ * Context passed to the getQualifiedRowId function.
+ * Provides all information needed to generate a unique ID for a row.
+ */
+interface GetQualifiedRowIdContext {
+    /** The node definition */
+    node: ItemDef | RadioItemDef | CheckboxItemDef | SubmenuDef | SubpageDef;
+    /** The node's value (node.value) - used for search/filtering and as fallback identifier */
+    value: string;
+    /** The node's explicit id (node.id) - if provided, treated as globally unique */
+    id: string | undefined;
+    /** Position in the flattened display list (0-based) */
+    index: number;
+    /**
+     * Breadcrumb nodes from root to parent.
+     * Contains full submenu/subpage node definitions for maximum flexibility.
+     */
+    breadcrumbs: BreadcrumbNode[];
+    /** Whether deep search is currently active (search query meets minLength threshold) */
+    isDeepSearching: boolean;
+    /** Search context, null if browsing */
+    search: {
+        query: string;
+        score: number;
+    } | null;
+    /** Whether surfaced via deep search (rendered outside its home menu) */
+    isDeepSearchResult: boolean;
+    /** Group context, if any */
+    group: {
+        id: string;
+        label?: string;
+    } | null;
+    /** Radio group context, if any */
+    radioGroup: {
+        id: string;
+        label?: string;
+    } | null;
+}
+/**
+ * Function that generates a unique qualified ID for a row.
+ * Used for React keys, store registration, and DOM id attributes.
+ *
+ * Default behavior:
+ * - If node.id is provided, use it as-is (treat as globally unique)
+ * - Otherwise, compute from breadcrumbs + value when deep searching
+ *
+ * @example
+ * ```ts
+ * // Custom implementation
+ * const getQualifiedRowId: GetQualifiedRowIdFn = (ctx) => {
+ *   // Use explicit id if provided
+ *   if (ctx.id) return ctx.id
+ *
+ *   // Otherwise, build from breadcrumbs + value
+ *   const path = ctx.breadcrumbs.map(b => b.id ?? slugify(b.value))
+ *   return [...path, slugify(ctx.value)].join('.')
+ * }
+ * ```
+ */
+type GetQualifiedRowIdFn = (context: GetQualifiedRowIdContext) => 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;
+}
+/**
+ * Props to spread onto the Item component.
+ * Derived from PopupMenuItemProps.
+ */
+type ItemRenderProps = {
+    /**
+     * Qualified unique ID for the item.
+     * Must be passed to the rendered component for navigation to work.
+     * This is the computed qualified ID (includes breadcrumb path for deep search results).
+     */
+    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 {
+    /** 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 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 {
+    /** 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 {
+    /** 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 submenu's static child node definitions.
+     * Does NOT include async results - use `asyncContent` for that.
+     */
+    nodes: NodeDef[];
+    /**
+     * 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;
+    /**
+     * Function to render a child node.
+     * Call this for each node in the submenu's list.
+     */
+    renderNode: (node: NodeDef) => 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 {
+    /** 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 {
+    /** Computed page ID for this subpage */
+    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 subpage's static child node definitions.
+     * Does NOT include async results - use `asyncContent` for that.
+     */
+    nodes: NodeDef[];
+    /**
+     * 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;
+    /**
+     * Function to render a child node.
+     * Call this for each node in the subpage's list.
+     */
+    renderNode: (node: NodeDef) => 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 {
+    /** 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;
+}
+/**
+ * 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 {
+    /** 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 {
+    /** 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;
+}
+/**
+ * Base properties shared by all node types.
+ */
+interface BaseNodeDef {
+    /**
+     * Unique identifier for this node.
+     * If not provided, a composite ID is generated from the `value` and breadcrumbs
+     * using the `getItemId` function.
+     */
+    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;
+}
+/**
+ * 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';
+    /**
+     * Optional explicit page ID for this subpage.
+     * If omitted, a deterministic page ID is generated from id/value + breadcrumbs.
+     */
+    pageId?: string;
+    /** 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';
+    /** Optional 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 | 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 original node definition */
+    node: ItemDef | RadioItemDef | CheckboxItemDef | SubmenuDef | SubpageDef;
+    /** 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;
+    } | null;
+    /** The radio group this node belongs to, if any */
+    radioGroup: {
+        id: string;
+        label?: string;
+        radioGroupDef: RadioGroupDef;
+    } | null;
+}
+/**
+ * A row node ready for display with its render context.
+ * Used for items, radio items, checkbox items, and submenu triggers.
+ */
+interface DisplayRowNode {
+    /** The original node definition */
+    node: ItemDef | RadioItemDef | CheckboxItemDef | SubmenuDef | SubpageDef;
+    /** Pre-computed render context for this node */
+    context: RowRenderContext;
+    /** Radio group this node belongs to, if rendering inside one */
+    radioGroup?: {
+        id: string;
+        label?: string;
+    };
+    /**
+     * Computed composite ID for this node.
+     * Includes breadcrumb path for deep search results (e.g., "status.in-progress").
+     * Set after filtering via `computeItemIds`.
+     */
+    compositeId?: 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 original subpage definition */
+    node: 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 group definition */
+    group: 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 radio group definition */
+    radioGroup: 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 separator definition */
+    separator: 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) */
+    content?: NodeDef[];
+    /**
+     * 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';
+    /**
+     * Function to generate qualified IDs for row items.
+     * Called for each item when rendering to produce IDs for:
+     * - React keys
+     * - Store registration
+     * - DOM id attributes
+     *
+     * @default Uses node.id if provided, otherwise qualifies with breadcrumbs + slugified value
+     */
+    getQualifiedRowId?: GetQualifiedRowIdFn;
+    /** 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;
+}
+/**
+ * Props for the DataList component.
+ */
+interface DataListProps {
+    /**
+     * Render function for the list content.
+     * Receives the current state and returns JSX.
+     */
+    children: (state: DataListChildrenState) => React.ReactNode;
+    /** Accessible label for the listbox */
+    label?: string;
+    /** Additional class name */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+    /**
+     * 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;
+}
+/**
+ * State passed to the DataSubpages render function.
+ */
+interface DataSubpagesChildrenState {
+    /** All subpage content nodes discovered in the current content tree. */
+    subpages: DisplaySubpageNode[];
+    /**
+     * Function to render a subpage content node.
+     * Calls the node's `renderContent` callback with page context and child renderer.
+     */
+    renderSubpageContent: (subpage: DisplaySubpageNode) => React.ReactNode;
+}
+/**
+ * Props for the DataSubpages component.
+ */
+interface DataSubpagesProps {
+    /**
+     * Optional render function.
+     * If omitted, all subpage contents are rendered by default.
+     */
+    children?: (state: DataSubpagesChildrenState) => React.ReactNode;
+}
+
+export { type ItemRenderParams as $, type AsyncLoaderConfig as A, type BreadcrumbNode as B, type ComponentProps as C, type CheckboxItemDef as D, type CheckboxItemRenderParams as E, type CheckboxItemRenderProps as F, type GetQualifiedRowIdFn as G, type DataListChildrenState as H, type DataListProps as I, type DataSubpagesChildrenState as J, type DataSubpagesProps as K, type DataSurfaceProps as L, type DeepSearchConfig as M, type DisplayGroupNode as N, type DisplayNode as O, PopupMenuCheckboxItem as P, type DisplayRadioGroupNode as Q, type DisplayRowNode as R, type DisplaySeparatorNode as S, type DisplaySubpageNode as T, type GroupBehavior as U, type GroupDef as V, type GroupRenderContext as W, type GroupRenderParams as X, type IncludeInDeepSearch as Y, type InitialQueryBehavior as Z, type ItemDef as _, PopupMenuItem as a, type ItemRenderProps as a0, type LoaderComponentProps as a1, type NodeDef as a2, type QueryAsyncNodesConfig as a3, type QueryDependentLoaderConfig as a4, type RadioGroupBehavior as a5, type RadioGroupDef as a6, type RadioGroupRenderParams as a7, type RadioGroupRenderProps as a8, type RadioItemDef as a9, type RadioItemRenderParams as aa, type RadioItemRenderProps as ab, type RowRenderContext as ac, type ScoredNode as ad, type SeparatorDef as ae, type SeparatorRenderParams as af, type StaticAsyncNodesConfig as ag, type StaticLoaderConfig as ah, type SubmenuDef as ai, type SubmenuRenderParams as aj, type SubmenuRenderProps as ak, type SubpageContentRenderParams as al, type SubpageDef as am, type SubpageTriggerRenderParams as an, type SubpageTriggerRenderProps as ao, defineRadioGroup as ap, isDisplayGroupNode as aq, isDisplayRadioGroupNode as ar, isDisplayRowNode as as, isDisplaySeparatorNode as at, type GetQualifiedRowIdContext as au, type ComponentRenderFn as av, PopupMenuRadioGroup as b, PopupMenuRadioItem as c, PopupMenuSubmenuTrigger as d, PopupMenuSubpageTrigger as e, type PopupMenuCheckboxItemProps as f, type PopupMenuCheckboxItemState as g, type PopupMenuItemProps as h, type PopupMenuItemState as i, type PopupMenuRadioGroupProps as j, type PopupMenuRadioGroupState as k, type PopupMenuRadioItemProps as l, type PopupMenuRadioItemState as m, type PopupMenuSubmenuTriggerProps as n, type PopupMenuSubmenuTriggerState as o, type PopupMenuSubpageTriggerProps as p, type PopupMenuSubpageTriggerState as q, type AsyncLoaderFetchStatus as r, type AsyncLoaderLoadingPhase as s, type AsyncLoaderResult as t, type AsyncLoaderSource as u, type AsyncLoaderStatus as v, type AsyncNodesConfig as w, type AsyncRenderState as x, type AsyncResultBehavior as y, type AsyncState as z };